Having used Apache Wink to  implement my basic JAX-RS service, which simply retrieves some information from Library, details of a Book Edition given its ISBN, I next want to implement an operation to add an Edition to the library. This operation will use a POST method to the resource

    http://myhost/LibraryWink/library/editions

that is, the resource that specifies that entire collection. Once again, the JAX-RS programming model makes the implementation of the service operation very easy, but I stumbled across a minor annoyance in testing the operation from Dojo, so in this posting I’ll take a side trip into the Dojo JavaScript libraries.

JAX-RS POST implementation

I already have a resource implementation class and so I just need to add a method to process the POST request

@POST
@Consumes({MediaType.APPLICATION_JSON,MediaType.APPLICATION_XML})
@Produces({MediaType.APPLICATION_JSON,MediaType.APPLICATION_XML})
public BookEdition addNewEdition(BookEdition edition) {
    return EditionStore.getInstance().addEdition(edition);
}

There are a few points to note here.

• The input parameter edition is not annotated. Contrast this with the GET example,  getEditionByIsbn(@PathParam("isbn") String isbn), which enabled access to an element from the URI. Here the edition parameter is mapped to the request body, that is the content which is POSTed. Such a parameter is termed an Entity parameter. A method may have at most one entity parameter.
• I have decided to permit both JSON and XML payloads to be Posted. JSON is very convenient from Dojo, as we shall see, but other clients may prefer XML. The Wink JAX-RS implementation will deal with deserializing JSON or XML depending upon the MediaType of the request.
• As a design decision, I have chosen to return the state representation of the added edition. In this case it’s overkill as the state was passed in and we make no modifications in adding it to the Library. However in general it’s quite possible that there is some enrichment of data as it is inserted into the store. Hence I use the general pattern of returning a representation of what has been stored.

Testing with Poster

We can quickly test this method using a Firefox extension: Poster.

Specifying an Edition in XML

    <Edition>
      <title>Invincible</title>
      <author>John Power</author>
      <isbn>B000NZ8Y9Q</isbn>
     </Edition>

and the content type application/xml. The response is as expected, containing a representation of the Edition we added. In the same way, we can provide a JSON payload

    {"Edition":
      {"title": "Invincible",
       "author": "John Power",
      "isbn":"B000NZ8Y9Q"
    }}

And content type application/json. The content type of the response is determined by the HTTP Header field Accept with a value of application/xml or application/json.

Testing from Dojo

One very likely scenario for using REST services is to call  an operation from an Browser-based rich client application. The Dojo JavaScript libraries are one possible technology for constructing such applications.

This is some sample code which invokes the addNewEdition() operation:

      var myEdition = {"Edition":{“author”:”x”, “title”"isbn":"44"}};
      var xhrArgs = {
                url: http://myhost/LibraryWink/library/editions,
                postData: dojo.toJson(myEdition),
                handleAs: "json",
                headers: { "Content-Type": "application/json"},
                load: function(data) {
                    dojo.byId("mainMessageText").innerHTML
                           =  "Message posted.";
                },
                error: function(error) {
                    dojo.byId("mainMessageText").innerHTML
                            = "Error :" + error;
                }
            };
        dojo.byId("mainMessageText").innerHTML
                           = "Message being sent…"; 
        var deferred = dojo.rawXhrPost(xhrArgs);

I’ll quickly summarise a few key features here, but first note in particular the actual POST request:

    dojo.rawXhrPost(xhrArgs);

You note that I use rawXhrPost rather than

    dojo.xhrPost(xhrArgs);

I can find no documentation that explains why rawXhrPost() is needed, but after much experimenting and imprecating I discovered that rawXhrPost() does indeed work and that xhrPost() sends no payload.

The other salient points:

• postData: dojo.toJson(myEdition) converts the payload object to JSON.
• headers: { "Content-Type": "application/json"} sets the MimeType in the header, hence allowing JAX-RS to correctly interpret the JSO string – the handleAs property relates to the interpretation of any response from the service
• The url: http://myhost/LibraryWink/library/editions is our resource URI

Next – Unit Testing

So, that’s two ways of exercising a REST service, however as a test mechanism both leave a few things to be desired. In the next posting I’ll move on to using JAS-RS client

JAX-RS is a specification addressing the implementation of providers and consumers of REST services in Java. Apache Wink is an Open Source implementation of that specification. To give an idea of what is possible: you can annotate a Java Class like this

    @Path(“/books”)
    public class LibraryResource {

    @GET
    @Produces( MediaType.APPLICATION_JSON)
    public BookCollection getBooks() {
          // implementation here

    }

and deploy this class along with the Wink framework to an Application Server and you have immediately implemented a RESTful service with a URI

    http://myhost/rest/books

In this posting I will explain in detail how to use Apache Wink to implement a service like this. I will be creating RESTful services for a simplified, fictional Lending library. First, a reminder of the problems addressed by JAX-RS. I’ve described the service providers responsibilities in more detail in this posting but in summary we first need to do some up-front design work:

• Identify some resources, in our case these could be Books, Editions, Authors, Categories and Borrowers
• Decide on the URIs that identify these resources, both individual resources and collections of resources.
• Design the services, giving appropriate meanings to methods such as GET, PUT, POST and DELETE

Then we write code and exploit JAX-RS (and JAXB) to address these implementation problems:

1. Transform between the State of a Resource and its Transfer Representation. That is, manage the conversion between a Java Object and an XML or JSON representation of its attributes.
2. Interpret the URI of a service request and direct the request to the appropriate Resource Manager, which we have developed in Java.
3. Map the HTTP method (GET, PUT …) to appropriate methods of the Resource Manager.
4. Enable the resource manager to use the details of the URI to identify particular resources. for example

   http://myhost/rest/borrowers/12345

   would identify a borrower with id 12345

5. Give access to qualifying parameters such as search criteria

Preparation

I am using Rational Application Developer 7.5  (RAD) and the WebSphere Application Server 7.0 (WAS) test environment provided by RAD. I downloaded Apache WINK and then added WINK jar files to my dynamic web project.

Download Wink

Apache WINK can be downloaded from Wink Download. I downloaded

apache-wink-1.0-incubating.zip

This contains directories

• dist – the core of Wink
• lib –  wink supporting libraries
• ext/wink-json-provider – JSON formatting and parsing

There is also documentation and examples.

Creating and Populating Web Project

In RAD create an Application (EAR) project and Dynamic Web Project, then add the Wink JAR files, define the Wink servlet and create packages for the Java Classes we will write shortly. The next sections describe these steps in more detail.

Wink JAR files

Copy the following jar files from the Wink distribution to the WEB-INF lib directory of the dynamic web project.

From dist

wink-server-1.0-incubating.jar
wink-common-1.0-incubating.jar

From lib:

jsr311-api-1.0.jar
slf4j-api-1.5.8.jar
slf4j-simple-1.5.8.jar

(note that instead of slf4j-simple-1.5.8.jar you may prefer to use a different slf4j implementation such as slf4j-jdk14-1.5.8.jar, you can download that from here.

From ext/wink-json-provider

lib/json-20080701.jar
wink-json-provider-1.0-incubating.jar

So my LibraryEar and LibraryWink projects now look like this

Wink Servlet

Edit WEB-INF/web.xml, add the servlet definition.

  <servlet>
        <servlet-name>restSdkService</servlet-name>
        <servlet-class>org.apache.wink.server.internal.servlet.RestServlet</servlet-class>
        <init-param>
            <param-name>applicationConfigLocation</param-name>
            <param-value>/WEB-INF/application</param-value>
        </init-param>
        <load-on-startup>0</load-on-startup>
    </servlet>

    <servlet-mapping>
        <servlet-name>restSdkService</servlet-name>
        <url-pattern>/library/*</url-pattern>
    </servlet-mapping>

This has the effect of mapping all URLs begging with “library” to the Wink REST servlet.

The Web project now shows a servlet:

We will create our own resource manager classes with JAX-RS annotation that will implement the service function and hook that servlet to call our implementation: note that the servlet has an initialisation parameter applicationConfigLocation which refers to a file

    /WEB-INF/application

the purpose of this file is to register our resource manager code with the Wink servlet. We’ll create that file once we have written the code.            

Creating Packages

I created two packages to differentiate two kinds of Class used in the service implementation:

• org.djna.library.service: the resource manager classes, these being the classes that offer the service interfaces themselves
• org.djna.library.resources: the resource state classes, which hold the data passed to and from the service methods, these classes will be serialised to and from JSON and XML

In the next section I’ll describe how to implement the state and resource manager classes

Information using JAXB

I  first create classes to hold the state of the various resources in our system. In this example they will be simple Java Beans with with minimal  business logic, effectively just Data Transfer Objects that will be serialised to and from JSON or XML. Something I want to study in the future is the relationship between these resource objects and JPA Entities.

Book Edition

We’ll start with a simple class representing an Edition of a Book. In this simple example the class has few attributes:

          package org.djna.library.resources;

     import java.util.Date;

public class BookEdition {
    private String title;
    private String author;
    private String isbn;
    private Date publicationDate;

The isbn uniquely identifies the book edition.

I generated getters and setters for every field, for example

    public String getTitle() {
        return title; 
  } 
  public void setTitle(String title) {
        this.title = title; 
  }

I also created a two constructors, one takes no arguments and one allowing a fully populated BookEdition to be created.

    public BookEdition() {
        title = null;
        author = null;
        isbn = null;
        publicationDate = null;
    }
       public BookEdition(String nTitle,
            String nAuthor,
            String nIsbn,
            Date nPublicationDate){
        title = nTitle;
        author = nAuthor;
        isbn = nIsbn;
        publicationDate = nPublicationDate;
    }

The zero argument constructor is required by JAXB.

Annotating for Serialization

The BookEdition class will be passed to and from the REST service and so must be serializable. This is quickly accomplished by adding annotations to the class.

@XmlAccessorType(XmlAccessType.PROPERTY)
@XmlRootElement(name = "Edition") 
public class BookEdition {

These two annotations are sufficient to enable BookEdition to be transformed to and from XML and JSON.

• The XmlAccessorType, with parameter  XmlAccessType.PROPERTY specifies that the attributes to be serialised will be deduced from the presence of Getters and Setters in the class. This a very simple use of JAXB. JAXB has many other capabilities, for example by using other XmlAccessTypes you can expose attributes directly. Also, if necessary you can get finer control over which fields are to be serialised and their serialized representations by applying other annotations to individual attributes.
• XmlRootElement specifies the root element of the XML or JSON payload.

Resources using JAX-RS

Next I create a Resource Manager which will offer services to manipulate BookEditions and specify a base URI for the services. I then create the individual service methods which act on particular resources and collections of resources. In order to enable testing of the services I create a Mock Data Store for Book Editions which simply works with a few hard-coded examples.

This assumes that I have already made decisions about the URIs I intend to use to access my resources.  For this simple case, with only a single kind of resource the following URIs (I show only the significant portion of the URI, prepend http://myhost/rest to all these) will be sufficient:

• /editions : all book editions
• /editions?query=XXX : editions matching query
• /editions/0858835544 : a particular edition specified by its ISBN

In the remainder of this posting I’ll focus on implementing that final operation, the retrieval of an Editions’s state specified by its ISBN.

Resource Manager Class

JAX-RS has a rich set of capabilities for mapping REST URIs to methods of resoruce manager classes. I’ implemented a very simple case: a single resource manager with methods for each particular operation I wanted to expose.

Resource Manager Class and Path

The resource manager class is an an arbitrary class, no special requirements for inheritance or interface implementation. It is annotated  to specify the URIs that will be dispatched to this class

    package org.djna.library.service;

    import javax.ws.rs.Path;

    @Path("/editions")
     public class BookEditionResources {

The context root for the Web Application is LibraryWink and the servlet is mapped to library hence the base URI for the REST services exposed by this resource manager is

   http://myhost/LibraryWink/library/editions

Next I prepared some example, hard-coded data items.

Example Data

The EditionStore class is included in the project ZIP file (TBD).

Retrieve One Item – GET

The first method I implemented retrieved a single edition, specified by its ISBN. That is, we implement a GET method for the URI

   http://myhost/LibraryWink/library/editions/0858835544

The method in the resource manager looks like this

   @Path("{isbn}")
    @GET
    @Produces( MediaType.APPLICATION_JSON)
    public BookEdition getEditionByIsbn(@PathParam("isbn") String isbn) {
        return EditionStore.getInstance().getEdition(isbn);
    }

The JAX-RS runtime has a flexible algorithm for matching the request to the service method, this considers the matching of the request URI to the @PATH annotations for class and method, the HTTP method types (GET, POST …) and also the requested Media Types.  In the general case the algorithm  needs to deal with the possibilities of there being many resource managers each with many methods. There is an explanation of the algorithm here.

In this getEditionByIsbn() example we see that the method is annotated with @GET to indicate that it deals with HTPP GET requests, and with @Produces( MediaType.APPLICATION_JSON) to specify that the response is in JSON format. It is possible to specify more than one Media type (for example both XML and JSON) in which case the client may specify its preference.

The @Path("{isbn}") annotation is a little more complex. Two things are happening here. First, this Path is used in conjunction with the overall ResouceManager class Path annotation so that the request URI that will be serviced by this method will look like this

     http://myhost/LibraryWink/library/editions/XXXXX

where XXXX will be a specific ISBN. The second thing that is being specified is that the isbn portion of the URI is to be accessible as a parameter, the parameter having the name isbn.

This now gives a context for the final annotation: @PathParam("isbn") the method declaration

    getEditionByIsbn(@PathParam("isbn") String isbn)

specifies that the Java method takes a single String parameter, and the annotation of that parameter tells JAX-RS to populate that parameter from the URI path.

Application Configuration

You may remember that we need to configure the Wink REST servlet to use our application code. We do this by creating a simple text file in the location specified by the servlet’s applicationConfigLocation parameter, that is a text fille: WEB_INF/application

The contents of the file is a simple list of resource manager classes, in our case just

    org.djna.library.service.BookEditionResources

Execute

I can now deploy the code to the WAS test environment and using a browser issue the GET request

  http://myhost/LibraryWink/library/editions/1900924323

The response is a simple JSON string containing the details of the Edition with ISBN 1900924323

   { "Edition": {
     "author": "Brian Hinton, Geoff Wall",
     "isbn": "1900924323",
     "publicationDate": "2002-03-27T14:45:43.437+00:00",
     "title": "The Guvnor"
   }  }

Conclusion 

The experience of coding a RESTful service using the Apache Wink implementation of JAX-RS is pretty good, I wrote very little code and achieved a working implementation very quickly. There’s a few directions for further study:

• The relationship between our resource classes and JPA entities. Can we (and should we) annotate a class with both JPA and JAXB annotations?
• How easy will it be to implement PUT, POST and DELETE?
• How easily can we implement queries across collections?
• JAX-RS has various techniques for allowing to refactor resource manager logic, with flexible URI path specifications. Are there obvious patterns for using these capabilities?
• JAX-RS enables various life-cycle models for resource managers. How easy are they to use?

RESTful services are particularly useful for Web 2.0 developers and are pleasingly easy to develop in Java using the Apache Wink implementation of JAX-RS. You can get more detail about REST starting here in Wikipedia in this posting I want to illustrate the significance of  JAX-RS by considering the responsibilities of the a developer who wants to provide a REST service. In a more detailed posting I describe in detail how to use Wink to create a few simple services for a Lending Library.

REpresentation State Transfer (REST) is concerned with the State of resources and passing of representations of that state between client and server. So, we need to understand:

• what is meant by a resource
• how URIs are used to specify particular resources
• how requests to retrieve and manipulate the state of a resource are defined by the client
• the representation of the state as it is transfered between client and server

Resources

Resources may be any entity (or collection of entities) owned by a service provider. They are often familiar business entities such as Customers and Orders. I am  library examples we might have Books and DVDs. We also treat collections of entities as resources, for example “All orders placed today” or “Books written by Alastair Reynolds”.

We can easily imagine a simple mapping between records in a Relational Database and the resources managed by a service provider. However we can also treat more abstract information as resources., for example “The temperature now in London” or “The current stock price for IBM on the NYSE”.

So our first task as a REST service provider is to identify the resources our service is managing. Typically we will give some detailed consideration as to how clients would like to refer to the resource and that leads to define the URIs by which clients with specify the resources.

URI

Strictly speaking REST services can use many different technologies, they are not limited to the use of Web technologies and HTTP protocols, but here I am going to focus on the most common case, accessing resources specified by a URI using HTTP (or HTTPS).

The service provider will define the URIs that specify particular resources. In our library example we might have

• http://my.library.org/books  which would be a collection of all books
• http://my.library.org/books/abc001 which references a particular book using its identifier abc001

and we can similarly use URIs to specify more abstract information such as

• http://my.weather.org/current/uk/london/temperature

We see here a more extensive URI hierarchy and this indicates the extent of design effort that may be required in the resource identification activity so that we can define the URIs to be used.

This leads to some specific implementation coding tasks:

1. The URI http://my.library.org/books must in some way map to code that actually manages the book resources, and similarly the http://my.weather.org/current URI must be associated with the resource manager for the current weather resources.
2. The resource manager must interpret more precise URIs in order to identify the specific resources. So  uk/london/temperature must be interpreted correctly, the implementer needs structured access to the URI.

The implementation tasks are addressed by JAX-RS, and in the more detailed article I describe how to use JSX-RS annotations to complete the service implementation.

These ideas are extended further to allow the passing of parameters in the URI, in the example the collection URI is  modified by some search criteria

http://my.library.org/books?author=doyle

JAX-RS has annotations to allow access to parameters of various kinds.

Methods

RESTful architecture using HTTP explicitly exploits of HTTP methods such as GET, PUT, POST and DELETE, to define actions on resources:

• GET: retrieve a representation of the resources specified by the URI
• PUT: replace the state of the resource specified by the URI with new values
• POST: add a new resource, typically the URI will be that of a collection and the specified ID will be be generated by the resource manager or derived from the payload
• DELETE: remove the resource specified by the URI

This too leads to specific coding tasks: the implementer needs to map from the HTTP method to the appropriate action.

Representation

The resource representation returned from  a GET or (for example) specified in a PUT can be in arbitrary format as specified by the MIME type of the request, usually that type would be application/xml for XML application/json for JSON.

From the service provider’s perspective this leads to two further tasks:

1. To determine the request MIME type
2. To parse requests or format responses in accordance with that type.

JAX-RS has annotation capabilities to deal with different MIME types, however the corresponding  parsing and formatting is not part of the JAX-RS as such, but rather is provided by JAXB, hence we will need to use some JAXB annotations when supporting the chosen MIME types.

Here are the slides that I have prepared for my talk at JavaForum this evening. It took me some time to cut it down to 34 slides and then still many of them had to become extra spare slides. I had to realize that 30 minutes is really not much time. On the other hand I’ve seen many 10 minute lightning talks where the speaker manages to deliver the essence of a pretty complicated topic, so I shouldn’t really complain.

This is a little late, but anyway…

Two weeks ago I attend one more of the Globalcode’s Casual Class‘es. This one was about JAVAEE 6 and the main technologies that will be part of it when it comes out – apparently very soon.

I don’t have many pictures because I’m very smart and let my mobile’s battery run out… but let’s go through a few of the ones I got and talk about the contents of this event.

Preparations

The event was split in a few individual topics, among them: JSF 2.0, JAX-RS, EJB 3.1 and JPA 2.0. Each one had different presenters, all of them great speakers! =)

JSF 2.0

JSF 2.0 was presented by Yara Senger and Alberto “Spock” Lemos. They mentioned some changes that are coming to JSF, and used a small demo application, SCRUM Toys, to explain how they got involved into actually using the new features.

JPA 2.0

Melissa Vilela spoke about the new features coming in JPA 2.0. There are a lot of nice things. Among them, the new Criteria API is not. To be brutally honest, that thing is ridiculously complex. It is clearly lacking some usage of the KISS principle.

Then there was a presentation about REST, more specifically JAX-RS. (no pictures, sorry). Nothing really new here, just the fact that the API, which was already done and available, is going to be part of JAVAEE 6.

EJB 3.1

The last topic was EJB 3.1. Like with EJB 3.0, things are moving towards a simpler development model, and this is what was presented. Nice, simplifications to EJBs are always welcome! =)

After that, Pizza! uhu! My only complain this time is that the technical sessions took longer than usual, and I was really hungry in the end! But it was well worth the time =)

This post shows you some tips you’ll likely need to use JSP with Jersey in typical Java webapps.

Tested Conditions

While Jersey 1.1.1-ea or later is probably the only hard requirement for the tips to work, my development environment is listed here for your info. You are welcome to add to this rather meager basis for sanity.

1. Jersey 1.1.1-ea
2. Tomcat 6.0.20
3. JDK 1.5
4. OS X Leopard

Change JSP Base Template Path

Default base path for templates is the root of the webapp. So if my webapp is at “/…/webapps/myapp” then Viewable(“/mypage”, null) will map to “/…/webapps/myapp/mypage.jsp”

To change this, say to “WEB-INF/jsp” as it’s commonly done for security reasons, add following init-param to Jersey servlet/filter in web.xml:

<init-param>
<param-name>com.sun.jersey.config.property.JSPTemplatesBasePath</param-name>
<param-value>/WEB-INF/jsp</param-value>
</init-param>

Return Viewable as part of Response

It was not obvious to me (doh) where Viewable fits into Response when I have to return a Response instead of Viewable. It turns out, Viewable can be passed where message body entity is passed. Example:

return Response.ok(new Viewable("/mypage", model).build();

Use “/*” as servlet-mapping for Jersey

The primitive servlet-mapping URI pattern scheme, which somehow survived many iterations of the servlet API, impacts JAX-RS hard if servlet-mapping is overly broad. Unfortunately, pretty restful URL calls for servlet-mapping to be “/*” instead of something like “/jersey/*”, breaking access to JSP files as well as static resources.

To work around, you’ll have to use Jersey as a filter instead of a servlet and edit a regular-expression init-param value to punch passthrough holes in Jersey’s routing scheme. To enable this, replace Jersey servlet entry in web.xml with something like this:

<filter>
 <filter-name>jersey</filter-name>
 <filter-class>com.sun.jersey.spi.container.servlet.ServletContainer</filter-class>
 <init-param>
  <param-name>com.sun.jersey.config.property.WebPageContentRegex</param-name>
  <param-value>/(images|js|styles|(WEB-INF/jsp))/.*</param-value>
 </init-param>
</filter>
<filter-mapping>
 <filter-name>jersey</filter-name>
 <url-pattern>/*</url-pattern>
</filter-mapping>

That’s all for now. Hope this post saved you some headaches.

This tutorial will start with a sample top artists (i.e favorite artists) file from http://ws.audioscrobbler.com/2.0/?method=user.gettopartists&user=Firari&api_key=b25b959554ed76058ac220b7b2e0a026. It will follow several steps to write a dynamic client GTK UI for the topartists service. Project depends on java-gnome (4.0.12+), jsr311-api (aka jax-rs), jersey-core and jersey-client libraries. Note that there’s a Java library for accessing Last.FM web services available at http://www.u-mass.de/lastfm Project files can be downloaded as a tarball.

Step 1: Generating XML schema from the sample XML

I downloaded a sample file from the the given URL. I used Trang to reverse engineer the XSD from XML. The command line tool just takes 2 arguments, the input xml and the output xsd files. Here’s the generated XSD file.

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified">
  <xs:element name="lfm">
    <xs:complexType>
      <xs:sequence>
        <xs:element ref="topartists"/>
      </xs:sequence>
      <xs:attribute name="status" use="required" type="xs:NCName"/>
    </xs:complexType>
  </xs:element>
  <xs:element name="topartists">
    <xs:complexType>
      <xs:sequence>
        <xs:element maxOccurs="unbounded" ref="artist"/>
      </xs:sequence>
      <xs:attribute name="type" use="required" type="xs:NCName"/>
      <xs:attribute name="user" use="required" type="xs:NCName"/>
    </xs:complexType>
  </xs:element>
  <xs:element name="artist">
    <xs:complexType>
      <xs:sequence>
        <xs:element ref="name"/>
        <xs:element ref="playcount"/>
        <xs:element ref="mbid"/>
        <xs:element ref="url"/>
        <xs:element ref="streamable"/>
        <xs:element maxOccurs="unbounded" ref="image"/>
      </xs:sequence>
      <xs:attribute name="rank" use="required" type="xs:integer"/>
    </xs:complexType>
  </xs:element>
  <xs:element name="name" type="xs:string"/>
  <xs:element name="playcount" type="xs:integer"/>
  <xs:element name="mbid" type="xs:string"/>
  <xs:element name="url" type="xs:anyURI"/>
  <xs:element name="streamable" type="xs:integer"/>
  <xs:element name="image">
    <xs:complexType>
      <xs:simpleContent>
        <xs:extension base="xs:anyURI">
          <xs:attribute name="size" use="required" type="xs:NCName"/>
        </xs:extension>
      </xs:simpleContent>
    </xs:complexType>
  </xs:element>
</xs:schema>

Step 2: Generating data classes for mapping the xml

xjc (JAXB Binding Compiler) is used to generate the classes in generated package. Jersey can utilize JAXB to map the result XML to data classes.

Step 3: Writing code to query Last.FM web service

public static Lfm queryTopArtists(String userName) {
	final Client client;
	final WebResource webResource;
	final MultivaluedMap queryParams;
	final Lfm result;

	client = Client.create();
	webResource = client.resource("http://ws.audioscrobbler.com/2.0");
	queryParams = new MultivaluedMapImpl();
	queryParams.add("method", "user.gettopartists");
	queryParams.add("user", userName);
	queryParams.add("api_key", "b25b959554ed76058ac220b7b2e0a026");
	result = webResource.queryParams(queryParams).get(Lfm.class);
	return result;
}

Here we’re building the HTTP request along with the parameters in the query string. And finally we’re calling the service and mapping the result to Lfm class which corresponds to XML’s root element lfm.

Step 4: The GTK+ GUI

Here were initializing the table and its data model.

/*
 * Initialize the table with its DataColumn's.
 */
model = new ListStore(new DataColumn[] { rank = new DataColumnString(),
		artistImage = new DataColumnPixbuf(),
		artist = new DataColumnString(),
		playCount = new DataColumnString(),
		percent = new DataColumnInteger() });
view = new TreeView(model);

Here we’re creating the view columns and binding their properties to data model. Note that were’re binding 2 properties of the CellRendererProgress to different columns in the data model.

/*
 * Create TreeViewColumns and bind the DataColumn's to their properties.
 */
vertical = view.appendColumn();
vertical.setTitle("Rank");
rendererText = new CellRendererText(vertical);
rendererText.setText(rank);

vertical = view.appendColumn();
rendererPixbuf = new CellRendererPixbuf(vertical);
rendererPixbuf.setPixbuf(artistImage);

vertical = view.appendColumn();
vertical.setTitle("Artist");
rendererText = new CellRendererText(vertical);
rendererText.setText(artist);

vertical = view.appendColumn();
vertical.setTitle("# of times played");
rendererProgress = new CellRendererProgress(vertical);
/*
 * It's nice that in GTK+ we can bind multiple DataColumn's to
 * properties of a single TreeViewColumn.
 */
rendererProgress.setText(playCount);
rendererProgress.setValue(percent);

Here we’re querying the service (i.e calling the utility method we wrote) and populating the table. The image data will be fetched asynchroniously by AsyncImageLoader which is a subclass of Thread (Its code wil follow)

/*
 * Query Last.FM user.gettopartists method JAX-RS handles the Webservice
 * call and JAXB handles the unmarshalling of the XML response.
 */
result = LastFMUtil.queryTopArtists("Firari");

/*
 * Add the properties of Artist items as TreeView rows.
 */
if (result.getStatus().equals("ok")) {
	final List<Artist> topArtists = result.getTopartists().getArtist();
	/*
	 * Determining maximum playcount from top of the list.
	 * It will be used to calculate the percentage of the ProgressBar's.
	 */
	maxPlayCount = topArtists.get(0).getPlaycount().floatValue();
	for (final Artist artistItem : topArtists) {
		final TreeIter row = model.appendRow();
		model.setValue(row, rank, artistItem.getRank().toString());
		/*
		 * Asynchronously load the image data and set it as the image
		 * column. The first image URL is the "small" one.
		 */
		new AsyncImageLoader(model, row, artistImage, artistItem.getImage().get(0).getValue()).start();
		model.setValue(row, artist, artistItem.getName());
		model.setValue(row, playCount, artistItem.getPlaycount().toString());
		model.setValue(row, percent, Math.round(artistItem.getPlaycount().intValue() / maxPlayCount * 100));
	}
}

Here’s the code for AsyncImageLoader.

class AsyncImageLoader extends Thread {
	private ListStore model;
	private TreeIter row;
	private DataColumnPixbuf artistImage;
	private String url;

	public AsyncImageLoader(ListStore model, TreeIter row,
			DataColumnPixbuf artistImage, String url) {
		super();
		this.model = model;
		this.row = row;
		this.artistImage = artistImage;
		this.url = url;
	}

	@Override
	public void run() {
		try {
			/*
			 * Fetch the image data and set it as the image column of the
			 * specified row.
			 */
			URL artistImageURL = new URL(url);
			URLConnection artistImageConnection = artistImageURL
					.openConnection();
			DataInputStream in = new DataInputStream(artistImageConnection
					.getInputStream());
			byte[] artistImageData = new byte[artistImageConnection
					.getContentLength()];
			in.readFully(artistImageData);
			/*
			 * The image will have 32 pixels height.
			 */
			model.setValue(row, artistImage, new Pixbuf(artistImageData, -1,
					32, true));
		} catch (IOException e) {
			e.printStackTrace();
		}
	}
}

Here’s a screenshot of the running application.

I have put together some slides about the basic principles in REST. The real presentation is actually implemented as a JAX-RS application. I started out with a django version, but I needed a Java-angle on it so I had to switch to JAX-RS.

Stay tuned …

As you know that in XML you can represent the same data in variety of ways by using fields, names, attributes, etc..

The same is true to JSON. In many cases different serializers produce different JSON representation of the same objects.

JAX-RS (as well as Jersey) provide you control over what and how you want to serialize. This is accomplished via providers.

Here is an example of such provider (Note that the class should be marked with @Provider annotation):

@Provider
public class JAXBContextResolver implements ContextResolver<JAXBContext> {
    private JAXBContext context;
    private Class<?>[] types = { ListDescription.class }; 

    public JAXBContextResolver() throws Exception {
        JSONConfiguration config = JSONConfiguration.natural().build();
        context = new JSONJAXBContext(config, types);
    } 

    public JAXBContext getContext(Class<?> objectType) {
        for (Class<?> type : types) {
            if (type == objectType) {
                return context;
            }
        }
        return null;
    }
}

Note that by creating an appropriate JSONConfiguration (JSONConfiguration.natural().build()) you, in fact, control the output JSON format. The JSONConfiguration class provide 4 different JSON formatters:

1. natural (Jackson)
2. mapped
3. mappedJettison
4. Badgerfish

Here is how the output will vary, depending on the choice of the configuration. Don’t forget that the class should be annotated with A simple class (with fields (int)ID and (String)Name) added to an ArrayList and then returned back as a @GET return value:

@XmlRootElement
public class ListDescription
{
	public int ID;
	public String Name;
}

@GET
@Produces({MediaType.APPLICATION_JSON })
public List<DataListInfo> getAllLists()
{
	List<ListDescription> lists = new ArrayList<ListDescription>();
	ListDescription ls = new ListDescription();
	ls.ID = 1;
	ls.Name = "Test";
	lists.add(ls);
	return lists;
}

This is what you’ll get from each configuration (respectively):

mappedJettison:

{"listDescriptions":{"listDescription":{"ID":1,"Name":"Test"}}}

mapped:

{"listDescription":{"ID":"1","Name":"Test"}}

natural (jackson):

[{"ID":1,"Name":"Test"}]

Badgerfish:

{"listDescriptions":{"listDescription":{"ID":{"$":"1"},"Name":{"$":"Test"}}}}

In the previous article (Part 1) we’ve seen how to create a web-based REST-full client (and an appropriate server) by using GWT. GWT is not providing any “standard” REST (if you can use this word in REST context at all) interface, but, merely, exposes the server-side logic via a proprietary GWT RPC interface.

Today, the most common REST standard is the JAX-RS specification. By implementing your code along the JAX-RS guidelines you can be rest assured that you can easily switch one REST-RX library with another.

As of today there are a couple of JAX-RS libraries used by the Java community:

1. Jersey
2. Restlet
3. Portlet
4. etc…

On the other hand, being a big fan of Spring, I was hoping that Spring will provide the JAX-RS support in it’s Spring v3 release, but, looking at the M3 drop, I have realized that it’s nowhere near that promise (check my discussion on the StackOverflow).

For this post I’m going to use Jersey JAX-RS implementation. Let’s start with creating

a Dynamic Web Project in Eclipse. I’m going to use:

1. Apache Tomcat v6.0
2. Dynamic Web Module v2.5
3. Default Configuration for Apache Tomcat v6.0

To add Jersey (1.1.0-ea) into this mix, add the following JARs (from this obscure installation instructions page) to your build path:

1. asm-3.1.jar
2. jsr311-api-1.1.jar
3. jersey-bundle-1.1.0-ea.jar
4. jersey-json-1.1.0-ea.jar
5. jaxb-impl-2.1.10.jar

Don’t forget to add these JARs to the “Java EE Module Dependencies” (in the properties of the project) as well.

Let’s define our Web Service. By using the JAX-RS specification it becomes extremely easy:

@PerRequest
@Path("/contacts")
@Consumes({ MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML })
@Produces({ MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML })
public class ContactManagerService {
    final static List<ContactInfo> contacts = new ArrayList<ContactInfo>();
    static {
        contacts.add(new ContactInfo("Joe", "Simth", "Some Company"));
        contacts.add(new ContactInfo("Tom", "Doe", "Another Company"));
    } 

    @GET
    public ContactList getAllContacts()
    {
        return contacts;
    } 

    @GET
    @Path("{filter}")
    public ContactList getFilteredContacts(@PathParam("filter") String filter)
    {
        ...

        return ContactList.fromContacts( contacts );
    } 

}

A couple of things to notice here:

1. The “root” path to the ContactManager Web service marked by tompost annotation @Path("/contacts"), is: /contacts
2. This class returns data in both application/json and application/xml formats. This is defined by the @Produces({ MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML }) annotations.
3. The “default” method for this web service is “getAllContacts”. This is happening because this method has NO @Path annotation.
4. The “getFilteredContacts” will be called if the Web Services URL will contain a non-empty addition to the root URL, like this: /contact/joe
   1. Note that this addition should be URL-encoded
   2. If you’d like to replace it with the query param – replace the annotation with the @QueryParam one. In this case the call will look like /contacts?filter=joe

The ContactList, that is returned to the client, should be annotated with @XmlRootElement so Jetty will fire up an appropriate the JAXB provider for the serialization (we’ll talk more about providers later):

@XmlRootElement
public class ContactList { 

    @XmlElement
    protected java.util.List<ContactInfo> contacts; 

    public ContactList() { ... }

}

As you can guess, there is no magic in the world (I, actually, still hope that there is some so, to make our service visible to the outside world, we need to make sure that Tomcat loads Jersey which, in its order, will load and expose our service according to our annotations. This is done via the additional configuration in the web.config file:

<!-- Servlets -->
<servlet>
    <servlet-name>ContactManager Web Services</servlet-name>
    <servlet-class>com.sun.jersey.spi.container.servlet.ServletContainer</servlet-class>
    <load-on-startup>1</load-on-startup>
</servlet>
<servlet-mapping>
    <servlet-name>ContactManager Web Services</servlet-name>
    <url-pattern>/services/*</url-pattern>
</servlet-mapping>

After completing all the above you can start Tomcat and use any of the available REST test clients like Fiddler, RESTClient or RESTTest (see discussion on StackOverflow) to see our service in action.

The root URL to the ContactManagerService is http://localhost:8080/ContactManagerServer/services/contacts.

If the request will contain header “Accept: application/json” the result will look like this:

{"contacts":[{"FirstName":"Joe","LastName":"Simth","Company":"Some Company"},
{"FirstName":"Tom","LastName":"Doe","Company":"Another Company"}]}

On the other hand the header “Accept: application/xml” will produce result like this:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<contactList>
	<contacts><FirstName>Joe</FirstName><LastName>Simth</LastName><Company>Some Company</Company></contacts>
	<contacts><FirstName>Tom</FirstName><LastName>Doe</LastName><Company>Another Company</Company></contacts>
</contactList>

Disregard format of the returned content for a moment, we’re going to talk about serialization in later posts.

More information about the JSON support in Jersey can be found in the Jersey User Guide.

Recently, I’ve been working on a side project which has given me the opportunity to play with an interesting Java technology stack. After a few weekends of working on the build and moving my way up the stack from database to service layer I was at the point of writing a full integration test. In the past I’ve done integration testing with an iBatis/Spring stack, which, with the help of DBUnit is a fairly simple exercise. However, this project is heavily REST based and the addition of Jersey (JAX-RS) was a serious curveball.

To really test the whole stack an embedded webserver is required.  Looking through the Jersey/Spring unit tests they make use of an exploded WAR using Glassfish.  Assuming this was the optimal solution I added Glassfish to my ivy.xml config and ran an ivy update.  However, once I realized the overwhelming volume of jars being downloaded I decided it was much too heavy weight of a solution.

My next choice was Jetty.  I have had experience with using Jetty in the past but I quickly ran into issues trying to get it working right with Jersey, Spring, and an exploded WAR configuration.  It was then that I saw the GrizzlyServerFactory referenced in another Jersey unit test.  After some prodding and reading into the source code I ended up with the following:

final URI baseUri = UriBuilder.fromUri( "http://localhost/" ).port( 9998 ).build();
final ServletAdapter adapter = new ServletAdapter();
adapter.addInitParameter( "com.sun.jersey.config.property.packages", <your-package-name> );
adapter.addContextParameter( "contextConfigLocation","classpath:applicationContext.xml" );
adapter.addServletListener( "org.springframework.web.context.ContextLoaderListener" );
adapter.setServletInstance( new SpringServlet() );
adapter.setContextPath( baseUri.getPath() );
SelectorThread threadSelector = GrizzlyServerFactory.create( baseUri, adapter );

We start by making a base Uri for localhost at a high numbered port.  Then we build the Grizzly ServletAdaptor.  The first parameter is the package name where your Jersey enabled are located.  The next two lines are taken directly from the web.xml file that is used for the actual WAR.  The first is the config location for the Spring Context and the second is the ContextLoaderListener servlet.  Finally we add the Jersey SpringServlet and the context path.  With these two objects created we can build a SelectorThread and begin using the server using the Jersey Client api that I talked about in my previous post.  When you are done, don’t forget to call stopEndpoint() on the SelectorThread when you are done.

EDIT:

I’ve recently come across one additional helpful tip regarding this setup. If you need to get access to your ApplicationContext, for instance to get access to the spring managed DataSource for database testing, there is a simple but non obvious way of doing this. The simple part is using Spring’s built in utilities for getting the application from a ServletContext.

WebApplicationContextUtils.getWebApplicationContext( adapter.getServletInstance().getServletConfig().getServletContext() );

However, when I first tried this I got an unexplained null pointer exception. After a long while trying to google around for the answer I gave up and dug into the source code. Turns out you need to add one important property to the ServletAdaptor for this to all work.

adapter.setProperty( "load-on-startup", 1 );

This will force your adaptor to initialize the servlet immediately and you populate the ServletConfig and ServletContext so you can get the ApplicationContext from them.

Recently, I’ve been working on a side project which has given me the opportunity to play with an interesting Java technology stack. After a few weekends of working on the build and moving my way up the stack from database to service layer I was at the point of writing a full integration test. In the past I’ve done integration testing with an iBatis/Spring stack, which, with the help of DBUnit is a fairly simple exercise. However, this project is heavily REST based and the addition of Jersey (JAX-RS) was a serious curveball.

To really test the whole stack an embedded webserver is required.  Looking through the Jersey/Spring unit tests they make use of an exploded WAR using Glassfish.  Assuming this was the optimal solution I added Glassfish to my ivy.xml config and ran an ivy update.  However, once I realized the overwhelming volume of jars being downloaded I decided it was much too heavy weight of a solution.

My next choice was Jetty.  I have had experience with using Jetty in the past but I quickly ran into issues trying to get it working right with Jersey, Spring, and an exploded WAR configuration.  It was then that I saw the GrizzlyServerFactory referenced in another Jersey unit test.  After some prodding and reading into the source code I ended up with the following:

final URI baseUri = UriBuilder.fromUri( "http://localhost/" ).port( 9998 ).build();
final ServletAdapter adapter = new ServletAdapter();
adapter.addInitParameter( "com.sun.jersey.config.property.packages", <your-package-name> );
adapter.addContextParameter( "contextConfigLocation","classpath:applicationContext.xml" );
adapter.addServletListener( "org.springframework.web.context.ContextLoaderListener" );
adapter.setServletInstance( new SpringServlet() );
adapter.setContextPath( baseUri.getPath() );
SelectorThread threadSelector = GrizzlyServerFactory.create( baseUri, adapter );

We start by making a base Uri for localhost at a high numbered port.  Then we build the Grizzly ServletAdaptor.  The first parameter is the package name where your Jersey enabled are located.  The next two lines are taken directly from the web.xml file that is used for the actual WAR.  The first is the config location for the Spring Context and the second is the ContextLoaderListener servlet.  Finally we add the Jersey SpringServlet and the context path.  With these two objects created we can build a SelectorThread and begin using the server using the Jersey Client api that I talked about in my previous post.  When you are done, don’t forget to call stopEndpoint() on the SelectorThread when you are done.

I recently had the need interact with Twittervision’s RESTful api from Java. As usual, I started googling around for a solution but nothing obviously stood out. There are a handful of RESTful java frameworks, but these focus on providing a RESTful api and not consuming one. Finally, after an annoyingly difficult search I found an impressively simple solution based on Jersey.

The point to realize is that Jersey provides both a sever and a client api. To make use of the client api requires three simple lines:

Client client = Client.create();
WebResource webResource = 
client.resource("http://twittervision.com/user/current_status/bdarfler.json");
String response = webResource.get(String.class);

The result is a string of JSON, but now, how to parse it. After searching around I ended up settling on json-simple. A few simple lines of code and we can get the address for any twitter user.

final JSONObject jsonObj = (JSONObject) JSON_PARSER.parse( response );
if ( jsonObj != null && jsonObj.containsKey( "location" ) )
{
final JSONObject location = (JSONObject) jsonObj.get( "location" );
return location.get( "address" ).toString();
}

So, once again, simple stuff but not as obvious as I was hoping it would be.

So ready to jump start into JBoss RESTEasy? Dive!

Writing the JAX-RS Class

The first step, let us write a simple echo service using JAX-RS:

package testpackage;

import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.PathParam;
import javax.ws.rs.core.Response;

@Path("/echo")
public class Echo {
    @GET
    @Path("/{message}")
    public Response echoService(@PathParam("message") String message){
        return Response.status(200).entity(message).build();
    }
}

Adding the JBoss RESTEasy dependency to Maven project

If you are using Maven to build your projects, add the dependency for RESTEasy:

<dependency>
    <groupId>org.jboss.resteasy</groupId>
    <artifactId>resteasy-jaxrs</artifactId>
    <version>1.0.0.GA</version>
</dependency>

Also remember to add the JBoss repository to the pom.xml (RESTEasy is not available in Maven public repository):

<repository>
    <id>jboss</id>
    <url>http://repository.jboss.com/maven2/</url>
    <releases>
        <enabled>true</enabled>
    </releases>
    <snapshots>
        <enabled>false</enabled>
    </snapshots>
</repository>

Configuring web.xml

The bare minimum needed to have RESTEasy running is:

<web-app ...>
    ...
    <listener>
        <listener-class>org.jboss.resteasy.plugins.server.servlet.ResteasyBootstrap</listener-class>
    </listener>

    <servlet>
        <servlet-name>Resteasy</servlet-name>
        <servlet-class>org.jboss.resteasy.plugins.server.servlet.HttpServletDispatcher</servlet-class>
    </servlet>

    <servlet-mapping>
        <servlet-name>Resteasy</servlet-name>
        <url-pattern>/*</url-pattern>
    </servlet-mapping>
    ...
</web-app>

Above, we have just added the RESTEasy servlet and listener. Now we have to make it load our JAX-RS class. This can be done in two ways. One, just let RESTEasy scan the CLASSPATH to identify and load JAX-RS resources:

<web-app ...>
    ...
    <context-param>
        <param-name>resteasy.scan</param-name>
        <param-value>true</param-value>
    </context-param>
    ...
</web-app>

The other option is to specify the resources manually (use CSV format):

<web-app ...>
    ...
    <context-param>
        <param-name>resteasy.resources</param-name>
        <param-value>testpackage.Echo</param-value>
    </context-param>
    ...
</web-app>

After deploying this, you may access your application (if your are using default Tomcat/Jetty installation): http://localhost:8080/resteasytest/echo/hello,world (assumes your application is deployed as resteasytest.war)

I have been awaiting the GA release of RESTEasy for some time! Now we have an alternative to Glasssfish Jersey JAX-RS engine.