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.BasicJson5Config}
- {@link oajr.config.BasicOpenApiConfig}
- {@link oajr.config.BasicUniversalConfig}
Serializers and parsers can also be defined programmatically using an INIT hook method like shown below:
| @Rest
| public class MyResource {
|
| @RestInit
| 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 custom REST contexts 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 {
|
| @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 {...}
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.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.