Understanding data binding rules in JAX-RS

 

Understanding data binding rules in JAX-RS

While injecting variable values from the URI path and query parameter into the resource class or while mapping the request-response entity body with Java types, the JAX-RS runtime follows certain rules for the Java types present in the resource class.

Mapping the path variable with Java types

At runtime, the framework automatically detects and copies the parameter values present in the inbound request into the appropriate Java types based on the request parameter type. In general, the mapping is performed on the basis of the following rules for each of the request parameter annotation types, except for the @Context annotation:

  • All primitive types, such as short, int, float, double, and Boolean, except char.
  • All the wrapper classes of primitive types, such as short, integer, BigDecimal, and Boolean, except char.
  • All classes with a constructor that accept a single string type argument. In this case, you can define your own class with a single string type constructor and use it as a method parameter or member variable with an appropriate annotation for reading the parameter value.
  • Any class with the static method named valueOf(String) that accepts a single string argument.
  • Have a registered implementation of ParamConverterProvider JAX-RS extension SPI that returns a ParamConverter instance, capable of a from string conversion for the type.
  • If the parameters contain more than one value for the same name, you can have java.util.List<T>, java.util.Set<T>, or java.util.SortedSet<T> as the Java variable type at the receiving end, where T represents the types that satisfy the first two criteria that we defined.

It would be interesting to see how the framework initializes the Java class types when there are no matching request parameters found. The following outcomes will occur if there is no matching value found in the request URI for a Java variable type and if @DefaultValue is not defined:

Now, let's see how the mapping is done between the request-response body content and Java types.

Mapping the request and response entity body with Java types


JAX-RS uses javax.ws.rs.ext.MessageBodyReader for mapping the HTTP request entity body to an appropriate Java type. On the other hand, javax.ws.rs.ext.MessageBodyWriter is used for mapping the Java type returned by a resource class method to the appropriate HTTP response entity body representation, such as JSON, XML, and text. The MessageBodyReader and MessageBodyWriter implementations will raise javax.ws.rs.WebApplicationException if they do not know how to convert the input data.

JAX-RS offers the default content handlers (entity providers) for all common data types. Here is a list of the Java types supported by JAX-RS by default:

  • JAX-RS supports mapping between the following Java data types and request-response entity bodies for all media forms: byte[], java.lang.String, java.io.InputStream, java.io.Reader, java.io.File, javax.activation.DataSource, and javax.xml.transform.Source
  • JAX-RS supports the javax.ws.rs.core.MultivaluedMap<K,V> type for reading or writing the form content, whose media type is application/x-www-form-urlencoded
  • JAX-RS supports the javax.xml.bind.JAXBElement type for reading or writing content represented using the XML media types (text/xml, application/xml, and application/*+xml)
  • JAX-RS supports the java.lang.Boolean, java.lang.Character, and java.lang.Number types for reading and writing the Boolean strings (true or false), characters, and numerical content presented in the text/plain media type


Comments

Post a Comment

Popular posts from this blog

Understanding the JAX-RS resource life cycle

Image
Understanding the JAX-RS resource life cycle The following diagram depicts the sequence of actions taking place on the server when a client invokes the JAX-RS RESTful web service: For an incoming REST API call, the container identifies the Java servlet configured for handling the REST API calls by parsing the URI, and then delegates the request to the designated servlet. The servlet initializes the JAX-RS runtime and kicks off the RESTful web service request processing cycle for the REST API call in the following sequence: The runtime executes prematching filters ( ContainerRequestFilter  with the  @Prematching  annotation), which happens before resolving the resource method. The prematching filters are useful if you want to influence resource method resolution. The next step is to identify the resource method for serving the request. After the resolution of the resource method, postmatching filters are executed (filters without  @Prematching ). Postmatching filters ...
Read more

Generating a chunked output using Jersey APIs

  Generating a chunked output using Jersey APIs A chunked response means that instead of waiting for the entire result, the results are   split  into chunks (partial results) and sent one after the other. Sending a response in chunks is useful for a RESTful web API if the resource returned by the API is huge in size. With Jersey, you can use the  org.glassfish.jersey.server.ChunkedOutput  class as the return type to send the response to a client in chunks. The chunked output content can be any data type for which  MessageBodyWriter<T>  (entity provider) is available. When you specify  ChunkedOutput  as the return type for a REST resource method, it tells the runtime that the response will be chunked and sent one by one to the client. Seeing  ChunkedOutput  as the return type for a method, Jersey will switch to the asynchronous processing mode while processing this method at runtime, without you having to explicitly use  A...
Read more

Jersey client API for reading chunked input

  Jersey client API for reading chunked input To read the chunked input on the client, Jersey offers the  org.glassfish.jersey.client.ChunkedInput<T> class. Here is a client example that reads the employee list in chunks, as returned by the server: //Other imports omitted for brevity import org.glassfish.jersey.media.sse.EventInput; import javax.ws.rs.client.ClientBuilder; String BASE_URI = "http://localhost:8080/hr-app/api"; Client client = ClientBuilder.newClient(); Response response = client.target().path("employees") .path("chunk").request().get(); ChunkedInput<List<Employee>> chunks = response .readEntity(new GenericType<ChunkedInput<List<Employee>>>(){}); List<Employee> chunk; while ((chunk = chunks.read()) != null) { //Code to process List<Employee> received in chunks goes here } //Close the client after use client.close(); Having discussed chunked output and input, we now wil...
Read more