Use Apache Wink with the Jackson JSON processor

Simpler JAX-RS integration with Ajax

Apache Wink is fast becoming one of the de facto implementations of the JAX-RS 1.0 specification. The providers included with the standard Apache Wink distribution for JSON marshalling and unmarshalling, such as JSON.org and Jettison, have some problems with array representation and limited return types. Coding JAX-RS services and their client Asynchronous JavaScript and XML (Ajax) applications can be difficult. In this article, learn a method for configuring an existing Apache Wink-enabled Web application to use the Jackson JSON provider to solve some of the problems. An example, with sample code for a simple Jackson-enabled JAX-RS Web service, illustrates the advantages of this provider.

Nick Maynard, Senior Software Engineer, Industry and Business Solutions Team, IBM

Author photoNick 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.


developerWorks Contributing author
        level

20 April 2010

Also available in Chinese Japanese

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.


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.

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.

Table 1. Jackson advantages
AdvantageDescription
Ability to serialize Lists nativelyJackson can directly return a List of string objects from a service without a wrapper Xml element.
Array handling Jackson has excellent, predictable array serialization facilities.
Speed Measurably faster than other providers.
LicensingThe Apache License 2.0 is well-understood. Components using this license are used in both commercial and free software products.

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.
Listing 1. web.xml snippet for Wink servlet
<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.)

Join the Apache Wink group on My developerWorks

Discuss topics and share resources with other developers about RESTful Web services development with Apache Wink in the My developerWorks Apache Wink group.

Not a member of My developerWorks? Join now!

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.

Listing 2. Sample WinkApplication.java
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;
  }

}

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.

Listing 3. HelloWorlds.java
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!" });
  }
	
}

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.


Download

DescriptionNameSize
Sample HelloWorlds Eclipse project archiveHelloWorlds.zip8KB

Resources

Learn

Get products and technologies

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into Web development on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Web development, Java technology, SOA and web services
ArticleID=483886
ArticleTitle=Use Apache Wink with the Jackson JSON processor
publish-date=04202010