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.)
Create the following Java class in your project:
1 // The Java class will be hosted at the URI path "/helloworld" 2 @UriTemplate("/helloworld") 3 public class HelloWorldResource { 4 5 // The Java method will process HTTP GET requests 6 @HttpMethod("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.
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.
Goto the URI http://localhost:9998/helloworld in your favourite browser.
Or, from the command line use
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 curl
:
> curl http://localhost:9998/helloworld
Here's one I created earlier
ant run
from the project directory.