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

1. Select File -> New Project.

2. Select Java Web in the Categories pane.

3. Select Web Application in the Projects pane.

4. Click Next.

5. Set Project Name to dukes-age.

6. Set the Project Location to tut-install/myexample.

7. Click Next.

8. Select your GlassFish Server instance from the Server menu.

9. Select Java EE 6 Web from the Java EE Version menu.

10. Set the Context Path to /DukesAgeService

11. Click Finish.

    You should now see the module you created in the Projects pane.

12. From the Projects pane, right-click on the index.jsp file and select Delete. Click Yes in the dialog.

Create the DukesAgeResource Class

1. Make sure dukes-age is selected in the Project menu.

2. Select File -> New File.

3. Select Web Services in the Categories pane.

4. Select RESTful Web Services From Patterns in the File Types pane.

5. Click Next.

6. Under Select Pattern select Singleton and click Next.

7. Set Resource Package to firstcup.webservice.

8. Under Path enter dukesAge.

9. Under Class Name enter DukesAgeResource.

10. Under MIME Type select text/plain.

11. Click Finish.

    You should now see the DukesAgeResource.java file inside the firstcup.webservice package in the Projects pane. The DukesAgeResource.java file should also be open in the editor pane.

Configure the dukes-age Web Application

By default, NetBeans IDE bundles the JAX-RS 1.0 JARs with web applications that use JAX-RS 1.0. GlassFish Server already has the JAX-RS 1.0 JARs in the server classpath, so there is no need to separately include the JARs.

The default URL that is brought up in a web browser when you run dukes-age can also be configured in NetBeans IDE.

1. Right-click on dukes-age in the Projects tab and select Properties.

2. Click Libraries.

3. Uncheck the boxes under Compile-time Libraries for restlib-gfv3ee6.

4. Click Run.

5. Set Relative URL to /resources/dukesAge.

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

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

1. 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 = GregorialCalendar.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 new String("" + dukesAge);

2. Right-click in the editor window and select Format.

3. Right-click in the Editor and select Fix Imports.

4. Select File -> Save from the menu to save the file.

Building and Deploying the Web Service

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

Building and Deploying 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.

1. Select dukes-age in the Projects tab.

2. Right-click dukes-age 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.

14