Introduction

Apache Wink is becoming one of the de facto implementations of the JAX-RS specification. JSON.org and Jettison, the default providers for JSON synchronization, have some problems. For example, their array representation and limited return types make coding JAX-RS services, and their client Ajax applications, difficult.

This article outlines a method for configuring an existing Apache Wink-enabled Web application to use the Jackson JSON provider. Learn about the advantages of this provider by using sample code for a simple Jackson-enabled JAX-RS Web service.

Back to top

JSON providers packaged with Apache Wink

Apache Wink packages two JSON providers as part of the standard distribution: JSON.org and Jettison implementations. Both of these providers have issues that complicate the integration of Wink services with Ajax applications. Neither provider can directly serialize a Java List to JSON as a return type because of the JAXB requirement for an encompassing XML element. Both providers also have additional problems, such as:

JSON.org

Array serialization with the JSON.org provider is predictable, but the behavior is undesirable when interacting with Ajax. When presented with arrays of varying sizes, JSON.org represents them differently:

• 2+ : "Correct" array serialization. For example: object : { array : ["element1", "element2"] }
• 1 : Collapses the array. For example: object : { array : "element1" }
• 0 : Removes the array entirely. For example: object : { }

It's clear that coding allowances for the different structures in Javascript make for extra, undesired complexity.

Jettison

Jettison uses the Badgerfish convention for JSON generation, producing structures that can be hard to navigate after they're converted to Javascript objects.

Back to top

Jackson

At its core, Jackson is a JSON processor used for both generation and parsing of JSON representations of Java objects. Jackson can also be configured as a JSON serialization provider for JAX-RS implementations.

As a JAX-RS JSON serialization provider, Jackson has several advantages over its JSON.org and Jettison counterparts, as described below.

Back to top

Configuring Apache Wink for Jackson

The instructions for the example in this article assume that:

• You have an existing dynamic Web project configured to use Apache Wink as a JAX-RS provider.
• The Wink servlet, org.apache.wink.server.internal.servlet.RestServlet, is configured in the web.xml file to use a JAX-RS application, as shown in Listing 1.

	
<servlet>
  <servlet-name>WinkServlet</servlet-name>
  <servlet-class>org.apache.wink.server.internal.servlet.RestServlet</servlet-class>
  <init-param>
    <param-name>javax.ws.rs.Application</param-name>
    <param-value>com.ibm.developerworks.winkJackson.WinkApplication</param-value>
  </init-param>
  <load-on-startup>1</load-on-startup>
</servlet>
<servlet-mapping>
  <servlet-name>WinkServlet</servlet-name>
  <url-pattern>/services/*</url-pattern>
</servlet-mapping>
			

Download and install Jackson libraries

From the Jackson Web site, download the latest version of the Jackson provider (see Resources for a link). At the time of writing, the Jackson team does not provide a single download resource for all the libraries required to use Jackson with Apache Wink. You'll need either ASL or LGPL versions of the JAR files, as follows.

• core-(asl/lgpl): the Jackson core functions
• mapper-(asl/lgpl): POJO <-> JSON serialization
• jax-rs: the interface between Wink and Jackson
• jax-xc: backwards compatibility with JAXB annotations

The JAR files must be present on the classpath of your Web project. The simplest way to do this is to place them in your WEB-INF/lib directory. (It is likely that your Apache Wink JAR files are already in this directory.)

Configure Apache Wink to use the Jackson provider for JSON serialization

At this point, the Jackson JSON provider is being loaded as part of your Web application, but Apache Wink has not been instructed to use it for JSON serialization.

Adjust the Wink servlet's configured application to load the provider, as shown in Listing 2.

				
package com.ibm.developerworks.winkJackson;

import java.util.HashSet;
import java.util.Set;

import javax.ws.rs.core.Application;

// Jackson imports
import org.codehaus.jackson.jaxrs.JacksonJaxbJsonProvider;
import org.codehaus.jackson.map.AnnotationIntrospector;
import org.codehaus.jackson.map.ObjectMapper;
import org.codehaus.jackson.map.introspect.JacksonAnnotationIntrospector;
import org.codehaus.jackson.xc.JaxbAnnotationIntrospector;

public class WinkApplication extends Application {

  /**
   * Get the list of service classes provided by this JAX-RS application
   */
  @Override
  public Set<Class<?>> getClasses() {
    Set<Class<?>> serviceClasses = new HashSet<Class<?>>();
    serviceClasses.add(HelloWorlds.class);
    return serviceClasses;
  }
  
  @Override
  public Set<Object> getSingletons() {
    Set<Object> s = new HashSet<Object>();
    
    // Register the Jackson provider for JSON
    
    // Make (de)serializer use a subset of JAXB and (afterwards) Jackson annotations
    // See http://wiki.fasterxml.com/JacksonJAXBAnnotations for more information
    ObjectMapper mapper = new ObjectMapper();
    AnnotationIntrospector primary = new JaxbAnnotationIntrospector();
    AnnotationIntrospector secondary = new JacksonAnnotationIntrospector();
    AnnotationIntrospector pair = new AnnotationIntrospector.Pair(primary, secondary);
    mapper.getDeserializationConfig().setAnnotationIntrospector(pair);
    mapper.getSerializationConfig().setAnnotationIntrospector(pair);
    
    // Set up the provider
    JacksonJaxbJsonProvider jaxbProvider = new JacksonJaxbJsonProvider();
    jaxbProvider.setMapper(mapper);
    
    s.add(jaxbProvider);
    return s;
  }

}

Back to top

Direct List<?> serialization

Jackson gives you the opportunity to easily return Java Lists from their functions, without the need for a wrapper JAXB XML element. Listing 3 shows an example.

				
package com.ibm.developerworks.winkJackson;

import java.util.Arrays;
import java.util.List;

import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;
import javax.ws.rs.core.MediaType;

@Path("helloworlds")
@Produces(MediaType.APPLICATION_JSON)
public class HelloWorlds {
  
  @GET
  public List<String> helloWorlds() {
    return Arrays.asList(new String [] {"Hello Earth!",  "Hello Mars!" });
  }
	
}  

Back to top

Summary

Apache Wink is increasingly used as an implementation of the JAX-RS specification. JSON.org and Jettison, the default providers for JSON synchronization, have some problems. In this article, you learned about a method for configuring an existing Apache Wink-enabled Web application to use the Jackson JSON provider. An example highlighted the advantages of this provider by using sample code for a simple Jackson-enabled JAX-RS Web service.

Back to top

Download

Information about download methods

Resources

Learn

• "RESTful Web services with Apache Wink, Part 1: Build an Apache Wink REST service" (developerWorks, February 2010) introduces the Apache Wink JAX-RS provider.
  
  
• "RESTful Web services: The basics" (developerWorks, November 2008) introduces you to the basic principles of Representational State Transfer (REST).
  
  
• RESTful Java with JAX-RS explores how to design and develop distributed Web services in Java™ code using RESTful architectural principals and the JAX-RS specification in Java EE 6.
  
  

Get products and technologies

• Download Apache Wink and get the source code and binaries of the latest version of the framework, along with other example projects.
  
  
• Download the Jackson JSON Processor used in this article.
  
  
• Download IBM product evaluation versions or explore the online trials in the IBM SOA Sandbox and get your hands on application development tools and middleware products from DB2®, Lotus®, Rational®, Tivoli®, and WebSphere®.
  
  

Discuss

• developerWorks blogs: Check out developerWorks blogs and get involved in the developerWorks community.
  
  

About the author

Nick Maynard works for the IBM Software Solutions Transformation team in Hursley, UK. He specializes in Web programming, Linux, Web services, and business integration technologies. You can contact Nick at nick.maynard@uk.ibm.com.

Rate this article

Comments

Back to top

Table of contents

• Introduction
• JSON providers packaged with Apache Wink
• Jackson
• Configuring Apache Wink for Jackson
• Direct List<?> serialization
• Summary
• Download
• Resources
• About the author
• Comments

Next steps from IBM

Create rich Internet applications using WebSphere Portal Express Web 2.0 technologies.

---

• Try: WebSphere Portal Express
• Article: Get started using Ajax and WebSphere Portal Express
• Tutorial: Quickly build a an Ajax-enabled WebSphere Portal Express Web application
• Demo: Architecture, design, and construction using the IBM Rational Software Delivery Platform: AJAX
• Buy: WebSphere Portal Express

Dig deeper into SOA and Web services on developerWorks

Try IBM PureSystems. No charge.

Experience today!

---

Get started with the cloud-based trial and pattern development kit.

Special offers