RESTful Web Services Developer's Guide

Chapter 4 Creating, Deploying, and Running Jersey Applications

This chapter provides an introduction to creating, deploying, and running your own Jersey applications. This section demonstrates the steps that you would take to create, build, deploy, and run a very simple web application that is annotated with Jersey.

Another way that you could learn more about deploying and running Jersey applications is to review the many sample applications that ship with Jersey. When you install the Jersey add-on to GlassFish, these samples are installed into the as-install/jersey/samples directory. If you have installed Jersey in another way, read the section Installing and Running the Jersey Sample Applications for information on how to download the sample applications. There is a README.html file for each sample that describes the sample and describes how to deploy and test the sample, and there is a Project Object Model file, pom.xml, that is used by Maven to build the project.

Note –

For GlassFish v3 Prelude release only, Jersey-based applications that use the JSP Views feature need to bundle the Jersey JAR files with the application WAR file. An example of how this is done can be found in the bookstore sample application.

Using NetBeans to Create Jersey Applications

This section gives a simple introduction to using Jersey in NetBeans.

Creating a Jersey-Annotated Web Application using NetBeans IDE

This section describes, using a very simple example, how to create a Jersey-annotated web application.

Before You Begin

Before you can deploy a Jersey application using NetBeans, you must have installed the RESTful Web Services plugin, as described in Installing Jersey in NetBeans.

In NetBeans IDE, create a simple web application. For this example, we will work with a very simple “Hello, World” web application.
1. Open NetBeans IDE.
2. Select File->New Project.
3. From Categories, select Java Web. From Projects, select Web Application. Click Next.
4. Enter a project name, HelloWorldApp, click Next.
5. Make sure the Server is GlassFish v3 Prelude.
6. Click Finish.

The project will be created. The file index.jsp will display in the Source pane.

Right-click the project and select New, then select RESTful Web Services from Patterns.
1. Select Singleton to use as a design pattern. Click Next.
2. Enter a Resource Package name, like HelloWorldResource. For MIME Type select text/html.
3. Enter /helloworld in the Path field. Enter HelloWorld in the Resource Name field.
4. Click Finish.
  
  A new resource, HelloWorldResource.java, is added to the project and displays in the Source pane.

In HelloWorldResource.java, modify or add code to resemble the following example.

/**
     * Retrieves representation of an instance of helloworld.HellowWorldResource
     * @return an instance of java.lang.String
     */
    @GET
    @Produces("text/html")
    public String getXml() {
        return "<html><body><h1>Hello World!</body></h1></html>";
    }

    /**
     * PUT method for updating or creating an instance of HelloWorldResource
     * @param content representation for the resource
     * @return an HTTP response with content of the updated or created resource.
     */
    @PUT
    @Consumes("application/xml")
    public void putXml(String content) {
    }

Deploying and Testing a Jersey Application using NetBeans IDE

This section describes building, deploying, and testing a Jersey-annotated application using NetBeans IDE.

Right-click the project node and click Test RESTful Web Services.

This step will deploy the application and bring up a test client in the browser.

When the test client displays, navigate to the helloworld resource and click the Test button.

The words Hello World! will display in the Response window.

Deploying and Testing a Jersey Application Without NetBeans

The following sections describes how to deploy and run a Jersey application without using the NetBeans IDE. This example describes copying and editing an existing Jersey sample application. An example that starts from scratch can be found here.

Deploying and Testing a Jersey Application without NetBeans

The easiest way to create and run an application without NetBeans is to copy and edit one of the Jersey sample applications. We'll use the simplest sample application, HelloWorld, to demonstrate one way you could go about creating your own application without NetBeans IDE.

Before You Begin

Before you can deploy an application to GlassFish from the command line, you must have downloaded and installed Jersey onto GlassFish, as described in Adding Jersey to GlassFish.

Copy the HelloWorld application to a new directory named helloworld2.

Do a search for all directories named helloworld and rename them to helloworld2.

Search again for all files containing the text helloworld and edit these files to replace this text with helloworld2.

Using a text editor, open the file jersey/samples/helloworld2/src/main/java/com/sun/jersey/samples/helloworld/resources/HelloWorldResource.java.

Modify the text that is returned by the resource to Hello World 2. Save and close the file.

Use Maven to compile and deploy the application. For this sample application, it is deployed onto Grizzly. Enter the following command from the command line to compile and deploy the application: mvn compile exec:java.

Open a web browser, and enter the URL to which the application was deployed, which in this examples is http://localhost:9998/helloworld2. Hello World 2 will display in the browser.

Deploying a RESTful Web Service

This section is taken from the document titled Overview of JAX-RS 1.0 Features.

JAX-RS provides the deployment-agnostic abstract class Application for declaring root resource classes and root resource singleton instances. A Web service may extend this class to declare root resource classes, as shown in the following code example.

public class MyApplicaton extends Application {
    public Set<Class<?>> getClasses() {
        Set<Class<?>> s = new HashSet<Class<?>>();
        s.add(HelloWorldResource.class);
        return s;
    }
}

Alternatively, it is possible to reuse a Jersey implementation that scans for root resource classes given a classpath or a set of package names. Such classes are automatically added to the set of classes that are returned by the getClasses method. For example, the following code example scans for root resource classes in packages org.foo.rest, org.bar.rest, and in any their sub-packages.

public class MyApplication extends PackagesResourceConfig {
    public MyApplication() {
        super("org.foo.rest;org.bar.rest");
    }
}

For servlet deployments, JAX-RS specifies that a class that implements Application may be declared instead of a servlet class in the <server-class> element of the application deployment descriptor, web.xml. As of this writing, this is not currently supported for Jersey. Instead it is necessary to declare the Jersey-specific servlet and the Application class, as shown in the following code example.

<web-app>
    <servlet>
        <servlet-name>Jersey Web Application</servlet-name>
        <servlet-class>com.sun.jersey.spi.container.servlet.ServletContainer</servlet-class>
        <init-param>
            <param-name>javax.ws.rs.Application</param-name>
            <param-value>MyApplication</param-value>
        </init-param>
    </servlet>
    ....

An even simpler approach is to let Jersey choose the PackagesResourceConfig implementation automatically by declaring the packages as shown in the following code.

<web-app>
    <servlet>
        <servlet-name>Jersey Web Application</servlet-name>
        <servlet-class>com.sun.jersey.spi.container.servlet.ServletContainer</servlet-class>
        <init-param>
            <param-name>com.sun.jersey.config.property.packages</param-name>
            <param-value>org.foo.rest;org.bar.rest</param-value>
        </init-param>
    </servlet>
    ....

JAX-RS also provides the ability to obtain a container-specific artifact from an Application instance. In the following code example, Jersey supports using Grizzly.

SelectorThread st = 
	RuntimeDelegate.createEndpoint(new MyApplication(), 
	SelectorThread.class);

Jersey also provides Grizzly helper classes to deploy the ServletThread instance at a base URL for in-process deployment. The Jersey samples provide many examples of servlet-based and Grizzly-in-process-based deployments.

Chapter 4 Creating, Deploying, and Running Jersey Applications

Using NetBeans to Create Jersey Applications

Creating a Jersey-Annotated Web Application using NetBeans IDE

Before You Begin

Deploying and Testing a Jersey Application using NetBeans IDE

See Also

Deploying and Testing a Jersey Application Without NetBeans

Deploying and Testing a Jersey Application without NetBeans

Before You Begin

See Also

Deploying a RESTful Web Service