Getting Started

Getting started with Jersey is very easy. First, download the latest distribution of Jersey and unzip it. Then, create a new project (using your favourite IDE or just ant/maven) and add the jar files in the Jersey distribution lib directory as compile time and run time dependencies of your project. (For those who want to skip the creation of their own project take a look at the last section of this document.)

Creating a Web 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        @ProduceMime("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 MIME media type. This is a key feature of JSR 311.

Deploying the Web resource

The Web resource will be deployed using the Lightweight HTTP Server included in the Jersey distribution and in Sun's Java Platform, Standard Edition 6 (Java SE 6) release.

Create the following Java class in your project:

 1    public class Main {
 2    
 3        public static void main(String[] args) throws IOException {
 4            // Create the HttpHandler
 5            // Pass in the HelloWorldResource class
 6            HttpHandler handler = ContainerFactory.createContainer(
 7                    HttpHandler.class,
 8                    HelloWorldResource.class);
 9
10            // Create the HTTP server using the HttpHandler
11            HttpServer server = HttpServer.create(
12                    new InetSocketAddress(9998),
13                    0);
14            server.createContext("/", handler);
15            server.setExecutor(null);
16            server.start();
17        
18            System.out.println("Server running");
19            System.out.println("Visit: http://localhost:9998/helloworld");
20            System.out.println("Hit return to stop...");
21            System.in.read();
22            System.out.println("Stopping server");   
23            server.stop(0);
24            System.out.println("Server stopped");
25        }    
26    }

The Main class deploys the HelloWorldResource using the Lightweight HTTP Server.

Lines 6 to 8 use the Jersey container API to create a HttpHandler that manages the dispatching of HTTP requests to the Jersey runtime, which in turn manages the dispatching (if the request matches) to an instance of the HelloWorldResource class.

Lines 11 to 13 sets up the HTTP server with the host address ("http://localhost:9998"). Line 14 sets the base URI of the HttpHandler ("/"). The complete URI of the Hello World Web resource is "http://localhost:9998/helloworld". Line 16 starts the HTTP server.

Notice that no deployment descriptors were needed and the Web resource was setup in just one statement of Java code. The container API enables multiple HTTP containers to be supported based on the Java type passed as the first parameter of the ContainerFactory.createContainer method. There is an SPI that enables developers to develop and register their own containers.

Testing the Web resource

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

Or, from the command line use curl:

    > curl http://localhost:9998/helloworld

Here's one I created earlier

The example code presented above is shipped as the HelloWorld project in the Jersey distribution (see the examples directory, or browse the project source). The example may be opened using NetBeans or may be run from the command line by typing ant run from the project directory.