Marshalling

Outdated examples (10.0)

Examples on this page using RestContext.Builder is pre-10.0 and kept only for historical context. Use @Rest(...serializers/parsers...), @RestOp(...), or @Bean(name="serializers"|"parsers") with fully built sets. See the V10 Migration Guide.

Juneau uses Parsers and 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.

Default response format is HTML, not JSON

The response format is not hardwired to JSON. It is chosen by ordinary HTTP content negotiation: the request's Accept header is best-matched against the media types of the configured serializers (Serializer.getMediaTypeRanges()). A request that sends no Accept header — or a non-specific one such as */*, which browsers send by default — is treated as */* and matches the first serializer in the set.

In the default configuration (BasicRestServlet / BasicRestResource, via BasicUniversalConfig) the serializer set lists HtmlDocSerializer first, so a browser — or any client that omits Accept — receives HTML, not JSON. To always get JSON, send an explicit Accept: application/json header. Serializer ordering is what sets this default, so order the serializers list deliberately.

Serializers and parsers can be associated with REST servlets using the following annotations:

Request bodies are parsed and passed in via @Content-annotated parameters, and response bodies are returned or thrown by @RestOp-annotated methods and serialized.

Example

@Rest(
    serializers={JsonSerializer.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:

BasicRestServlet

BasicRestServletGroup

BasicRestResource

BasicRestResourceGroup

Interfaces:

Serializers and parsers can also be supplied programmatically using @Bean bean suppliers (for example, name="serializers" and name="parsers").

They can also be defined through custom REST contexts.

Config annotations allow you to define serializer and parser properties using specialized annotations at either the class or operation levels:

@Rest(
    ...
)
@MarshalledConfig(sortProperties="true")
@SerializerConfig(trimNulls="true")
@JsonConfig(escapeSolidus="true")
public class MyResource extends BasicRestServlet {

    @RestPost
    @MarshalledConfig(sortProperties="false")
    @SerializerConfig(trimNulls="false")
    public MyPojo myMethod(@Content MyPojo myPojo) {
        ...
    }
}

Swaps are associated serializers and parsers registered on a REST resource via the MarshalledConfig annotation on either the class or method level:

// Servlet with transforms applied
@Rest(
    ...
)
@MarshalledConfig(
    calendarFormat=CalendarFormat.ISO_INSTANT,  // Calendars serialized/parsed as ISO8601 date-time strings
    binaryFormat=BinaryFormat.BASE64            // Byte arrays serialized/parsed as BASE64-encoded strings
)
public MyResource extends BasicRestServlet {...}

Config annotations are defined for all serializers and parsers: