Coding the DukesAgeResource Example Application

Coding the `DukesAgeResource` Example Application

This section describes how to code the DukesAgeResource example application, a JAX-RS RESTful web service endpoint.

Getting Started

Before you start coding the example, you need to perform some configuration tasks:

Register the server with your NetBeans IDE as described in Configuring Your Environment.
Create a directory for the example you will build.

Create a Directory for the Example

Create another directory at the same level as the tut-install/example directory, where tut-install is the location of the firstcup tutorial installation, and call it myexample.
You'll create the applications described in this tutorial in this directory.

Creating the Web Service

The DukesAgeResource endpoint is a simple RESTful web service. REST stands for representational state transfer, and software architectures that conform to the principles of REST are referred to as RESTful. RESTful web services are web-based applications that use the HTTP protocol to access, modify, or delete information contained within a resource. A RESTful web service resource is a source of specific information identifiable by a uniform resource identifier (URI), for example http://example.com/someResource, and may be manipulated by calling the HTTP protocol's methods, for example GET or POST.

RESTful web services are often contrasted to SOAP web services (for example, web services created with the JAX-WS API that is part of Java EE 6). Compared to SOAP web services, RESTful web services are simpler, as they use HTTP directly rather than as a transport mechanism for an underlying XML document format, and typically offer better performance.

Web services are designed to be independent of their clients. Typically RESTful web services are publicly available to a wide variety of clients, and the clients are located throughout the Internet. This is called “loose coupling,” as the clients and servers are connected only by the standard HTTP-based requests and responses, and do not need to know each other's implementation details. For this reason, DukesAge will be developed in its own application module, and deployed separately from the DukesBirthdayBean enterprise bean and firstcup web client. DukesAge could be deployed on a completely different machine without affecting the functionality of the firstcup web client.

JAX-RS Resources

DukesAgeResource is a JAX-RS resource class that responds to HTTP GET requests and returns a String representing the age of Duke at the time of the request.

To create DukesAgeResource, use the wizard provided by the JAX-RS plug-in for NetBeans IDE to generate the resource class. This class is annotated with the javax.ws.rs.Path annotation, which specifies the URL suffix to which the resource will respond. DukesAgeResource has a single method, getText, annotated with the javax.ws.rs.GET and javax.ws.rs.Produces annotations. @GET marks the method as a responder to HTTP GET requests, and @Produces specifies the MIME-type of the response sent back from getText to clients. In this case, the MIME-type is text/plain.

Creating the Endpoint

In NetBeans IDE, create a web project with a source file called DukesAgeResource.java in the firstcup.webservice package using the RESTful Web Service wizard.

Create the Project in NetBeans

From the File menu, choose New Project.
In the Categories pane, select Java Web.
In the Projects pane, select Web Application.
Click Next.
In the Project Name field, type dukes-age.
In the Project Location field, browse to tut-install/myexample, where tut-install is the location of the firstcup tutorial installation.
Click Next.
Select your GlassFish Server instance from the Server menu.
Select Java EE 6 Web from the Java EE Version menu.
In the Context Path field, type /DukesAgeService.
Click Finish.
You should now see the module you created in the Projects tab.
From the Projects tab, right-click the index.jsp file and select Delete. Click Yes in the dialog.

Create the `DukesAgeResource` Class

Select the dukes-age project in the Projects tab.
From the File menu, choose New File.
In the Categories pane, select Web Services.
In the File Types pane, select RESTful Web Services From Patterns.
Click Next.
Under Select Pattern, select Simple Root Resource and click Next.
In the Resource Package field, type firstcup.webservice.
In the Path field, type dukesAge.
In the Class Name field, type DukesAgeResource.
From the MIME Type menu, select text/plain.
Click Finish.
In the REST Resources Configuration dialog, uncheck Add Jersey Library and click OK.
You should now see the DukesAgeResource.java file inside the firstcup.webservice package in the Projects tab. The DukesAgeResource.java file should also be open in the editor pane.

Configure the `dukes-age` Web Application

Set the default URL that is brought up in a web browser when you run dukes-age.

Right-click the dukes-age project in the Projects tab and select Properties.
In the Categories pane, click Run.
Set Relative URL to /resources/dukesAge.
Click OK.

Remove the `putText` Method

The DukesAgeResource JAX-RS resource doesn't respond to HTTP PUT requests. Delete the generated putText method in DukesAgeResource.

Highlight the following generated Javadoc and method definition and delete it.

/**
 * PUT method for updating or creating an instance of DukesAgeResource
 * @param content representation for the resource
 * @return an HTTP response with content of the updated or created resource.
 */
@PUT
@Consumes("text/plain")
public void putText(String content) {
}

Implement the `getText` Method

Add code to DukesAgeResource.getText that calculates Duke's age at the time of the request. To do this, use the java.util.Calendar and java.util.GregorianCalendar classes to create an object representing the date May 23, 1995, Duke's birthday. Then create another Calendar object representing today's date, and subtract today's year from Duke's birth year. If today's date falls before May 23, subtract a year from this result. Then return the result as a String representation.

Highlight the current code in getText and replace it with the following code:

// Create a new Calendar for Duke's birthday
Calendar dukesBirthday = new GregorianCalendar(1995, Calendar.MAY, 23);
// Create a new Calendar for today
Calendar now = GregorianCalendar.getInstance();

// Subtract today's year from Duke's birth year, 1995
int dukesAge = now.get(Calendar.YEAR) - dukesBirthday.get(Calendar.YEAR);
dukesBirthday.add(Calendar.YEAR, dukesAge);

// If today's date is before May 23, subtract a year from Duke's age
if (now.before(dukesBirthday)) {
    dukesAge--;
}
// Return a String representation of Duke's age
return "" + dukesAge;

Right-click in the editor window and select Format.
Right-click in the Editor and select Fix Imports.
From the File menu, choose Save to save the file.

Building and Deploying the Web Service

Build the JAX-RS web application and deploy it to your GlassFish Server instance.

Build and Deploy the Web Service Endpoint

Compile, package, and deploy dukes-age.war to GlassFish Server. This task gives instructions on deploying dukes-age.war in NetBeans IDE.

Right-click dukes-age in the Projects tab and select Run.
After dukes-age.war deploys successfully to GlassFish Server a web browser will load the URL of the DukesAgeResource path, and you'll see the returned String representing Duke's age.

Example 3-1 Output of DukesAgeResource

Here's an example of the output of DukesAgeResource displayed in a web browser.

At this point, you've successfully created, deployed, and run your first Java EE application. Now you will create a web application that uses this web service data.