Network Deployment (Distributed operating systems), v8.0 > End-to-end paths > Web services - RESTful services > Use multipart content in JAX-RS application requests and responses > 4. Implement a resource using multipart messages

Implement resources using multipart messages

A multipart message contains one or more other messages within its structure. Each message part can have its own content type. Using IBM Java API for RESTful Web Services (JAX-RS), you can produce and consume multipart messages.
IBM JAX-RS provides classes from Apache Wink to model a multipart request and a multipart response. Additionally, IBM JAX-RS includes entity providers, by default, that support multipart messages. These entity providers can serialize and deserialize the multipart class instances when the message content type is compatible with multipart/*.

To process multipart messages using Apache Wink APIs, use defined classes to represent the multipart message body entity.

Use the following classes to represent an incoming multipart request:

org.apache.wink.common.model.multipart.InMultiPart
org.apache.wink.common.model.multipart.BufferedInMultiPart

Use one of the incoming multipart request class types as a method parameter in your resource method. The InMultiPart class streams the request message whereas the BufferedInMultiPart class stores the entire message in memory. Streaming the message consumes less memory but you can only access the message parts once in an iterative manner. In contrast, by using buffering, you can read any part of the message at any time.

Use the following classes to represent an outbound multipart response:

org.apache.wink.common.model.multipart.OutMultiPart
org.apache.wink.common.model.multipart.BufferedOutMultiPart

We can return an instance of one of the outbound multipart response types in your resource method. The OutMultiPart class streams the multipart response whereas the BufferedOutMultiPart class stores the entire message in memory.

These multipart inbound and outbound classes use JAX-RS entity providers to serialize and deserialize individual parts of the multipart message.

To learn more about the multipart message classes, see the Apache Wink API documentation.

Procedure

1. Determine to use the multipart class that streams messages or use the multipart class that buffers messages. Consider performance and capabilities when you determine which multipart message implementation is best for your business needs.

2. If a multipart message is received, use one of the InMultiPart classes to deserialize the request entity.

   For example, add the InMultiPart parameter to the resource method:

   @POST
   @Consumes("multipart/mixed")
   public void processMessage(InMultiPart inPart) {
   
   }
   
   

   The following code snippet is an example of a request that has a Content-Type request header value of multipart/mixed;boundary=myboundary and a message body:

   --myboundary
   Content-Type: text/plain
   MyCustomPartHeader: ThisIsTheGreetingPart
   
   Hello world
   --myboundary
   Content-Type: text/custom
   
   Bonjour
   --myboundary--
   
   

   The following code example can read each part of the multipart message:

   @POST
   @Consumes("multipart/mixed")
   public void processMessage(InMultiPart inMultiPart) throws IOException {
       int counter = 0;
       while(inMultiPart.hasNext()) {
           counter++;
           InPart part = inMultiPart.next();
           .println("The part number is: " + counter);
           .println("The content type is: " + part.getContentType());
           .println("The content body is: " + part.getBody(String.class, String.class));
           .println("The content headers are: " + part.getHeaders());
       }
   }
   
   

3. If it is required that a multipart message is sent, use one of the OutMultiPart classes to serialize the request entity.

   For example, return a BufferedOutMultiPart instance from the resource method:

   @GET
   @Produces("multipart/mixed;boundary=myboundary")
   public BufferedOutMultiPart processMessage() {
       BufferedOutMultiPart mpout = new BufferedOutMultiPart();
       mpout.setBoundary("myboundary");
   
       /* first part */
       OutPart op = new OutPart();
       op.setBody("Hello world");
       op.setContentType("text/plain");
       op.addHeader("MyCustomHeader", "ThisIsTheGreetingPart");
       mpout.addPart(op);
   
       /* second part */
       op = new OutPart();
       byte[] binaryData = "Bonjour".getBytes("UTF-8");
       op.setBody(binaryData);
       op.setContentType("custom/binarytype");
       mpout.addPart(op);
       return mpout;
   }
   
   

   The previous response code can reply to the request with a message like the following code example:

   --myboundary
   Content-Type: text/plain
   MyCustomHeader: ThisIsTheGreetingPart
   
   Hello world
   --myboundary
   Content-Type: custom/binarytype
   
   Bonjour
   --myboundary--
   
   

Results

We can receive and send multipart messages containing multiple content types.
Use multipart content in JAX-RS application requests and responses

+

Search Tips   |   Advanced Search