Links: Table of Contents | Single HTML

Chapter 1. Getting Started

Table of Contents

1.1. Creating a root resource
1.2. Deploying the root resource
1.3. Testing the root resource
1.4. Here's one Paul created earlier

This chapter will present how to get started with Jersey using the embedded Grizzly server. The last section of this chapter presents a reference to equivalent functionality for getting started with a Web application.

First, it is necessary to depend on the correct Jersey artifacts as described in Chapter 11, Dependencies

Maven developers require a dependency on

The following dependencies need to be added to the pom:

<dependency>
    <groupId>com.sun.jersey</groupId>
    <artifactId>jersey-server</artifactId>
    <version>1.12</version>
</dependency>
<dependency>
    <groupId>com.sun.jersey</groupId>
    <artifactId>jersey-grizzly2</artifactId>
    <version>1.12</version>
</dependency>

If you want to depend on Jersey snapshot versions the following repository needs to be added to the pom:

<repository>
    <id>snapshot-repository.java.net</id>
    <name>Java.net Snapshot Repository for Maven</name>
    <url>https://maven.java.net/content/repositories/snapshots/</url>
    <layout>default</layout>
</repository>

Non-maven developers require:

For Ant developers the Ant Tasks for Maven may be used to add the following to the ant document such that the dependencies do not need to be downloaded explicitly:

<artifact:dependencies pathId="dependency.classpath">
  <dependency groupId="com.sun.jersey"
              artifactId="jersey-server"
              version="1.12"/>
  <dependency groupId="com.sun.jersey"
              artifactId="jersey-core"
              version="1.12"/>
  <dependency groupId="com.sun.jersey"
              artifactId="jersey-grizzly2"
              version="1.12"/>
  <dependency groupId="org.glassfish.grizzly"
              artifactId="grizzly-http-server"
              version="2.2.1"/>
  <dependency groupId="org.glassfish.grizzly"
              artifactId="grizzly-http"
              version="2.2.1"/>
  <dependency groupId="org.glassfish.grizzly"
              artifactId="grizzly-framework"
              version="2.2.1"/>
  <dependency groupId="javax/ws/rs"
              artifactId="jsr311-api"
              version="1.1.1"/>
  <dependency groupId="asm"
              artifactId="asm"
              version="3.3.1"/>
  <artifact:remoteRepository id="maven-repository.java.net"
                             url="http://maven.java.net/" />
  <artifact:remoteRepository id="maven1-repository.java.net"
                             url="http://download.java.net/maven/1"
                             layout="legacy" />
</artifact:dependencies>

The path id “dependency.classpath” may then be referenced as the classpath to be used for compiling or executing.

Second, create a new project (using your favourite IDE or just ant/maven) and add the dependences. (For those who want to skip the creation of their own project take a look at Section 1.4, “Here's one Paul created earlier”

1.1. Creating a root resource

Create the following Java class in your project:

  1     // The Java class will be hosted at the URI path "/helloworld"
  2     @Path("/helloworld")
  3     public class HelloWorldResource {
  4     
  5         // The Java method will process HTTP GET requests
  6         @GET 
  7         // The Java method will produce content identified by the MIME Media
  8         // type "text/plain"
  9         @Produces("text/plain")
 10         public String getClichedMessage() {
 11             // Return some cliched textual content
 12             return "Hello World";
 13         }
 14     }

The HelloWorldResource class is a very simple Web resource. The URI path of the resource is "/helloworld" (line 2), it supports the HTTP GET method (line 6) and produces cliched textual content (line 12) of the MIME media type "text/plain" (line 9).

Notice the use of Java annotations to declare the URI path, the HTTP method and the media type. This is a key feature of JSR 311.

1.2. Deploying the root resource

The root resource will be deployed using the Grizzly Web container.

Create the following Java class in your project:

  1 import com.sun.jersey.api.container.grizzly2.GrizzlyServerFactory;
  2 import com.sun.jersey.api.core.DefaultResourceConfig;
  3 import com.sun.jersey.api.core.PackagesResourceConfig;
  4 import com.sun.jersey.api.core.ResourceConfig;
  5 import org.glassfish.grizzly.http.server.HttpServer;
  6 
  7 import javax.ws.rs.core.UriBuilder;
  8 import java.io.IOException;
  9 import java.net.URI;
 10 import java.util.HashMap;
 11 import java.util.Map;
 12 import java.util.Map.Entry;
 13 
 14 public class Main {
 15 
 16     private static URI getBaseURI() {
 17         return UriBuilder.fromUri("http://localhost/").port(9998).build();
 18     }
 19 
 20     public static final URI BASE_URI = getBaseURI();
 21 
 22     protected static HttpServer startServer() throws IOException {
 23         System.out.println("Starting grizzly...");
 24         ResourceConfig rc = new PackagesResourceConfig("com.sun.jersey.samples.helloworld.resources");
 25         return GrizzlyServerFactory.createHttpServer(BASE_URI, rc);
 26     }
 27     
 28     public static void main(String[] args) throws IOException {
 29         HttpServer httpServer = startServer();
 30         System.out.println(String.format("Jersey app started with WADL available at "
 31                 + "%sapplication.wadl\nTry out %shelloworld\nHit enter to stop it...",
 32                 BASE_URI, BASE_URI));
 33         System.in.read();
 34         httpServer.stop();
 35     }    
 36 }

The Main class deploys the HelloWorldResource using the Grizzly Web container.

Line 24 creates an initialization parameter that informs the Jersey runtime where to search for root resource classes to be deployed. In this case it assumes the root resource class in the package com.sun.jersey.samples.helloworld.resources (or in a sub-package of).

Line 25 deploys the root resource to the base URI "http://localhost:9998/" and returns a Grizzly HttpServer. The complete URI of the Hello World root resource is "http://localhost:9998/helloworld".

Notice that no deployment descriptors were needed and the root resource was setup in a few statements of Java code.

1.3. Testing the root resource

Goto the URI http://localhost:9998/helloworld in your favourite browser.

Or, from the command line use curl:

> curl http://localhost:9998/helloworld

1.4. Here's one Paul created earlier

The example code presented above is shipped as the HelloWorld sample in the Java.Net maven repository.

For developers wishing to get started by deploying a Web application an equivalent sample, as a Web application, is shipped as the HelloWorld-WebApp sample.