juneau-doc/docs/Topics/19.Glossaries/02.Annotations.html

<!--
/***************************************************************************************************************************
 * Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information regarding copyright ownership.  The ASF licenses this file
 * to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance
 * with the License.  You may obtain a copy of the License at
 *  
 *  http://www.apache.org/licenses/LICENSE-2.0
 *  
 * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the License for the
 * specific language governing permissions and limitations under the License.
 ***************************************************************************************************************************/
 -->

{8.1.3-new} 
Annotations

<h5 class='figure'>Serialization Annotations (used to modify how artifacts are marshalled)</h5>
<table class='styled w1000'>
	<tr>
		<th>Annotation</th><th>Description</th><th>Used On</th><th>Used By</th>
	</tr>
	<tr>
		<td><ul style='margin-left:20px'><li class='ja'>{@link oaj.annotation.Bean}</ul></td>
		<td><ul><li>Classes</ul></td>
		<td>All serializers and parsers</td>
		<td>Tailors how beans get marshalled.</td>
	</tr>
	<tr>
		<td><ul style='margin-left:20px'><li class='ja'>{@link oaj.annotation.Beanc}</ul></td>
		<td><ul><li>Bean constructors</ul></td>
		<td>All serializers and parsers</td>
		<td>Identifies bean constructors and property args.</td>
	</tr>
	<tr>
		<td><ul style='margin-left:20px'><li class='ja'>{@link oaj.annotation.BeanIgnore}</ul></td>
		<td><ul><li>Classes<li>Fields<li>Methods</ul></td>
		<td>All serializers and parsers</td>
		<td>Prevents artifacts from being interpreted as beans/bean components.</td>
	</tr>
	<tr>
		<td><ul style='margin-left:20px'><li class='ja'>{@link oaj.annotation.Beanp}</ul></td>
		<td><ul><li>Methods<li>Fields<li>Constructor args</ul></td>
		<td>All serializers and parsers</td>
		<td>Tailors how bean properties get marshalled.</td>
	</tr>
	<tr>
		<td><ul style='margin-left:20px'><li class='ja'>{@link oaj.annotation.Builder}</ul></td>
		<td><ul><li>Classes</ul></td>
		<td>All parsers</td>
		<td>Identifies a class as a builder for a POJO class.</td>
	</tr>
	<tr>
		<td><ul style='margin-left:20px'><li class='ja'>{@link oaj.csv.annotation.Csv}</ul></td>
		<td><ul><li>Classes<li>Methods<li>Fields</ul></td>
		<td><ul><li class='jc'>{@link oaj.csv.CsvSerializer}<li class='jc'>{@link oaj.csv.CsvParser}</ul></td>
		<td>CSV-specific tweaks.</td>
	</tr>
	<tr>
		<td><ul style='margin-left:20px'><li class='ja'>{@link oaj.annotation.Example}</ul></td>
		<td><ul><li>Static methods<li>Static fields<li>Classes</ul></td>
		<td><ul><li class='jc'>{@link oaj.json.JsonSchemaSerializer}</ul></td>
		<td>Identifies examples for POJOs.</td>
	</tr>
	<tr>
		<td><ul style='margin-left:20px'><li class='ja'>{@link oaj.html.annotation.Html}</ul></td>
		<td><ul><li>Classes<li>Methods<li>Fields</ul></td>
		<td><ul><li class='jc'>{@link oaj.html.HtmlSerializer}<li class='jc'>{@link oaj.html.HtmlParser}</ul></td>
		<td>HTML-specific tweaks.</td>
	</tr>
	<tr>
		<td><ul style='margin-left:20px'><li class='ja'>{@link oaj.html.annotation.HtmlLink}</ul></td>
		<td><ul><li>Classes</ul></td>
		<td><ul><li class='jc'>{@link oaj.html.HtmlSerializer}</ul></td>
		<td>Defines how to construct hyperlinks on objects.</td>
	</tr>
	<tr>
		<td><ul style='margin-left:20px'><li class='ja'>{@link oaj.jso.annotation.Jso}</ul></td>
		<td><ul><li>Classes<li>Methods<li>Fields</ul></td>
		<td><ul><li class='jc'>{@link oaj.jso.JsoSerializer}<li class='jc'>{@link oaj.jso.JsoParser}</ul></td>
		<td>JSO-specific tweaks.</td>
	</tr>
	<tr>
		<td><ul style='margin-left:20px'><li class='ja'>{@link oaj.json.annotation.Json}</ul></td>
		<td><ul><li>Classes<li>Methods<li>Fields</ul></td>
		<td><ul><li class='jc'>{@link oaj.json.JsonSerializer}<li class='jc'>{@link oaj.json.JsonParser}</ul></td>
		<td>JSON-specific tweaks.</td>
	</tr>
	<tr>
		<td><ul style='margin-left:20px'><li class='ja'>{@link oaj.msgpack.annotation.MsgPack}</ul></td>
		<td><ul><li>Classes<li>Methods<li>Fields</ul></td>
		<td><ul><li class='jc'>{@link oaj.msgpack.MsgPackSerializer}<li class='jc'>{@link oaj.msgpack.MsgPackParser}</ul></td>
		<td>MessagePack-specific tweaks.</td>
	</tr>
	<tr>
		<td><ul style='margin-left:20px'><li class='ja'>{@link oaj.annotation.Name}</ul></td>
		<td><ul><li>Constructor args</ul></td>
		<td>All parsers</td>
		<td>Maps constructor args to property names.</td>
	</tr>
	<tr>
		<td><ul style='margin-left:20px'><li class='ja'>{@link oaj.annotation.NameProperty}</ul></td>
		<td><ul><li>Methods<li>Fields</ul></td>
		<td>All parsers</td>
		<td>Identifies a 'name' property.</td>
	</tr>
	<tr>
		<td><ul style='margin-left:20px'><li class='ja'>{@link oaj.oapi.annotation.OpenApi}</ul></td>
		<td><ul><li>Classes<li>Methods<li>Fields</ul></td>
		<td><ul><li class='jc'>{@link oaj.oapi.OpenApiSerializer}<li class='jc'>{@link oaj.oapi.OpenApiParser}</ul></td>
		<td>OpenAPI-specific tweaks.</td>
	</tr>
	<tr>
		<td><ul style='margin-left:20px'><li class='ja'>{@link oaj.annotation.ParentProperty}</ul></td>
		<td><ul><li>Methods<li>Fields</ul></td>
		<td>All parsers</td>
		<td>Identifies a 'parent' property.</td>
	</tr>
	<tr>
		<td><ul style='margin-left:20px'><li class='ja'>{@link oaj.plaintext.annotation.PlainText}</ul></td>
		<td><ul><li>Classes<li>Methods<li>Fields</ul></td>
		<td><ul><li class='jc'>{@link oaj.plaintext.PlainTextSerializer}<li class='jc'>{@link oaj.plaintext.PlainTextParser}</ul></td>
		<td>PlainText-specific tweaks.</td>
	</tr>
	<tr>
		<td><ul style='margin-left:20px'><li class='ja'>{@link oaj.jena.annotation.Rdf}</ul></td>
		<td><ul><li>Classes<li>Methods<li>Fields</ul></td>
		<td>All RDF serializers and parsers</td>
		<td>RDF-specific tweaks.</td>
	</tr>
	<tr>
		<td><ul style='margin-left:20px'><li class='ja'>{@link oaj.jena.annotation.RdfSchema}</ul></td>
		<td><ul><li>Packages</ul></td>
		<td>All RDF serializers and parsers</td>
		<td>Identifies the default RDF namespaces at the package level.</td>
	</tr>
	<tr>
		<td><ul style='margin-left:20px'><li class='ja'>{@link oaj.soap.annotation.SoapXml}</ul></td>
		<td><ul><li>Classes<li>Methods<li>Fields</ul></td>
		<td><ul><li class='jc'>{@link oaj.soap.SoapXmlSerializer}</ul></td>
		<td>SOAP/XML-specific tweaks.</td>
	</tr>
	<tr>
		<td><ul style='margin-left:20px'><li class='ja'>{@link oaj.annotation.Swap}</ul></td>
		<td><ul><li>Classes<li>Bean getters/setters<li>Fields</ul></td>
		<td>All serializers and parsers</td>
		<td>Associates swaps and surrogates with POJOs and bean properties.</td>
	</tr>
	<tr>
		<td><ul style='margin-left:20px'><li class='ja'>{@link oaj.annotation.Swaps}</ul></td>
		<td><ul><li>Classes</ul></td>
		<td>All serializers and parsers</td>
		<td>Associates multiple swaps with the same POJO class.</td>
	</tr>
	<tr>
		<td><ul style='margin-left:20px'><li class='ja'>{@link oaj.uon.annotation.Uon}</ul></td>
		<td><ul><li>Classes<li>Methods<li>Fields</ul></td>
		<td><ul><li class='jc'>{@link oaj.uon.UonSerializer}<li class='jc'>{@link oaj.uon.UonParser}</ul></td>
		<td>UON-specific tweaks.</td>
	</tr>
	<tr>
		<td><ul style='margin-left:20px'><li class='ja'>{@link oaj.annotation.URI}</ul></td>
		<td><ul><li>Classes<li>Methods<li>Fields</ul></td>
		<td>HTML and XML serializers</td>
		<td>Identifies a class or bean property as a URI.</td>
	</tr>
	<tr>
		<td><ul style='margin-left:20px'><li class='ja'>{@link oaj.urlencoding.annotation.UrlEncoding}</ul></td>
		<td><ul><li>Classes<li>Methods<li>Fields</ul></td>
		<td><ul><li class='jc'>{@link oaj.urlencoding.UrlEncodingSerializer}<li class='jc'>{@link oaj.urlencoding.UrlEncodingParser}</ul></td>
		<td>URL-Encoding-specific tweaks.</td>
	</tr>
	<tr>
		<td><ul style='margin-left:20px'><li class='ja'>{@link oaj.xml.annotation.Xml}</ul></td>
		<td><ul><li>Classes<li>Methods<li>Fields</ul></td>
		<td><ul><li class='jc'>{@link oaj.xml.XmlSerializer}<li class='jc'>{@link oaj.xml.XmlParser}</ul></td>
		<td>XML-specific tweaks.</td>
	</tr>
	<tr>
		<td><ul style='margin-left:20px'><li class='ja'>{@link oaj.xml.annotation.XmlSchema}</ul></td>
		<td><ul><li>Packages</ul></td>
		<td>XML serializers and parsers</td>
		<td>Identifies the default XML namespaces at the package level.</td>
	</tr>
</table>
<br><br>

<h5 class='figure'>Configuration Annotations (used to modify how serializers/parsers behave)</h5>
<table class='styled w800'>
	<tr>
		<th>Annotation</th><th>Configures</th>
	</tr>
	<tr>
		<td><ul style='margin-left:20px'><li class='ja'>{@link oaj.annotation.BeanConfig}</ul></td>
		<td>All serializers and parsers</td>
	</tr>
	<tr>
		<td><ul style='margin-left:20px'><li class='ja'>{@link oaj.csv.annotation.CsvConfig}</ul></td>
		<td><ul><li class='jc'>{@link oaj.csv.CsvSerializer}<li class='jc'>{@link oaj.csv.CsvParser}</ul></td>
	</tr>
	<tr>
		<td><ul style='margin-left:20px'><li class='ja'>{@link oaj.html.annotation.HtmlConfig}</ul></td>
		<td><ul><li class='jc'>{@link oaj.html.HtmlSerializer}<li class='jc'>{@link oaj.html.HtmlParser}</ul></td>
	</tr>
	<tr>
		<td><ul style='margin-left:20px'><li class='ja'>{@link oaj.html.annotation.HtmlDocConfig}</ul></td>
		<td><ul><li class='jc'>{@link oaj.html.HtmlDocSerializer}</ul></td>
	</tr>
	<tr>
		<td><ul style='margin-left:20px'><li class='ja'>{@link oaj.jso.annotation.JsoConfig}</ul></td>
		<td><ul><li class='jc'>{@link oaj.jso.JsoSerializer}<li class='jc'>{@link oaj.jso.JsoParser}</ul></td>
	</tr>
	<tr>
		<td><ul style='margin-left:20px'><li class='ja'>{@link oaj.json.annotation.JsonConfig}</ul></td>
		<td><ul><li class='jc'>{@link oaj.json.JsonSerializer}<li class='jc'>{@link oaj.json.JsonParser}</ul></td>
	</tr>
	<tr>
		<td><ul style='margin-left:20px'><li class='ja'>{@link oaj.jsonschema.annotation.JsonSchemaConfig}</ul></td>
		<td><ul><li class='jc'>{@link oaj.json.JsonSchemaSerializer}</ul></td>
	</tr>
	<tr>
		<td><ul style='margin-left:20px'><li class='ja'>{@link oaj.msgpack.annotation.MsgPackConfig}</ul></td>
		<td><ul><li class='jc'>{@link oaj.msgpack.MsgPackSerializer}<li class='jc'>{@link oaj.msgpack.MsgPackParser}</ul></td>
	</tr>
	<tr>
		<td><ul style='margin-left:20px'><li class='ja'>{@link oaj.oapi.annotation.OpenApiConfig}</ul></td>
		<td><ul><li class='jc'>{@link oaj.oapi.OpenApiSerializer}<li class='jc'>{@link oaj.oapi.OpenApiParser}</ul></td>
	</tr>
	<tr>
		<td><ul style='margin-left:20px'><li class='ja'>{@link oaj.parser.annotation.ParserConfig}</ul></td>
		<td>All parsers</td>
	</tr>
	<tr>
		<td><ul style='margin-left:20px'><li class='ja'>{@link oaj.plaintext.annotation.PlainTextConfig}</ul></td>
		<td><ul><li class='jc'>{@link oaj.plaintext.PlainTextSerializer}</ul></td>
	</tr>
	<tr>
		<td><ul style='margin-left:20px'><li class='ja'>{@link oaj.jena.annotation.RdfConfig}</ul></td>
		<td>All RDF serializers and parsers</td>
	</tr>
	<tr>
		<td><ul style='margin-left:20px'><li class='ja'>{@link oaj.serializer.annotation.SerializerConfig}</ul></td>
		<td>All serializers</td>
	</tr>
	<tr>
		<td><ul style='margin-left:20px'><li class='ja'>{@link oaj.soap.annotation.SoapXmlConfig}</ul></td>
		<td><ul><li class='jc'>{@link oaj.soap.SoapXmlSerializer}</ul></td>
	</tr>
	<tr>
		<td><ul style='margin-left:20px'><li class='ja'>{@link oaj.uon.annotation.UonConfig}</ul></td>
		<td><ul><li class='jc'>{@link oaj.uon.UonSerializer}<li class='jc'>{@link oaj.uon.UonParser}</ul></td>
	</tr>
	<tr>
		<td><ul style='margin-left:20px'><li class='ja'>{@link oaj.urlencoding.annotation.UrlEncodingConfig}</ul></td>
		<td><ul><li class='jc'>{@link oaj.urlencoding.UrlEncodingSerializer}<li class='jc'>{@link oaj.urlencoding.UrlEncodingParser}</ul></td>
	</tr>
	<tr>
		<td><ul style='margin-left:20px'><li class='ja'>{@link oaj.xml.annotation.XmlConfig}</ul></td>
		<td><ul><li class='jc'>{@link oaj.xml.XmlSerializer}<li class='jc'>{@link oaj.xml.XmlParser}</ul></td>
	</tr>
</table>
<br><br>

<h5 class='figure'>Common REST Annotations (used on both client-side and server-side)</h5>
<table class='styled w800'>
	<tr>
		<th>Annotation</th><th>Used On</th><th>Description</th>
	</tr>
	<tr>
		<td><ul style='margin-left:20px'><li class='ja'>{@link oaj.http.annotation.Body}</ul></td>
		<td><ul><li>Classes<li>Methods<li>Fields<li>Parameters</ul></td>
		<td>HTTP request/response body.</td>
	</tr>
	<tr>
		<td><ul style='margin-left:20px'><li class='ja'>{@link oaj.http.annotation.FormData}</ul></td>
		<td><ul><li>Classes<li>Methods<li>Fields<li>Parameters</ul></td>
		<td>HTTP form data parameter.</td>
	</tr>
	<tr>
		<td><ul style='margin-left:20px'><li class='ja'>{@link oaj.http.annotation.HasFormData}</ul></td>
		<td><ul><li>Classes<li>Methods<li>Fields<li>Parameters</ul></td>
		<td>HTTP form data parameter is present.</td>
	</tr>
	<tr>
		<td><ul style='margin-left:20px'><li class='ja'>{@link oaj.http.annotation.HasQuery}</ul></td>
		<td><ul><li>Classes<li>Methods<li>Fields<li>Parameters</ul></td>
		<td>HTTP query parameter is present.</td>
	</tr>
	<tr>
		<td><ul style='margin-left:20px'><li class='ja'>{@link oaj.http.annotation.Header}</ul></td>
		<td><ul><li>Classes<li>Methods<li>Fields<li>Parameters</ul></td>
		<td>HTTP header.</td>
	</tr>
	<tr>
		<td><ul style='margin-left:20px'><li class='ja'>{@link oaj.http.annotation.Path}</ul></td>
		<td><ul><li>Classes<li>Methods<li>Fields<li>Parameters</ul></td>
		<td>HTTP path part.</td>
	</tr>
	<tr>
		<td><ul style='margin-left:20px'><li class='ja'>{@link oaj.http.annotation.Query}</ul></td>
		<td><ul><li>Classes<li>Methods<li>Fields<li>Parameters</ul></td>
		<td>HTTP query parameter.</td>
	</tr>
	<tr>
		<td><ul style='margin-left:20px'><li class='ja'>{@link oaj.http.annotation.Request}</ul></td>
		<td><ul><li>Classes<li>Parameters</ul></td>
		<td>Identifies an interface to use to interact with HTTP parts of an HTTP request through a bean.</td>
	</tr>
	<tr>
		<td><ul style='margin-left:20px'><li class='ja'>{@link oaj.http.annotation.Response}</ul></td>
		<td><ul><li>Classes<li>Methods<li>Parameters</ul></td>
		<td>Identifies an interface to use to interact with HTTP parts of an HTTP response through a bean.</td>
	</tr>
	<tr>
		<td><ul style='margin-left:20px'><li class='ja'>{@link oaj.http.annotation.ResponseBody}</ul></td>
		<td><ul><li>Methods</ul></td>
		<td>Denotes a method as an HTTP response body on a <ja>@Response</ja>-annotated bean.</td>
	</tr>
	<tr>
		<td><ul style='margin-left:20px'><li class='ja'>{@link oaj.http.annotation.ResponseHeader}</ul></td>
		<td><ul><li>Classes<li>Methods<li>Parameters</ul></td>
		<td>Denotes a method as an HTTP response header on a <ja>@Response</ja>-annotated bean.</td>
	</tr>
	<tr>
		<td><ul style='margin-left:20px'><li class='ja'>{@link oaj.http.annotation.ResponseStatus}</ul></td>
		<td><ul><li>Methods<li>Parameters</ul></td>
		<td>Denotes a method as an HTTP response status code on a <ja>@Response</ja>-annotated bean.</td>
	</tr>
</table>
<br><br>

<h5 class='figure'>REST Server-only Annotations</h5>
<table class='styled w800'>
	<tr>
		<th>Annotation</th><th>Used On</th><th>Description</th>
	</tr>
	<tr>
		<td><ul style='margin-left:20px'><li class='ja'>{@link oaj.rest.annotation.Attr}</ul></td>
		<td><ul><li>Parameters</ul></td>
		<td>Request attribute.</td>
	</tr>
	<tr>
		<td><ul style='margin-left:20px'><li class='ja'>{@link oaj.rest.annotation.Rest}</ul></td>
		<td><ul><li>Classes</ul></td>
		<td>Identifies and configures REST resource classes.</td>
	</tr>
	<tr>
		<td><ul style='margin-left:20px'><li class='ja'>{@link oaj.rest.annotation.RestHook}</ul></td>
		<td><ul><li>Methods</ul></td>
		<td>Identifies REST lifecycle hook methods.</td>
	</tr>
	<tr>
		<td><ul style='margin-left:20px'><li class='ja'>{@link oaj.rest.annotation.RestMethod}</ul></td>
		<td><ul><li>Methods</ul></td>
		<td>Identifies and configures REST resource class methods.</td>
	</tr>
</table>
<br><br>