{title:'Marshalling', updated:'9.0.0'}

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.

##### Example:

| @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.