Apache Wink : JAX-RS Getting Started

The following example project will produce a simple JAX-RS application that can respond to requests at "/helloworld" with a "Hello world!" plain text resource. While not entirely RESTful, this example project is to show how to create a simple application and how to package it for consumption in a web container.

The application is packaged in a WAR file (which is similar to a JAR/ZIP file, except with special files in certain locations and a defined layout). It can be deployed in any web container, for example: Jetty, Tomcat and Geronimo. Perform the following steps in order to create the "helloworld" example application.

Step 1 - Creating the Root Resource

First, create a resource that will be used for HTTP GET requests to "/helloworld".

package org.apache.wink.example.helloworld;

import javax.ws.rs.GET;
import javax.ws.rs.Path;

@Path("/helloworld")
public class HelloWorldResource {

    @GET
    public String getMessage() {
        return "Hello World!";
    }
}

As shown above, the Java class is just a plain old Java object that has JAX-RS annotations.

Step 2 - Creating a javax.ws.rs.core.Application sub-class

For non-JAX-RS aware web container environments (most environments are currently non JAX-RS aware), a javax.ws.rs.core.Application sub-class needs to be created which returns sets of JAX-RS root resources and providers. In the following example, there is only one root resource that will need to be returned.

package org.apache.wink.example.helloworld;

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

import javax.ws.rs.core.Application;

public class HelloWorldApplication extends Application {

    @Override
    public Set<Class<?>> getClasses() {
        Set<Class<?>> classes = new HashSet<Class<?>>();
        classes.add(HelloWorldResource.class);
        return classes;
    }

}

Compiling the classes

Using the Apache Wink distribution's JARs in the classpath, compile the two classes from the previous example.

Step 3 - Creating a web.xml file

Now create a web.xml deployment descriptor. The deployment descriptor details information about the web application in the WAR. In this case, it says that the Apache Wink JAX-RS servlet should be initialized with a HelloWorldApplication instance.

In addition, any requests that begin with /rest/ will be handled by the Apache Wink JAX-RS servlet. So, the request URL would be "/rest/helloworld" to reach the HelloWorld resource.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE web-app PUBLIC
 "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
 "http://java.sun.com/dtd/web-app_2_3.dtd" >

<web-app>
    <display-name>Hello world Web Application</display-name>
    <servlet>
        <servlet-name>HelloWorldApp</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>org.apache.wink.example.helloworld.HelloWorldApplication</param-value>
        </init-param>
        <load-on-startup>1</load-on-startup>
    </servlet>
    <servlet-mapping>
        <servlet-name>HelloWorldApp</servlet-name>
        <url-pattern>/rest/*</url-pattern>
    </servlet-mapping>
</web-app>

Step 4 - Packaging the web application into a WAR file

Layout the application as follows and create a WAR file from the base directory (the one before WEB-INF). Create a WAR by running "jar cvf helloworld-jaxrs.war *" from the base directory.

Not every JAR in the lib directory is necessary for all environments. Read the documentation for more information about the requirements.

WEB-INF/classes/org/apache/wink/example/helloworld/HelloWorldApplication.class
WEB-INF/classes/org/apache/wink/example/helloworld/HelloWorldResource.class
WEB-INF/lib/activation-1.1.jar
WEB-INF/lib/commons-lang-2.3.jar
WEB-INF/lib/jaxb-api-2.1.jar
WEB-INF/lib/jaxb-impl-2.1.4.jar
WEB-INF/lib/json-20080701.jar
WEB-INF/lib/jsr311-api-1.0.jar
WEB-INF/lib/slf4j-api-1.5.8.jar
WEB-INF/lib/slf4j-simple-1.5.8.jar
WEB-INF/lib/stax-api-1.0-2.jar
WEB-INF/lib/wink-common-<version #>.jar
WEB-INF/lib/wink-server-<version #>.jar
WEB-INF/web.xml

Step 5 - Installing the WAR file into your environment

Most web container environments will take a WAR file and deploy it without any further configuration required. However, note the "Context Root" of the web application, or change it as required.

The context paths combine as follows:
http://<hostname>/<web application context root>/<servlet url mapping path>/helloworld