Example Applications for JAX-RS and Jersey

This section 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 test 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. These samples are installed into the as-install/jersey/samples directory. There is a README.html file for each sample that describes the sample and describes how to deploy and test the sample. These samples also include a Project Object Model file, pom.xml, that is used by Maven to build the project. The sample applications that ship with Jersey require Maven to run. The sample applications included with the tutorial will run using Ant.

Creating a RESTful Web Service

This section discusses two ways that you can create a RESTful web service. If you choose to use NetBeans IDE to create a RESTful web service, the IDE generates a skeleton where you simply need to implement the appropriate methods. If you choose not to use an IDE, try using one of the example applications that ship with Jersey as a template to modify.

Creating a RESTful Web Service Using NetBeans IDE

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

In NetBeans IDE, create a simple web application. This example creates 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 Sun GlassFish v3.
6. Click Finish. You may be prompted for your server User Name and Password. These may be admin and adminadmin, respectively.
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.
3. Enter /helloworld in the Path field. Enter HelloWorld in the Class Name field. For MIME Type select text/html.
4. Click Finish.
  A new resource, HelloWorld.java, is added to the project and displays in the Source pane. This file provides a template for creating a RESTful web service.

In HelloWorld.java, find the section that resembles the following method and modify or add code to resemble the following example.

Note - Because the MIME type that is produces is HTML, you can use HTML tags in your return statement.

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

Test the web service. To do this, 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, select the helloworld resource in the left pane, and click the Test button in the right pane.
The words Hello, World! will display in the Response window below.
Deploy and Run the application.
1. Set the Run Properties. To do this, right-click the project node, select Properties, and then select the Run category. Set the Relative URL to the location of the RESTful web service relative to the Context Path, which for this example is resources/helloworld.
  Tip - You can find the value for the Relative URL in the Test RESTful Web Services browser window. In the top of the right pane, after Resource, is the URL for the RESTful web service being tested. The part following the Context Path is the Relative URL that needs to be entered here.
  If you don't set this property, by default the file index.jsp will display when the application is run. As this file also contains Hello World as its default value, you might not notice that your RESTful web service isn't running, so just be aware of this default and the need to set this property.
2. Right-click the project and select Deploy.
3. Right-click the project and select Run.
  A browser window opens and displays the return value of Hello, World!

Creating a RESTful Web Service From Examples Without NetBeans IDE

The easiest way to create and run an application without NetBeans IDE is to copy and edit one of the Jersey sample applications. This task uses 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 the Jersey sample applications to GlassFish from the command line, you must have downloaded and installed Maven onto your system. You can install Maven from the Maven website at http://maven.apache.org.

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.

Creating a RESTful Web Service From Maven Archetype

Although this tutorial does not present instructions on using Maven for creating applications as a general rule, because Project Jersey is built, assembled and installed using Maven, and all of its sample applications are Maven-based, this section provides an example that creates a skeleton Jersey application from a Maven archetype.

Before You Begin

This example requires that Maven be installed and configured to run from the command line on your system. Maven can be downloaded from http://maven.apache.org/.

After Maven is installed, run the following from the command line:
mvn archetype:generate -DarchetypeCatalog=http://download.java.net/maven/2
The archetype catalog will download. You will be prompted to select the type of archetype you want to create. The command window will display this choice:
Choose archetype: 1: http://download.java.net/maven/2 -> jersey-quickstart-grizzly (Archetype for creating a RESTful web application with Jersey and Grizzly) 2: http://download.java.net/maven/2 -> jersey-quickstart-webapp (Archetype for creating a Jersey based RESTful web application WAR packaging) Choose a number: (1/2):
Select the appropriate option for the type of RESTful web service you would like to create.
With the Grizzly-based archetype (selection 1), you will get a sample Java application, which you can run directly from Java without a need to deploy it to any container. The web application archetype (selection 2) enables you to build a WAR archive, which you could deploy onto any web Servlet container.
Define a value for groupId.
Define a value for artifactId. This is the directory where the application is created.
Define value for version: 1.0–SNAPSHOT.
Define value for package: groupId. This is the directory where the main Java files will be located, which is basedir/artifactId/src/main/java/package.
Confirm properties configuration. Enter Y to confirm or N to cancel.
Maven generates a new project containing a simple Hello World RESTful web service.
Build and run your RESTful web service. First, change into the project directory, which is basedir/artifactId.
- For the Grizzly-based scenario (selection 1), build and run the web service on the Grizzy container using this command: mvn clean compile exec:java.
- If you selected the WAR-based scenario (selection 2), build your WAR file using the command mvn clean package. Deploy the WAR file to your favorite Servlet container. To run it using the embedded version of GlassFish V3, use this command: mvn glassfish:run.
Test the service in your browser.
- Enter the following URL to run the Grizzly-based application (selection 1): http://localhost:9998/myresource. This is the location where it is published by default. The browser displays the text Got it!
- Enter the following URL to run the WAR-based scenario (selection 2): http://localhost:8080/artifactId/webresources/myresource. This is the location where it is published by default. The browser displays the text Hi there!

Example: Creating a Simple Hello World Application Using JAX-RS and Jersey

This section discusses the simple RESTful web service that is included with the tutorial examples in the directory jaxrs/JAXRSHelloWorld. This example was created by following the steps similar to those described in Creating a RESTful Web Service Using NetBeans IDE.

JAXRSHelloWorld Example: Discussion

With this simple application, a singleton RESTful web service design pattern was selected. This design pattern generates a RESTful resource class with GET and PUT methods. This design is useful for creating examples such as this simple Hello World service.

In this example, the method getHtml() is annotated with @GET and the @Produces (“text/html”) annotation. This method will process HTTP GET requests and produce content in HTML. To finish this example, you simply need to replace the current contents of this example with a statement that returns Hello World. This example has also replaced the name of the method with the name sayHello. Here is the code for the completed sayHello() method:

@GET
    @Produces("text/html")
    public String sayHello() {
        return "Hello World";
    }

Testing the JAXRSHelloWorld Example

Open the project javaeetutorial/jaxrs/JAXRSHelloWorld in NetBeans IDE.
Right-click the project node, JAXRSHelloWorld, and select Test RESTful Web Services.
You may need to enter the user name (admin) and password (adminadmin).
Click the helloWorld service in the left pane.
The Get(text/html) method is selected by default. Click Test.
The response Hello World, displays in the lower pane, as shown in the following figure.
Figure 12-1 Testing JAXRSHelloWorld Web Service

Deploying and Running the JAXRSHelloWorld Example

Before You Begin

The application's Run properties must be set to run the RESTful web service. For the provided application, this task has been completed. For future reference, right-click the project node, select Properties, then select Run, and enter the Relative URL. For this example, you would enter /resources/helloWorld.

Right-click the project node, JAXRSHelloWorld, and select Deploy.
Right-click the project node, JAXRSHelloWorld, and select Run.
A browser opens and displays Hello World at the URL http://localhost:8080/HelloWorld/resources/helloWorld.

Example: Adding on to the Simple Hello World RESTful Web Service

This section discusses the simple RESTful web service that is included with the tutorial examples in the directory jaxrs/HelloWorld3. This example was created by following the steps similar to those described in Creating a RESTful Web Service Using NetBeans IDE.

Tip - A description of how to create this example is available online at http://www.netbeans.org/kb/docs/websvc/wadl-zembly. This online version of the example also explains how to deploy the RESTful web service to your domain and add the domain to Zembly.

HelloWorld3 Example: Discussion

This example takes the simple Hello World application discussed in the previous section and adds to it. In this example, there are methods for getting a user's name, and then the name is appended to the Hello World greeting. An annotation that wasn't used in the previous example, @QueryParam, is used in this example.

In this example, there is a simple RESTful web service that returns HTML messages. To accomplish this task, you would first create a JAX-B class that represents the HTML message in Java (RESTGreeting.java), then create a RESTful web service that returns an HTML message (HelloGreetingService.java.)

The JAX-B class that represents the HTML message gets the message and the name. This file, RESTGreeting.java, is basic Java code that creates a new instance of RESTGreeting and the getter and setter methods for its parameters.

The RESTful web service that returns an HTML message is in the file HelloGreetingService.java. You may notice that method that is annotated with JAX-RS annotations is similar to the one described in the previous example, however, this example adds an @QueryParam annotation to extract query parameters from the Query component of the request URL. The following code example shows the JAX-RS-annotated method:

@GET
    @Produces("text/html")
    public RESTGreeting getHtml(@QueryParam("name")String name) {
        return new RESTGreeting(getGreeting(), name);
    }     
    private String getGreeting(){
        return "Hello ";
    }

Testing the HelloWorld3 Example

Open the project javaeetutorial/jaxrs/HelloWorld3 in NetBeans IDE.
Right-click the project node, HelloWorld3, and select Test RESTful Web Services.
You may need to enter the user name (admin) and password (adminadmin).
Click the helloGreeting service in the left pane.
Enter a name in the name text field.
The Get(text/html) method is selected by default. Click Test.
The response Hello name, displays in the lower pane (Raw View)

Deploying and Running the HelloWorld3 Example

Before You Begin

Right-click the project node, HelloWorld3, and select Deploy.
Right-click the project node, HelloWorld3, and select Run.
The Run property does not specify a particular name, so none is shown in the browser window when it displays. The browser window simply shows the message Hello.
Append a name to the URL in the web browser, so that the URL looks like this: http://localhost:8080/HelloWorld3/helloGreeting?name=your_name.
The message Hello and the name your_name display in the browser.

JAX-RS in the First Cup Example

JAX-RS is used in the Your First Cup of Java example, which you will find at Your First Cup: An Introduction to the Java EE Platform

Real World Examples

A few real-world web applications that use RESTful web services include most blog sites. These are considered RESTful in that most blog sites involve downloading XML files in RSS or Atom format which contain lists of links to other resources. Other web sites and web applications that use REST-like developer interfaces to data include Twitter and Amazon S3 (Simple Storage Service). With Amazon S3, buckets and objects can be created, listed, and retrieved using either a REST-style HTTP interface or a SOAP interface. The examples that ship with Jersey include a storage service example with a RESTful interface. The tutorial at http://www.netbeans.org/kb/docs/websvc/twitter-swing uses the NetBeans IDE to create a simple, graphical, REST-based client that displays Twitter public timeline messages and lets you view and update your Twitter status.