Chapter 9. Support for Common Media Type Representations

• POJO based JSON binding support

• JAXB based JSON binding support

• Low-level JSON parsing & processing support

POJO support represents the easiest way to convert your Java Objects to JSON and back.

Media modules that support this approach areMOXy,Jackson, andJava API for JSON Binding (JSON-B)

Taking this approach will save you a lot of time, if you want to easily produce/consume both JSON and XML data format. With JAXB beans you will be able to use the same Java model to generate JSON as well as XML representations. Another advantage is simplicity of working with such a model and availability of the API in Java SE Platform. JAXB leverages annotated POJOs and these could be handled as simple Java beans.

A disadvantage of JAXB based approach could be if you need to work with a very specific JSON format. Then it might be difficult to find a proper way to get such a format produced and consumed. This is a reason why a lot of configuration options are provided, so that you can control how JAXB beans get serialized and de-serialized. The extra configuration options however requires you to learn more details about the framework you are using.

Following is a very simple example of how a JAXB bean could look like.

@XmlRootElementpublic class MyJaxbBean {    public String name;    public int age;    public MyJaxbBean() {} // JAXB needs this    public MyJaxbBean(String name, int age) {        this.name = name;        this.age = age;    }}

Using the above JAXB bean for producing JSON data format from you resource method, is then as simple as:

@GET@Produces("application/json")public MyJaxbBean getMyBean() {    return new MyJaxbBean("Agamemnon", 32);}

Notice, that JSON specific mime type is specified in@Produces annotation, and the method returns an instance ofMyJaxbBean, which JAXB is able to process. Resulting JSON in this case would look like:

{"name":"Agamemnon", "age":"32"}

A proper use of JAXB annotations itself enables you to control output JSON format to certain extent. Specifically, renaming and omitting items is easy to do directly just by using JAXB annotations. For example, the following example depicts changes in the above mentioned MyJaxbBean that will result in{"king":"Agamemnon"} JSON output.

@XmlRootElementpublic class MyJaxbBean {    @XmlElement(name="king")    public String name;    @XmlTransient    public int age;    // several lines removed}

Media modules that support this approach areMOXy,Jackson,Jettison

JSON Processing API is a new standard API for parsing and processing JSON structures in similar way to what SAX and StAX parsers provide for XML. The API is part of Jakarta EE 9 and later. Another such JSON parsing/processing API is provided by Jettison framework (which is also supported in jakartified environment). Both APIs provide a low-level access to producing and consuming JSON data structures. By adopting this low-level approach you would be working withJsonObject (orJSONObject respectively) and/orJsonArray (orJSONArray respectively) classes when processing your JSON data representations.

The biggest advantage of these low-level APIs is that you will gain full control over the JSON format produced and consumed. You will also be able to produce and consume very large JSON structures using streaming JSON parser/generator APIs. On the other hand, dealing with your data model objects will probably be a lot more complex, compared to the POJO or JAXB based binding approach. Differences are depicted at the following code snippets.

Let's start with JAXB-based approach.

MyJaxbBean myBean = new MyJaxbBean("Agamemnon", 32);

Above you construct a simple JAXB bean, which could be written in JSON as{"name":"Agamemnon", "age":32}

Now to build an equivalentJsonObject/JSONObject (in terms of resulting JSON expression), you would need several more lines of code. The following example illustrates how to construct the same JSON data using the standard Jakarta EE 9 JSON-Processing API.

JsonObject myObject = Json.createObjectBuilder()        .add("name", "Agamemnon")        .add("age", 32)        .build();

And at last, here's how the same work can be done with Jettison API.

JSONObject myObject = new JSONObject();try {    myObject.put("name", "Agamemnon");    myObject.put("age", 32);} catch (JSONException ex) {    LOGGER.log(Level.SEVERE, "Error ...", ex);}

Media modules that support the low-level JSON parsing and generating approach areJava API for JSON Processing (JSON-P) andJettison. Unless you have a strong reason for using the non-standardJettison API, we recommend you to use the new standardJava API for JSON Processing (JSON-P) API instead.

To use MOXy as your JSON provider you need to addjersey-media-moxy module to yourpom.xml file:

<dependency>    <groupId>org.glassfish.jersey.media</groupId>    <artifactId>jersey-media-moxy</artifactId>    <version>4.0.0</version></dependency>

If you're not using Maven make sure to have all needed dependencies (seejersey-media-moxy) on the classpath.

As stated in theSection 4.3, “Auto-Discoverable Features” as well as earlier in this chapter, MOXy media module is one of the modules where you don't need to explicitly register itsFeatures (MoxyJsonFeature) in your client/serverConfigurable as this feature is automatically discovered and registered when you addjersey-media-moxy module to your class-path.

The auto-discoverablejersey-media-moxy module defines a few properties that can be used to control the automatic registration ofMoxyJsonFeature (besides the genericCommonProperties.FEATURE_AUTO_DISCOVERY_DISABLE an the its client/server variants):

To configureMessageBodyReader<T>s /MessageBodyWriter<T>s provided by MOXy you can simply create an instance ofMoxyJsonConfig and set values of needed properties. For most common properties you can use a particular method to set the value of the property or you can use more generic methods to set the property:

final Map<String, String> namespacePrefixMapper = new HashMap<String, String>();namespacePrefixMapper.put("http://www.w3.org/2001/XMLSchema-instance", "xsi");final MoxyJsonConfig configuration = new MoxyJsonConfig()        .setNamespacePrefixMapper(namespacePrefixMapper)        .setNamespaceSeparator(':');

In order to makeMoxyJsonConfig visible for MOXy you need to create and registerContextResolver<T> in your client/server code.

final Map<String, String> namespacePrefixMapper = new HashMap<String, String>();namespacePrefixMapper.put("http://www.w3.org/2001/XMLSchema-instance", "xsi");final MoxyJsonConfig moxyJsonConfig = MoxyJsonConfig()            .setNamespacePrefixMapper(namespacePrefixMapper)            .setNamespaceSeparator(':');final ContextResolver<MoxyJsonConfig> jsonConfigResolver = moxyJsonConfig.resolver();

Another way to pass configuration properties to the underlyingMOXyJsonProvider is to set them directly into yourConfigurable instance (see an example below). These are overwritten by properties set into theMoxyJsonConfig.

new ResourceConfig()                            .property(MarshallerProperties.JSON_NAMESPACE_SEPARATOR, ".")                            // further configuration

There are some properties for which Jersey sets the default value whenMessageBodyReader<T> /MessageBodyWriter<T> from MOXy is used and they are:

final Client client = ClientBuilder.newBuilder()        // The line below that registers MOXy feature can be        // omitted if FEATURE_AUTO_DISCOVERY_DISABLE is        // not disabled.        .register(MoxyJsonFeature.class)        .register(jsonConfigResolver)        .build();

// Create JAX-RS application.final Application application = new ResourceConfig()        .packages("org.glassfish.jersey.examples.jsonmoxy")        // The line below that registers MOXy feature can be        // omitted if FEATURE_AUTO_DISCOVERY_DISABLE is        // not disabled.        .register(MoxyJsonFeature.class)        .register(jsonConfigResolver);

Jersey provides aJSON MOXy example on how to use MOXy to consume/produce JSON.

To use JSON-P as your JSON provider you need to addjersey-media-json-processing module to yourpom.xml file:

<dependency>    <groupId>org.glassfish.jersey.media</groupId>    <artifactId>jersey-media-json-processing</artifactId>    <version>4.0.0</version></dependency>

If you're not using Maven make sure to have all needed dependencies (seejersey-media-json-processing) on the class-path.

As stated inSection 4.3, “Auto-Discoverable Features” JSON-Processing media module is one of the modules where you don't need to explicitly register itsFeatures (JsonProcessingFeature) in your client/serverConfigurable as this feature is automatically discovered and registered when you addjersey-media-json-processing module to your classpath.

As for the other modules,jersey-media-json-processing has also few properties that can affect the registration ofJsonProcessingFeature (besidesCommonProperties.FEATURE_AUTO_DISCOVERY_DISABLE and the like):

To configureMessageBodyReader<T>s /MessageBodyWriter<T>s provided by JSON-P you can simply add values for supported properties into theConfiguration instance (client/server). Currently supported are these properties:

ClientBuilder.newClient(new ClientConfig()        // The line below that registers JSON-Processing feature can be        // omitted if FEATURE_AUTO_DISCOVERY_DISABLE is not disabled.        .register(JsonProcessingFeature.class)        .property(JsonGenerator.PRETTY_PRINTING, true));

// Create JAX-RS application.final Application application = new ResourceConfig()        // The line below that registers JSON-Processing feature can be        // omitted if FEATURE_AUTO_DISCOVERY_DISABLE is not disabled.        .register(JsonProcessingFeature.class)        .packages("org.glassfish.jersey.examples.jsonp")        .property(JsonGenerator.PRETTY_PRINTING, true);

Jersey provides aJSON Processing example on how to use JSON-Processing to consume/produce JSON.

To use Jackson 2.x as your JSON provider you need to addjersey-media-json-jackson module to yourpom.xml file:

<dependency>    <groupId>org.glassfish.jersey.media</groupId>    <artifactId>jersey-media-json-jackson</artifactId>    <version>4.0.0</version></dependency>

If you're not using Maven make sure to have all needed dependencies (seejersey-media-json-jackson) on the classpath.

Jackson JSON processor could be controlled via providing a custom Jackson 2ObjectMapper instance. This could be handy if you need to redefine the default Jackson behaviour and to fine-tune how your JSON data structures look like. Detailed description of all Jackson features is out of scope of this guide. The example below gives you a hint on how to wire yourObjectMapper instance into your Jersey application.

Since the 2.36 version of Jersey it is possible to filter (include/exclude) Jackson modules by propertiesCommonProperties.JSON_JACKSON_DISABLED_MODULES andCommonProperties.JSON_JACKSON_ENABLED_MODULES (with their client/server derivatives). If theCommonProperties.JSON_JACKSON_ENABLED_MODULES property is used, only those named modules will be used for JSON processing. On the other hand if theCommonProperties.JSON_JACKSON_DISABLED_MODULES property is used, those listed modules will be explicitly excluded from processing while other (not listed) will remain. Please note that theJaxbAnnotationModule module is always excluded from processing and this is not configurable.

In order to use Jackson as your JSON (JAXB/POJO) provider you need to registerJacksonFeature and aContextResolver<T> forObjectMapper, if needed, in yourConfigurable (client/server).

@Providerpublic class MyObjectMapperProvider implements ContextResolver<ObjectMapper> {    final ObjectMapper defaultObjectMapper;    public MyObjectMapperProvider() {        defaultObjectMapper = createDefaultMapper();    }    @Override    public ObjectMapper getContext(Class<?> type) {            return defaultObjectMapper;        }    }    private static ObjectMapper createDefaultMapper() {        final ObjectMapper result = new ObjectMapper();        result.configure(Feature.INDENT_OUTPUT, true);        return result;    }    // ...}

final Client client = ClientBuilder.newBuilder()        .register(MyObjectMapperProvider.class)  // No need to register this provider if no special configuration is required.        .register(JacksonFeature.class)        .build();

// Create JAX-RS application.final Application application = new ResourceConfig()        .packages("org.glassfish.jersey.examples.jackson")        .register(MyObjectMapperProvider.class)  // No need to register this provider if no special configuration is required.        .register(JacksonFeature.class);

Jersey providesJSON Jackson (2.x) example showing how to use Jackson to consume/produce JSON.

To use Jettison as your JSON provider you need to addjersey-media-json-jettison module to yourpom.xml file:

<dependency>    <groupId>org.glassfish.jersey.media</groupId>    <artifactId>jersey-media-json-jettison</artifactId>    <version>4.0.0</version></dependency>

If you're not using Maven make sure to have all needed dependencies (seejersey-media-json-jettison) on the classpath.

JettisonConfig allows you to use two JSON notations. Each of these notations serializes JSON in a different way. Following is a list of supported notations:

You might want to use one of these notations, when working with more complex XML documents. Namely when you deal with multiple XML namespaces in your JAXB beans.

Individual notations and their further configuration options are described below. Rather then explaining rules for mapping XML constructs into JSON, the notations will be described using a simple example. Following are JAXB beans, which will be used.

@XmlRootElementpublic class Address {    public String street;    public String town;    public Address(){}    public Address(String street, String town) {        this.street = street;        this.town = town;    }}

@XmlRootElementpublic class Contact {    public int id;    public String name;    public List<Address> addresses;    public Contact() {};    public Contact(int id, String name, List<Address> addresses) {        this.name = name;        this.id = id;        this.addresses =            (addresses != null) ? new LinkedList<Address>(addresses) : null;    }}

Following text will be mainly working with a contact bean initialized with:

Address[] addresses = {new Address("Long Street 1", "Short Village")};Contact contact = new Contact(2, "Bob", Arrays.asList(addresses));

I.e. contact bean withid=2,name="Bob" containing a single address (street="Long Street 1",town="Short Village").

All below described configuration options are documented also in api-docs atJettisonConfig.

...@XmlElement(namespace="http://example.com")public int id;...

Map<String,String> ns2json = new HashMap<String, String>();ns2json.put("http://example.com", "example");context = new JettisonJaxbContext(    JettisonConfig.mappedJettison().xml2JsonNs(ns2json).build(),    types);

{   "contact":{      "example.id":2,      "name":"Bob",      "addresses":{         "street":"Long Street 1",         "town":"Short Village"      }   }}

context = new JettisonJaxbContext(    JettisonConfig.mappedJettison().serializeAsArray("name").build(),    types);

{   "contact":{      ...      "name":["Bob"],      ...   }}

JettisonConfig.badgerFish().build()

{   "contact":{      "id":{         "$":"2"      },      "name":{         "$":"Bob"      },      "addresses":{         "street":{            "$":"Long Street 1"         },         "town":{            "$":"Short Village"         }      }   }}

In order to use Jettison as your JSON (JAXB/POJO) provider you need to registerJettisonFeature and aContextResolver<T> forJAXBContext (if needed) in yourConfigurable (client/server).

@Providerpublic class JaxbContextResolver implements ContextResolver<JAXBContext> {    private final JAXBContext context;    private final Set<Class<?>> types;    private final Class<?>[] cTypes = {Flights.class, FlightType.class, AircraftType.class};    public JaxbContextResolver() throws Exception {        this.types = new HashSet<Class<?>>(Arrays.asList(cTypes));        this.context = new JettisonJaxbContext(JettisonConfig.DEFAULT, cTypes);    }    @Override    public JAXBContext getContext(Class<?> objectType) {        return (types.contains(objectType)) ? context : null;    }}

final Client client = ClientBuilder.newBuilder()        .register(JaxbContextResolver.class)  // No need to register this provider if no special configuration is required.        .register(JettisonFeature.class)        .build();

// Create JAX-RS application.final Application application = new ResourceConfig()        .packages("org.glassfish.jersey.examples.jettison")        .register(JaxbContextResolver.class)  // No need to register this provider if no special configuration is required.        .register(JettisonFeature.class);

Jersey provides anJSON Jettison example on how to use Jettison to consume/produce JSON.

• Resource method, which should return wrapped JSON, needs to be annotated with@JSONP annotation.

• MessageBodyWriter<T> forapplication/json media type, which also accepts the return type of the resource method, needs to be registered (seeJSON section of this chapter).

• User's request has to containAccept header with one of the JavaScript media types defined (see below).

Example 9.28. Simplest case of using@JSONP

@GET@JSONP@Produces({"application/json", "application/javascript"})public JaxbBean getSimpleJSONP() {    return new JaxbBean("jsonp");}

Example 9.29. JaxbBean for @JSONP example

@XmlRootElementpublic class JaxbBean {    private String value;    public JaxbBean() {}    public JaxbBean(final String value) {        this.value = value;    }    public String getValue() {        return value;    }    public void setValue(final String value) {        this.value = value;    }}

Note

queryParam value (if set) always takes precedence overcallback value.

Example 9.30. Example of@JSONP with configured parameters.

@GET@Produces({"application/json", "application/javascript"})@JSONP(callback = "eval", queryParam = "jsonpCallback")public JaxbBean getSimpleJSONP() {    return new JaxbBean("jsonp");}

To use JSON-B as your JSON provider you need to addjersey-media-json-binding module to yourpom.xml file:

<dependency>    <groupId>org.glassfish.jersey.media</groupId>    <artifactId>jersey-media-json-binding</artifactId>    <version>4.0.0</version></dependency>

If you're not using Maven make sure to have all needed dependencies (seejersey-media-json-binding) on the classpath.

As stated inSection 4.3, “Auto-Discoverable Features” JSON-Binding media module is one of the modules where you don't need to explicitly register itsFeatures (JsonBindingFeature) in your client/serverConfigurable as this feature is automatically discovered and registered when you addjersey-media-json-binding module to your classpath.

To use custom preconfigured JSON-B, it is simply possible to register aContextResolver<T> forJsonb in yourConfigurable (client/server) and configureJsonbConfig.

@Providerpublic class JsonbContextResolver implements ContextResolver<Jsonb> {        @Override        public Jsonb getContext(Class<?> type) {            JsonbConfig config = new JsonbConfig();            // configure JsonbConfig            ...            return JsonbBuilder.create(config);        }}

ClientBuilder.newClient(new ClientConfig()    // The line below that registers JSON-Binding feature can be    // omitted if FEATURE_AUTO_DISCOVERY_DISABLE is not disabled.    .register(JsonBindingFeature.class)    .register(JsonbContextResolver.class));

Example.  You can take a look at a providedJSON-B example..

Example 9.33. Low level XML test - methods added toHelloWorldResource.java

@POST@Path("StreamSource")public StreamSource getStreamSource(StreamSource streamSource) {    return streamSource;}@POST@Path("SAXSource")public SAXSource getSAXSource(SAXSource saxSource) {    return saxSource;}@POST@Path("DOMSource")public DOMSource getDOMSource(DOMSource domSource) {    return domSource;}@POST@Path("Document")public Document getDocument(Document document) {    return document;}

curl -v http://localhost:8080/base/helloworld/StreamSource -d "<test/>"

Example 9.34. Planet class

@XmlRootElementpublic class Planet {    public int id;    public String name;    public double radius;}

Example 9.35. Resource class

@Path("planet")public class Resource {    @GET    @Produces(MediaType.APPLICATION_XML)    public Planet getPlanet() {        final Planet planet = new Planet();        planet.id = 1;        planet.name = "Earth";        planet.radius = 1.0;        return planet;    }}

Example 9.36. Method for consuming Planet

@POST@Consumes(MediaType.APPLICATION_XML)public void setPlanet(Planet planet) {    System.out.println("setPlanet " + planet);}

Example 9.37. Resource class - JAXBElement

@Path("planet")public class Resource {    @GET    @Produces(MediaType.APPLICATION_XML)    public JAXBElement<Planet> getPlanet() {        Planet planet = new Planet();        planet.id = 1;        planet.name = "Earth";        planet.radius = 1.0;        return new JAXBElement<Planet>(new QName("planet"), Planet.class, planet);    }    @POST    @Consumes(MediaType.APPLICATION_XML)    public void setPlanet(JAXBElement<Planet> planet) {        System.out.println("setPlanet " + planet.getValue());    }}

Example 9.38. Client side - JAXBElement

// GETGenericType<JAXBElement<Planet>> planetType = new GenericType<JAXBElement<Planet>>() {};Planet planet = (Planet) webTarget.path("planet").request(MediaType.APPLICATION_XML_TYPE).get(planetType).getValue();System.out.println("### " + planet);// POSTplanet = new Planet();// ...webTarget.path("planet").post(new JAXBElement<Planet>(new QName("planet"), Planet.class, planet));

Example 9.39. PlanetJAXBContextProvider

@Providerpublic class PlanetJAXBContextProvider implements ContextResolver<JAXBContext> {    private JAXBContext context = null;    public JAXBContext getContext(Class<?> type) {        if (type != Planet.class) {            return null; // we don't support nothing else than Planet        }        if (context == null) {            try {                context = JAXBContext.newInstance(Planet.class);            } catch (JAXBException e) {                // log warning/error; null will be returned which indicates that this                // provider won't/can't be used.            }        }        return context;    }}

Example 9.40. Using Provider with JAX-RS client

ClientConfig config = new ClientConfig();config.register(PlanetJAXBContextProvider.class);Client client = ClientBuilder.newClient(config);

Example 9.41. Addjersey-media-moxy dependency.

<dependency>    <groupId>org.glassfish.jersey.media</groupId>    <artifactId>jersey-media-moxy</artifactId>    <version>4.0.0</version></dependency>

Example 9.42. Register theMoxyXmlFeature class.

final ResourceConfig config = new ResourceConfig()    .packages("org.glassfish.jersey.examples.xmlmoxy")    .register(MoxyXmlFeature.class);

Example 9.43. Configure and register anMoxyXmlFeature instance.

// Configure Properties.final Map<String, Object> properties = new HashMap<String, Object>();// ...// Obtain a ClassLoader you want to use.final ClassLoader classLoader = Thread.currentThread().getContextClassLoader();final ResourceConfig config = new ResourceConfig()    .packages("org.glassfish.jersey.examples.xmlmoxy")    .register(new MoxyXmlFeature(        properties,        classLoader,        true, // Flag to determine whether eclipselink-oxm.xml file should be used for lookup.        CustomClassA.class, CustomClassB.class  // Classes to be bound.    ));

• TheMIME-Version: 1.0 HTTP header is included on generated responses. It is accepted, but not required, on processed requests.

• AMessageBodyReader<T> implementation for consuming MIME MultiPart entities.

• AMessageBodyWriter<T> implementation for producing MIME MultiPart entities. The appropriate@Provider is used to serialize each body part, based on its media type.

• Optional creation of an appropriateboundary parameter on a generatedContent-Type header, if not already present.

To use multipart features you need to addjersey-media-multipart module to yourpom.xml file:

<dependency>    <groupId>org.glassfish.jersey.media</groupId>    <artifactId>jersey-media-multipart</artifactId>    <version>4.0.0</version></dependency>

If you're not using Maven make sure to have all needed dependencies (seejersey-media-multipart) on the class-path.

Prior to Jersey 3.1.0, before you can use the capabilities of thejersey-media-multipart module in your client/server code, you need to registerMultiPartFeature. The multipart feature is supported by Jakarta RESTful Web Services 3.1 multipart API. From Jersey 3.1.0 on, theMultiPartFeature is no longer required to be registered and it is registered automatically.

Jersey provides aMultipart Web Application Example on how to use multipart features.

• Client using Jersey API

• Client using Jakarta REST API

MultiPart class (or it's subclasses) can be used as an entry point to usejersey-media-multipart module on the client side. This class represents aMIME multipart message and is able to hold an arbitrary number ofBodyParts. Default media type ismultipart/mixed forMultiPart entity andtext/plain forBodyPart.

final MultiPart multiPartEntity = new MultiPart()        .bodyPart(new BodyPart().entity("hello"))        .bodyPart(new BodyPart(new JaxbBean("xml"), MediaType.APPLICATION_XML_TYPE))        .bodyPart(new BodyPart(new JaxbBean("json"), MediaType.APPLICATION_JSON_TYPE));final WebTarget target = // Create WebTarget.final Response response = target        .request()        .post(Entity.entity(multiPartEntity, multiPartEntity.getMediaType()));

If you send amultiPartEntity to the server the entity withContent-Type header in HTTP message would look like:

Content-Type: multipart/mixed; boundary=Boundary_1_829077776_1369128119878--Boundary_1_829077776_1369128119878Content-Type: text/plainhello--Boundary_1_829077776_1369128119878Content-Type: application/xml<?xml version="1.0" encoding="UTF-8" standalone="yes"?><jaxbBean><value>xml</value></jaxbBean>--Boundary_1_829077776_1369128119878Content-Type: application/json{"value":"json"}--Boundary_1_829077776_1369128119878--

When working with forms (e.g. media typemultipart/form-data) and various fields in them, there is a more convenient class to be used -FormDataMultiPart. It automatically sets the media type for theFormDataMultiPart entity tomultipart/form-data andContent-Disposition header toFormDataBodyPart body parts.

final FormDataMultiPart multipart = new FormDataMultiPart()    .field("hello", "hello")    .field("xml", new JaxbBean("xml"))    .field("json", new JaxbBean("json"), MediaType.APPLICATION_JSON_TYPE);final WebTarget target = // Create WebTarget.final Response response = target.request().post(Entity.entity(multipart, multipart.getMediaType()));

To illustrate the difference when usingFormDataMultiPart instead ofFormDataBodyPart you can take a look at theFormDataMultiPart entity from HTML message:

Content-Type: multipart/form-data; boundary=Boundary_1_511262261_1369143433608--Boundary_1_511262261_1369143433608Content-Type: text/plainContent-Disposition: form-data; name="hello"hello--Boundary_1_511262261_1369143433608Content-Type: application/xmlContent-Disposition: form-data; name="xml"<?xml version="1.0" encoding="UTF-8" standalone="yes"?><jaxbBean><value>xml</value></jaxbBean>--Boundary_1_511262261_1369143433608Content-Type: application/jsonContent-Disposition: form-data; name="json"{"value":"json"}--Boundary_1_511262261_1369143433608--

A common use-case for many users is sending files from client to server. For this purpose you can use classes fromorg.glassfish.jersey.jersey.media.multipart package, such asFileDataBodyPart orStreamDataBodyPart.

// MediaType of the body part will be derived from the file.final FileDataBodyPart filePart = new FileDataBodyPart("my_pom", new File("pom.xml"));final FormDataMultiPart multipart = new FormDataMultiPart()    .field("foo", "bar")    .bodyPart(filePart);final WebTarget target = // Create WebTarget.final Response response = target.request()    .post(Entity.entity(multipart, multipart.getMediaType()));

EntityPart interface can be used as an entry point to usejersey-media-multipart module on the client side. This class represents multipart message is able to hold an arbitrary number ofEntityParts. Default media type ismultipart/form-data.

final List<EntityPart> multiPartEntity = new List<>();list.add(EntityPart.withName("part-01").content("hello").build());list.add(EntityPart.withName("part-01").content(new JaxbBean("xml")).mediaType(MediaType.APPLICATION_XML_TYPE).build()); //same namelist.add(EntityPart.withName("part-02").content(new JaxbBean("json")).mediaType(MediaType.APPLICATION_JSON_TYPE).build()); //other namefinal GenericEntity<List<EntityPart>> genericEntity = new GenericEntity<>(list) {};final Entity entity = Entity.entity(genericEntity, MediaType.MULTIPART_FORM_DATA_TYPE);final WebTarget target = // Create WebTarget.final Response response = target.request().post(entity);

The common use-case for many users is sending files from client to server. It is also covered byEntityPart.Builder.

// MediaType of the body part will be derived from the file.final List<EntityPart> multiPartEntity = new List<>();list.add(EntityPart.withFileName("file001.txt").content(Files.newInputStream(Path.of("file001.txt"))).build());list.add(EntityPart.withFileName("mypom.xml").content(Files.newInputStream(Path.of("pom.xml"))).build());final GenericEntity<List<EntityPart>> genericEntity = new GenericEntity<>(list) {};final Entity entity = Entity.entity(genericEntity, MediaType.MULTIPART_FORM_DATA_TYPE);final WebTarget target = // Create WebTarget.final Response response = target.request().post(entity);

• Server using Jersey API

• Server using Jakarta REST API

Returning a multipart response from server to client is not much different from the parts described in the client section above. To obtain a multipart entity, sent by a client, in the application you can use two approaches:

@POST@Produces("multipart/mixed")public MultiPart post(final FormDataMultiPart multiPart) {    return multiPart;}

@POST@Consumes(MediaType.MULTIPART_FORM_DATA)public String postForm(    @DefaultValue("true") @FormDataParam("enabled") boolean enabled,    @FormDataParam("data") FileData bean,    @FormDataParam("file") InputStream file,    @FormDataParam("file") FormDataContentDisposition fileDisposition) {    // ...}

There are multiple options that can be used when configuring the multipart. SeeMultiPartProperties orSection A.13, “Multipart configuration properties” for the possibilities.

The options can set in a configuration file specified by theMultiPartProperties.MULTI_PART_CONFIG_RESOURCE property. That is the standard Java properties file.

Or the options can be set programmatically, by registeringContextResolver<MultiPartProperties>. For instance:

ResourceConfig resourceConfig = new ResourceConfig();resourceConfig.register(new MultiPartProperties().bufferThreshold(65535).maxParts(2).resolver());

UsingEntityPart on the server side is similar to the client side. Jakarta REST specification allows for returning aResponse or aList ofEntityParts.

Receiving theEntityParts can be done either using@FormParam annotations andEntityPart,InputStream orString data-types, or using aList ofEntityParts.

@POST@Path("/postFormVarious")public Response postFormVarious(@FormParam("name1") EntityPart part1,                @FormParam("name2") InputStream part2,                @FormParam("name3") String part3) throws IOException {    final List<EntityPart> list = new LinkedList<>();    list.add(EntityPart.withName(part1.getName())        .content(part1.getContent(String.class) + new String(part2.readAllBytes()) + part3)        .mediaType(MediaType.TEXT_PLAIN_TYPE)        .build());    final GenericEntity<List<EntityPart>> genericEntity = new GenericEntity<>(list) {};    return Response.ok(genericEntity, MediaType.MULTIPART_FORM_DATA_TYPE).build();}

@POST@Path("/postListForm")public String postEntityPartForm(@FormParam("part-0x") List<EntityPart> part) throws IOException {    final String entity = part.get(0).getContent(String.class) + part.get(1).getContent(String.class);    return entity;}

@GET@Produces(MediaType.MULTIPART_FORM_DATA)@Path("/getList")public List<EntityPart> getList() throws IOException {    final List<EntityPart> list = new LinkedList<>();    list.add(EntityPart.withName("name1").content("data1").build());    return list;}