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.

The following topics are addressed here:

Creating a Simple RESTful Web Service
The rsvp Example Application
Real-World Examples

Creating a Simple RESTful Web Service

This section explains how to use NetBeans IDE to create a RESTful web service using a Maven archetype. The archetype generates a skeleton for the application, and you simply need to implement the appropriate method.

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

The following topics are addressed here:

To Create a RESTful Web Service Using NetBeans IDE

To Create a RESTful Web Service Using NetBeans IDE

Ensure you have installed the tutorial archetypes as described in Installing the Tutorial Archetypes.
In NetBeans IDE, create a simple web application using the jaxrs-service-archetype Maven archetype. This archetype creates a very simple "Hello, World" web application.
From the File menu, choose New Project.
From Categories, select Maven. From Projects, select Project From Archetype. Click Next.
Under Search enter jaxrs-service, select the jaxrs-service-archetype, and click Next.
Under Project Name enter HelloWorldApplication, set the Project Location, and set the Package name to javaeetutorial.hello, and click Finish.

The project is created.
In HelloWorld.java, find the getHtml() method. Replace the //TODO comment with the following text, so that the finished product resembles the following method:
```
@GET
@Produces("text/html")
public String getHtml() {
    return "<html lang=\"en\"><body><h1>Hello, World!!</body></h1></html>";
}
```
Note:

Because the MIME type produced is HTML, you can use HTML tags in your return statement.
Right-click the HelloWorldApplication project in the Projects pane and select Run.

This will build and deploy the application to GlassFish Server.
In a browser, open the following URL:
```
http://localhost:8080/HelloWorldApplication/HelloWorldApplication
```
A browser window opens and displays the return value of Hello, World!!

For other sample applications that demonstrate deploying and running JAX-RS applications using NetBeans IDE, see The rsvp Example Application and Your First Cup: An Introduction to the Java EE Platform at http://docs.oracle.com/javaee/7/firstcup/doc/. You may also look at the tutorials on the NetBeans IDE tutorial site, such as the one titled "Getting Started with RESTful Web Services" at https://netbeans.org/kb/docs/websvc/rest.html. This tutorial includes a section on creating a CRUD application from a database. Create, read, update, and delete (CRUD) are the four basic functions of persistent storage and relational databases.

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 Apache Derby using the Java Persistence API. The JAX-RS resources in rsvp are exposed in a stateless session enterprise bean.

The following topics are addressed here:

Components of the rsvp Example Application
Running the rsvp Example Application

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 first on the class and then on the getEvent method:

@Stateless
@Named
@Path("/status")
public class StatusBean {
    ...
    @GET
    @Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
    @Path("{eventId}/")
    public Event getEvent(@PathParam("eventId") Long eventId) {
         ...

The combination of the two @Path annotations results in the following URI path template:

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

The URI path variable eventId is a @PathParam variable in the getEvent 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.

The javaeetutorial.rsvp.rest.RsvpApplication class defines the root application path for the resources by applying the javax.ws.rs.ApplicationPath annotation at the class level.

@ApplicationPath("/webapi")
public class RsvpApplication extends Application {
}

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 POST request by the putResponse method. The new response is extracted from the HTTP POST 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.

The web application also includes two CDI managed beans, StatusManager and EventManager, which use the JAX-RS Client API to call the resources exposed in StatusBean and ResponseBean. For information on how the Client API is used in rsvp, see "The Client API in the rsvp Example Application".

Running the rsvp Example Application

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

The following topics are addressed here:

To Run the rsvp Example Application Using NetBeans IDE
To Run the rsvp Example Application Using Maven

To Run the rsvp Example Application Using NetBeans IDE

If the database server is not already running, start it by following the instructions in Starting and Stopping Apache Derby.
Make sure that GlassFish Server has been started (see Starting and Stopping GlassFish Server).
From the File menu, choose Open Project.
In the Open Project dialog box, navigate to:
```
tut-install/examples/jaxrs
```
Select the rsvp folder.
Click Open Project.
In the Projects tab, right-click the rsvp project and select Run.

The project will be compiled, assembled, and deployed to GlassFish Server. A web browser window will open to the following URL:
```
http://localhost:8080/rsvp/index.xhtml
```
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 the current response of one of the invitees in the Status column of the table, select a new response, and click Update your status.

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 Maven

If the database server is not already running, start it by following the instructions in Starting and Stopping Apache Derby.
Make sure that GlassFish Server has been started (see Starting and Stopping GlassFish Server).
In a terminal window, go to:
```
tut-install/examples/jaxrs/rsvp/
```
Enter the following command:
```
mvn install
```
This command builds, assembles, and deploys rsvp to GlassFish Server.
Open a web browser window to the following URL:
```
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 the current response of one of the invitees in the Status column of the table, select a new response, and click Update your status.

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 websites 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.