Example Applications for JAX-RS

This section provides an introduction to creating, deploying, and running your own JAX-RS applications. This section demonstrates the steps that are needed to create, build, deploy, and test a very simple web application that uses JAX-RS annotations.

A RESTful Web Service

This section explains how to use NetBeans IDE to create a RESTful web service. NetBeans IDE generates a skeleton for the application, and you simply need to implement the appropriate methods. If you do not use an IDE, try using one of the example applications that ship with Jersey as a template to modify.

You can find a version of this application at tut-install/examples/jaxrs/HelloWorldApplication/.

To Create a RESTful Web Service Using NetBeans IDE

In NetBeans IDE, create a simple web application. This example creates a very simple “Hello, World” web application.
1. From the File menu, choose New Project.
2. From Categories, select Java Web. From Projects, select Web Application. Click Next.
  Note - For this step, you could also create a RESTful web service in a Maven web project by selecting Maven as the category and Maven Web Project as the project. The remaining steps would be the same.
3. Type a project name, HelloWorldApplication, and click Next.
4. Make sure that the Server is GlassFish Server (or similar wording).
5. Click Finish.
The project is created. The file index.jsp appears in the Source pane.
Right-click the project and select New; then select RESTful Web Services from Patterns.
1. Select Simple Root Resource and click Next.
2. Type a Resource Package name, such as helloWorld.
3. Type helloworld in the Path field. Type HelloWorld in the Class Name field. For MIME Type, select text/html.
4. Click Finish.
  The REST Resources Configuration page appears.
5. Click OK.
  A new resource, HelloWorld.java, is added to the project and appears in the Source pane. This file provides a template for creating a RESTful web service.
In HelloWorld.java, find the getHtml() method. Replace the //TODO comment and the exception with the following text, so that the finished product resembles the following method.
Note - Because the MIME type produced is HTML, you can use HTML tags in your return statement.
```
/**
 * Retrieves representation of an instance of helloWorld.HelloWorld
 * @return an instance of java.lang.String
 */
@GET
@Produces("text/html")
public String getHtml() {
    return "<html lang=\"en\"><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 deploys the application and brings up a test client in the browser.
When the test client appears, select the helloworld resource in the left pane, and click the Test button in the right pane.
The words Hello, World!! appear in the Response window below.
Set the Run Properties:
1. Right-click the project node and select Properties.
2. In the dialog, select the Run category.
3. 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 (http://localhost:8080/HelloWorldApp) is the Relative URL that needs to be entered here.

If you don’t set this property, the file index.jsp will appear by default 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, or update index.jsp to provide a link to the RESTful web service.
Right-click the project and select Deploy.
Right-click the project and select Run.
A browser window opens and displays the return value of Hello, World!!

The `rsvp` Example Application

The rsvp example application, located in the tut-install/examples/jaxrs/rsvp/ directory, allows invitees to an event to indicate whether they will attend. The events, people invited to the event, and the responses to the invite are stored in a Java DB database using the Java Persistence API. The JAX-RS resources in rsvp are exposed in a stateless session enterprise bean.

Components of the `rsvp` Example Application

The three enterprise beans in the rsvp example application are rsvp.ejb.ConfigBean, rsvp.ejb.StatusBean, and rsvp.ejb.ResponseBean.

ConfigBean is a singleton session bean that initializes the data in the database.

StatusBean exposes a JAX-RS resource for displaying the current status of all invitees to an event. The URI path template is declared as follows:

@Path("/status/{eventId}/")

The URI path variable eventId is a @PathParam variable in the getResponse method, which responds to HTTP GET requests and has been annotated with @GET. The eventId variable is used to look up all the current responses in the database for that particular event.

ResponseBean exposes a JAX-RS resource for setting an invitee’s response to a particular event. The URI path template for ResponseBean is declared as follows:

@Path("/{eventId}/{inviteId}")

Two URI path variables are declared in the path template: eventId and inviteId. As in StatusBean, eventId is the unique ID for a particular event. Each invitee to that event has a unique ID for the invitation, and that is the inviteId. Both of these path variables are used in two JAX-RS methods in ResponseBean: getResponse and putResponse. The getResponse method responds to HTTP GET requests and displays the invitee’s current response and a form to change the response.

An invitee who wants to change his or her response selects the new response and submits the form data, which is processed as an HTTP PUT request by the putResponse method. One of the parameters to the putResponse method, the userResponse string, is annotated with @FormParam("attendeeResponse"). The HTML form created by getResponse stores the changed response in the select list with an ID of attendeeResponse. The annotation @FormParam("attendeeResponse") indicates that the value of the select response is extracted from the HTTP PUT request and stored as the userResponse string. The putResponse method uses userResponse, eventId, and inviteId to update the invitee’s response in the database.

The events, people, and responses in rsvp are encapsulated in Java Persistence API entities. The rsvp.entity.Event, rsvp.entity.Person, and rsvp.entity.Response entities respectively represent events, invitees, and responses to an event.

The rsvp.util.ResponseEnum class declares an enumerated type that represents all the possible response statuses an invitee may have.

Running the `rsvp` Example Application

Both NetBeans IDE and Ant can be used to deploy and run the rsvp example application.

To Run the `rsvp` Example Application in NetBeans IDE

From the File menu, choose Open Project.
In the Open Project dialog, navigate to:
```
tut-install/examples/jaxrs/
```
Select the rsvp folder.
Select the Open as Main Project check box.
Click Open Project.
Right-click the rsvp project in the left pane and select Run.
The project will be compiled, assembled, and deployed to GlassFish Server. A web browser window will open to http://localhost:8080/rsvp.
In the web browser window, click the Event Status link for the Duke’s Birthday event.
You’ll see the current invitees and their responses.
Click on the name of one of the invitees, select a response, and click Submit response; then click Back to event page.
The invitee’s new status should now be displayed in the table of invitees and their response statuses.

To Run the `rsvp` Example Application Using Ant

Before You Begin

You must have started the Java DB database before running rsvp.

In a terminal window, go to:
```
tut-install/examples/jaxrs/rsvp/
```
Type the following command:
```
ant all
```
This command builds, assembles, and deploys rsvp to GlassFish Server.
Open a web browser window to http://localhost:8080/rsvp.
In the web browser window, click the Event Status link for the Duke’s Birthday event.
You’ll see the current invitees and their responses.
Click on the name of one of the invitees, select a response, and click Submit response, then click Back to event page.
The invitee’s new status should now be displayed in the table of invitees and their response statuses.

Real-World Examples

Most blog sites use RESTful web services. These sites involve downloading XML files, in RSS or Atom format, that 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://netbeans.org/kb/docs/websvc/twitter-swing.html uses 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.