Juneau uses {@link oaj.parser.Parser Parsers} and {@link oaj.serializer.Serializer Serializers} for marshalling
HTTP request and response bodies to POJOs using the Content-Type header to match the best
parser and the Accept header to match the best serializer.
Serializers and parsers can be associated with REST servlets using the following annotations:
- {@link oajr.annotation.Rest}
- {@link oajr.annotation.Rest#serializers() serializers}
- {@link oajr.annotation.Rest#serializers() parsers}
- {@link oajr.annotation.RestOp}
- {@link oajr.annotation.RestOp#serializers() serializers}
- {@link oajr.annotation.RestOp#serializers() parsers}
Request bodies are parsed and passed in via {@link oaj.http.annotation.Content @Content}-annotated parameters,
and response bodies are returned or thrown by {@link oajr.annotation.RestOp @RestOp}-annotated methods
and serialized.
| @Rest(
| serializers={JsonParser.class, HtmlSerializer.class},
| parsers={JsonParser.class, HtmlParser.class}
| )
| public class MyResource {
|
| // Override at the method level.
| @RestPost(parsers={XmlParser.class})
| public MyPojo myMethod(@Content MyPojo myPojo) {
| // Do something with your parsed POJO.
| // Then return it and serialize the POJO.
| }
| }
The following classes provide common default serializers and parsers that can be
used as-is or augmented by child classes:
- Classes:
- {@link oajr.servlet.BasicRestServlet}
- {@link oajr.servlet.BasicRestServletGroup}
- {@link oajr.servlet.BasicRestObject}
- {@link oajr.servlet.BasicRestObjectGroup}
- Interfaces:
- {@link oajr.config.BasicJsonConfig}
- {@link oajr.config.BasicJsonHtmlConfig}
- {@link oajr.config.BasicSimpleJsonConfig}
- {@link oajr.config.BasicOpenApiConfig}
- {@link oajr.config.BasicUniversalConfig}
- {@link oajr.config.BasicUniversalJenaConfig}
Serializers and parsers can also be defined programmatically using an INIT hook method like shown below:
| @Rest
| public class MyResource {
|
| @RestHook(INIT)
| public void init(RestContext.Builder builder) {
| builder.serializers().add(JsonSerializer.class, HtmlSerializer.class);
| builder.parsers().add(JsonParser.class, HtmlParser.class);
| }
| }
They can also be defined through {@doc jrs.RestContext custom REST context and builders}.
Config annotations allow you to define serializer and parser properties using specialized annotations
at either the class or operation levels:
| @Rest(
| ...
| )
| @BeanConfig(sortProperties="true")
| @SerializerConfig(trimNulls="true")
| @JsonConfig(escapeSolidus="true")
| public class MyResource extends BasicRestServlet implements BasicUniversalConfig {
|
| @RestPost
| @BeanConfig(sortProperties="false")
| @SerializerConfig(trimNulls="false")
| public MyPojo myMethod(@Content MyPojo myPojo) {
| ...
| }
| }
Swaps are associated serializers and parsers registered on a REST resource via the {@link oaj.annotation.BeanConfig} annotation
on either the class or method level:
| // Servlet with transforms applied
| @Rest(
| ...
| )
| @BeanConfig(
| swaps={
| // Calendars should be serialized/parsed as ISO8601 date-time strings
| TemporalCalendarSwap.IsoInstant.class,
|
| // Byte arrays should be serialized/parsed as BASE64-encoded strings
| ByteArraySwap.Base64.class
| },
| beanFilters={
| // Subclasses of MyInterface will be treated as MyInterface objects.
| // Bean properties not defined on that interface will be ignored.
| MyInterface.class
| }
| )
| public MyResource extends BasicRestServlet implements BasicUniversalConfig {...}
Config annotations are defined for all serializers and parsers:
- {@link oaj.annotation.BeanConfig BeanConfig}
- {@link oaj.csv.annotation.CsvConfig CsvConfig}
- {@link oaj.html.annotation.HtmlConfig HtmlConfig}
- {@link oaj.html.annotation.HtmlDocConfig HtmlDocConfig}
- {@link oaj.json.annotation.JsonConfig JsonConfig}
- {@link oaj.jsonschema.annotation.JsonSchemaConfig JsonSchemaConfig}
- {@link oaj.msgpack.annotation.MsgPackConfig MsgPackConfig}
- {@link oaj.oapi.annotation.OpenApiConfig OpenApiConfig}
- {@link oaj.parser.annotation.ParserConfig ParserConfig}
- {@link oaj.plaintext.annotation.PlainTextConfig PlainTextConfig}
- {@link oaj.jena.annotation.RdfConfig RdfConfig}
- {@link oaj.serializer.annotation.SerializerConfig SerializerConfig}
- {@link oaj.soap.annotation.SoapXmlConfig SoapXmlConfig}
- {@link oaj.uon.annotation.UonConfig UonConfig}
- {@link oaj.urlencoding.annotation.UrlEncodingConfig UrlEncodingConfig}
- {@link oaj.xml.annotation.XmlConfig XmlConfig}
- {@link oaj.examples.rest.PhotosResource} - An example of a REST resource that uses a custom serializer and parser.