Screencast: Part 2 – JavaEE 7, Mongo, REST, Mobile

In the second part screencast, we will take the data news item stored in the Mongo database and expose that as RESTful reesources. When a request arrives it can specify the following 2 parameters in the query string

  • oid – this is the object id of the document/record. This tells the REST resource to start returning the records from the specified oid. If the oid is missing then we will start from the very first record.
  • batchSize – the number of records to return.

To allow the application server to potentially process a large number of records per request, we handle the retrieving and processing of the news items asynchronously. This is very similar in spirit to async Servlets; however unlike async Servlets, in async JAX-RS you need to provide a thread. This is where the concurrency utilities comes in.

Using @Suspended annotation, we get an instance of AsyncResponse. The AsyncResponse object is passed to a Runnable (our task) which is then dispatched to the ManagedScheduleExecutorSerivce. When the Runnable completes, it calls AsyncResponse.resume() to resume the suspended request.



The NetBeans project for part 2 is available here. You can find part 1 of this series here.

Till next time.

Using JSONP with JAX-RS

JSONP is a format used to work around the same origin policy. As the name implies it is a modification on the JSON format. Instead of returning a JSON object like so

{ "customerId": 123, "name": "fred", "email": "" }

the JSON is return as a method call to a function like so

foo({ "customerId": 123, "name": "fred", "email": "" })

JSONP is typically used in cross origin AJAX calls using the GET method. You can learn more about JSONP from this Stack Overflow discussion. The JSON-P website talks about why and when it is used.

Handling JSONP

We will examine JSONP by first looking at how we use it from the ever popular jQuery. To make an cross origin AJAX call with JSONP we use $.ajax() like so

   type: "GET",
   url: "webresources/customer/1",
   dataType: 'jsonp' })
.done(function(result) {
   //Do something with the result
   console.log("----> " + JSON.stringify(result));
}).fail(function() {
   //Handle failure

Lets assume that our AJAX call is going to get a customer record. The HTTP request goes across to the server

GET /JSONPTest/webresources/customer/1?callback=jQuery210012143543711863458_1393227259817 HTTP/1.1
Accept: text/javascript, application/javascript, application/ecmascript, application/x-ecmascript, */*; q=0.01

and the response

HTTP/1.1 200 OK
Content-Type: application/javascript

Notice that the callback function name is in the query string of the request.

So to write a JAX-RS resource to handle we need to

  • Handle the HTTP GET method
  • Read the callback parameter in the query string. We will use the name of the function to wrap our result
  • Produce the MIME type in the Accept header

The following JAX-RS resource should handle the JSONP request

public class CustomerResource {

   @PersistenceContext EntityManager em;

   public String get(@PathParam("id") Integer id ,
         @QueryParam("callback") String callback) {

      Customer cust = em.find(Customer.class, id); 
      if (null == cust)
         throw WebApplicationException(Response.Status.NOT_FOUND);

      //Convert object to JSON
      JsonObjectBuilder builder = Json.createObjectBuilder();
      return (callback + "(" + + ")");

The code is quite straightforward. We inject the callback query string into the handler which we subsequently use to wrap the result.

As you can see, its quite simple to handle JSONP.

JSONP as MessageBodyWriter

JAX-RS has a pair of SPI call MessageBodyReader and MessageBodyWriter that allows anyone to handle marshalling and unmarshalling of objects from HTTP to JAX-RS resources. I wrote a simple MessageBodyWriter , called JSONP4JAXRS, that simplifies the entire process (if you don’t mind adding 12K to to your project).

If you’re using JSONP4JAXRS, then the above CustomerResource can rewritten as follows

public class CustomerResource {

   @PersistenceContext EntityManager em;

      public String get(@PathParam("id") Integer id ) {

      Customer cust = em.find(Customer.class, id); 
      if (null == cust)
         throw WebApplicationException(Response.Status.NOT_FOUND);

      //Convert object to JSON
      JsonObjectBuilder builder = Json.createObjectBuilder();
      return (; 

No more fiddling around with callback parameter. The MessageBodyWriter will automatically pad the JsonObject with the callback.

But wait! There is more!

JSONP4JAXRS will automatically pad any return types according to the following rules:

Return Type Padding (assume fn is the name of the callback function)
JsonObject fn({ … }) where { … } is the JsonObject
JsonArray fn([ … ]) where [ … ] is the JsonArray
Any primitives including their  wrappers fn({“value”: the_value })
Any object fn({“value”: toString_value_of_object})
Iterable  fn([ … ]) The Iterable is converted to a JsonArray and the elements are converted according the the above rule

Don’t forget to wrap your Iterable (eg. List<JsonObject>) in a GenericEntity if you are returning the result via a Response.

The JSONP4JAXRS contains a class call JsonWithPadding that defines the following constants for JSONP MIME types

Constant Name MIME Type
APPLICATION_JAVASCRIPT application/javascript
APPLICATION_JSON application/json
APPLICATION_ECMASCRIPT application/ecmascript
APPLICATION_X_ECMASCRIPT application/x-ecmascript
TEXT_JAVASCRIPT text/javascript

JSONP4JAXRS works with Java EE 7 only. JSONP4JAXRS can be downloaded here. The source and binaries are in the compile NetBeans project file. The binaries is in dist directory.

Till next time.

Persisting Backbone.js Models and Collections to JAX-RS

There are many competing Javascript framework available; one of the more common and popular framework is Backbone.js. One of its claim to fame over other Javascript frameworks its persistence. (No flames please)

Like other framework, Backbone.js allows you to define models and collections to represent your data; you can then use Backbone.js build in REST features to persist your models and collections to a backend system.

I was recently given the opportunity to use Backbone.js with Java EE, specifically connecting from Backbone.js to a some RESTful resource. I’ll document what I’ve learnt in this blog; the database used here is not the actual database.

The blog will be broken into 3 parts

  • The first part we will look at how to map a model to a JAX-RS root resource and a JPA entity
  • The second part we will extend from mapping a model to a collection
  • The third part we will look at PATCH support

We will be using the following table throughout this blog


The customer table (from JavaDB in NetBeans) is mapped to the following JPA entity. Note: for the sake of simplicity, I’ve not mapped all the fields and also I’ve not included any relationship

@Entity @XmlRootElement
public class Customer implements Serializable {
   @Id @Column(name=”customer_id”) private Integer customerId;
   private String name;
   private String addressLine1, addressLine2;
   private String city, state;
   private String email, fax, phone
   private Integer creditLimit;
   //Properties for the above members – not shown
   . . .

The @XmlRootElement annotation allows JAX-RS to automatically convert the a customer entity to JSON (as well as XML).


Exposing Customer Entity as a RESTful Resource

We will now use JAX-RS to provide a REST interface for the Customer entity. If you’re not familiar with JAX-RS, see this tutorial.

But before we proceed to code the class, we need to decide the resource identifier; the obvious choice is customer/id where id is the primary key entity.

public class CustomerResource {
   @PersistenceContext EntityManager em;
   public Response get(@PathParam(“id”) int custId) {
      Customer customer = em.find(Customer.class, custId);
      if (null == customer)
         return (Response.status(Response.Status.NOT_FOUND)
      return (Response.ok(customer).build());
   . . .

Using a REST client for testing Customer resource


Click to enlarge

So if you look closely at the resource URI you will notice the following URI


Reading the URI from left to right, the first customer is the the application context. This is followed by webresources. The webresource is the base URI and is used as a prefix for all other resource URI. This value specified in the @ApplicationPath annotation on the Application subclass. If you are using NetBean, this subclass is generated for you and the base URI defaults to “webresources”.

Finally customer/1 is the actual URI of CustomerResource; this is defined in defined in @Path.


Mapping to Backbone Model

We will now define a Backbone model to map to customer resource. There are 3 things that we need to know:

  • The first is associating the Model’s id to the JPA’s entity primary key;
  • The second is mapping the resource identifier to JAX-RS root resource’s path.
  • Finally the HTTP method. This will largely depend on what  the model is performing. eg a Model.fetch() will generate a GET method

Lets look at JPA first. By default all Backbone model assumes that the name of the primary key is called id. In our case above, the primary key is called customerId. We have to tell Backbone this otherwise a Backbone will not know the identity of the model if we perform any of the CRUD operations on the model or collections. To map the primary key use the idAttribute.

To retrieve and update backend data, all Backbone models need the URI fo the REST resource. Since we are using JAX-RS, we need to know the URI of the resource. If we map the model to the above defined REST resource, then we need to assign the URI  webresources/customer to the urlRoot property (assuming that our JavaScript is loaded from http://localhost:8080/customer/index.html).

var Customer = Backbone.Model.extend({
   initialize: function() {
      console.log(“created: “ + this.get(“name”));
   idAttribute: “customerId”, //PK mapping
   urlRoot: “webresources/customer” //REST URI mapping

To retrieve customerId 1, from we do the following

var customer = new Customer();
customer.set({customerId: 1})

The result of the fetch() shown below

result Click to enlarge

If you are unfamiliar with the workings of Backbone.js persistence, read the excellent free book by Addy Osmani here.

I will leave CUD as an exercise for the reader.


Mapping to Backbone Collections

One of the concept of RESTful resource is the idea of a container; a container is just a collection of RESTful resource. So we can have a container for Customers. Unlike Java collections, RESTful containers you should not hold the Customer data but a URI to that data. See “Link things together” in this article. So the following is an example of Customer container in JSON

   { “id”: 1, “name”: “Jumbo Eagle Corp",
   { “id”: 2, “name”: . . .

Notice that although there are information like customer id and name, the key is the url which the URI to the actual resource. Lets look at how we can create just such a collection

public class CustomersResource {
   @PersistenceContext EntityManager em;
   @Context UriInfo ui;
   public Response get(
         @DefaultValue(“0”) @QueryParam(“start”) int start,
         @DefaultValue(“-1”) @QueryParam(“count”) int count) {
      TypeQuery<Customer> query = em.createNamedQuery(
            “Customer.findAll”, Customer.class);
      if (count > 0)
      List<CustomerReference> refs = new LinkedList<>();
      UriBuilder builder = ui.getBaseUriBuilder()
      for (Customer c: query.getResultList()) {
         URI uri = builder.clone().build(c.getCustomerId());
      GenericEntity<List<CustomerReference>> response =
            new GenericEntity<List<CustomerReference>>(refs){};
      return (Response.ok(response).build());
   . . .

The URI of the Customer container is /customers. The resource allows you to specify a cursor (start) and also the number of records to retrieve (count). You can of course add other query string to the GET like a pattern to match etc.  The rest of the code is quite straight forward.

The CustomerReference is a class to hold the result. It is defined as follows

public class CustomerReference {
   private String id;
   private String name;
   private String url;
   //Getter and setters – not shown

Mapping a collection to /customers URI is very similar to mapping a model. The only difference is you use url instead of urlRoot.

var Customers = Backbone.Collection.extend({
   model: Customer,
   url: “webresources/customers”

Once you have setup the model, you can say get 5 Customers starting from position 3

var custSet = new Customers();
custSet.fetch({data: {start: 3, count: 5}});

Partial Model Update with PATCH

One common problem with model is that if you just update one field, Backbone will send all the attributes of that model to the server to be persisted. The HTTP PATCH method allows you to specify only the subset of attributes to send back . Say you want to update the customer’s name and get Backbone to only send that attribute back, set the patch option to true when you are performing a save.

var cust = custSet.get(2);{name: "Fred"}, {patch: true});

Backbone will send a PATCH method with /customer/id URL back to the root resource. You can see this in the following

patch Click to enlarge

Now to write JAX-RS support. As I’m using Java EE 7 for this, I get to use new Json classes to map the values in. If you’re using EE 6, use an InputStream as a parameter to read to the method. Then use one of the Java libraries from to parse it to JSON.

First we define a HTTP PATCH method

public @interface PATCH { }

Next we add the method to handle PATH

public class CustomerResource {
   . . .
   public Response updateValues(JsonObject json) {
      //Update record – not shown
      . . .
      return (Response.ok().build());
. . .

The full source including all the missing methods is available here. I have to disguise the source as a Word file because Word Press will not allow me to upload zips. Just download it and rename the suffix to zip. Its a NetBeans project file.

Let me know what you think. Thanks for reading.

Till next time…

%d bloggers like this: