Reading and writing large binary objects using Jersey APIs

When you work on enterprise-grade business applications, you may often want to build RESTful web APIs for reading and writing large binary objects, such as images, documents, and various types of media files. Unfortunately, the JAX-RS API does not have standardized APIs for dealing with large binary files. In this section, we will see offerings from the Jersey framework to store and retrieve images files. These APIs are generic in nature and can be used with any large binary file.

Building RESTful web services for storing images

Let's build a REST API to store the image sent by the client. We will start with the client and then move on to the server-side implementation.

This example uses an HTML client to upload images to the REST API. When you make a POST request to the server, you have to encode the data that forms the body of the request. You can use the multipart/form-data encoding to deal with a large binary object uploaded via <input type="file">. The client-side HTML code may look like the following:

<html> 
  <head> 
   <title>File upload</title> 
   <meta charset="UTF-8"> 
  </head> 
  <body> 
   <form action="employees/100/image"  
     method="post" enctype="multipart/form-data"> 
     Choose photo for employee# 100 :  
     <input type="file" name="empImgFile" /> 
     <br> 
     <input type="submit" value="Upload Image" /> 
   </form> 
  </body> 
</html>

This HTML client uploads images for an employee identified by id=100. The RESTful web API for storing images is located at the employees/100/image URI. The client code for uploading an image to the RESTful web API is in place now.

As the next step, we will build a RESTful web API that accepts an uploaded image and stores it in a database. Jersey makes it simple by offering many binding annotations for method parameters to extract the desired value from the request body. For instance, it offers the @org.glassfish.jersey.media.multipart.FormDataParam annotation, which can be used for binding the named body parts of a multipart/form-data request body to a method parameter or a class member variable, as appropriate. We will use this annotation in conjunction with the request content encoded with multipart/form-data for consuming forms that contain files, non-ASCII data, and binary data. Jersey allows you to inject @FormDataParam onto the following parameter types:

Any type of parameter for which a message body reader is available: The following example binds an input stream present in the first named body part, empImageFile, with an inputStream object: @FormDataParam("empImgFile") InputStream inputStream.
org.glassfish.jersey.media.multipart.FormDataBodyPart: This object can be used for reading the value of a parameter that represents the first named body part present in the request body. You can also use List or Collection of FormDataBodyPart to read the values of multiple body parts with the same name. An example is @FormDataParam("p1") List<FormDataBodyPart> values.
org.glassfish.jersey.media.multipart.FormDataContentDisposition: This represents the form-data content disposition header in the incoming payload. You can use it for retrieving details about the uploaded file, such as its name and size.

When you use @FormDataParam on a field, the entity provider will inject content from the incoming message body to the annotated fields, as appropriate.

The following code snippet demonstrates how you can use @FormDataParam for building a REST API that reads an image uploaded by a client. Note that the name parameter set for @FormDataParam(...) must match with the file input component present in the request payload. In this example, we name the input file component empImgFile in the HTML, <input type="file" name="empImgFile" />. You must use the same name as the parameter for @FormDataParam("empImgFile") to read the uploaded file content present in the payload posted to the server. This example uses JPA to persist the data:

//Other imports are not shown for brevity 
import org.glassfish.jersey.media.multipart. 
           FormDataContentDisposition; 
import org.glassfish.jersey.media.multipart.FormDataParam; 
  
@Stateless 
@Path("employees") 
public class EmployeeResource { 
   //Name of the persistence unit from persistence.xml  
   @PersistenceContext(unitName = "EMP_PU") 
   private EntityManager entityManager; 
 
   @POST 
   @Path("{empId}/image") 
   @Consumes(MediaType.MULTIPART_FORM_DATA) 
   public void uploadImage(@Context HttpServletRequest request,  
       @FormDataParam("empImgFile") InputStream in, 
      @FormDataParam("empImgFile") FormDataContentDisposition 
       fileDetail,  
      @PathParam("empId") Integer empId) throws Exception { 
 
      try(ByteArrayOutputStream bos = new ByteArrayOutputStream()) 
      { 
         int size = request.getContentLength(); 
         byte[] buffer = new byte[size]; 
         int len=0; 
         while ((len = in.read(buffer, 0, 10240)) != -1) { 
           bos.write(buffer, 0, len); 
         } 
         byte[] imgBytes = bos.toByteArray(); 
         //Pass the image to underlying entity  
         //to persist the content 
         EmployeeImage empImg = findEmployeeImageEntity(empId); 
         empImg.setImage(imgBytes); 
         entityManager.merge(empImg); 
       }
   } 
//Other methods are not shown for brevity 
}

Before ending this section on REST support for handling binary files, let's take a quick look at the code snippet for reading binary files (or images) as well.

Building RESTful web service for reading images

The following method reads the binary representation of an image from the database and streams the content by using the javax.ws.rs.core.StreamingOutput class. The method is annotated with @Produces(MediaType.APPLICATION_OCTET_STREAM) to indicate that the response is in a binary form:

//Other imports are omitted for brevity 
import javax.ws.rs.core.StreamingOutput; 
 
@GET 
@Path("/{empId}/image") 
@Produces(MediaType.APPLICATION_OCTET_STREAM) 
public Response getImage(final @PathParam("empId") Integer id) throws Exception { 
 
  StreamingOutput outputImage = new StreamingOutput() { 
     @Override 
     Public void write(OutputStream output)  
         throws IOException { 
    EmployeeImage empImg = findEmployeeImageEntity(id); 
    byte[] buf = empImg.getImage(); 
    output.write(buf); 
    output.flush(); 
     } 
  }; 
  
  ResponseBuilder response = Response.ok((Object) outputImage);
  response.header("Content-Disposition", "inline;filename=image.jpeg");
  return response.build();
}

You can use the preceding RESTful web API directly with the <img> component present in the HTML page, as shown in the following HTML snippet. The employees/100/image URI points to the RESTful web API that we built for reading the image content:

<img alt="Employee image" src="employees/100/image" id="id"/>

Search This Blog

RESTful Java Web Services 3rd Edition-Bogunuva Mohanram Balachandar