Getting Started with RESTful Web Services

REpresentational State Transfer (REST) is an architectural style for distributed hypermedia systems, such as the World Wide Web. Central to the RESTful architecture is the concept of resources identified by universal resource identifiers (URIs). These resources can be manipulated using a standard interface, such as HTTP, and information is exchanged using representations of these resources. In this tutorial, you first learn a bit about REST and then you are shown how NetBeans IDE supports this architectural style.

Contents

• Introduction
• RESTful Web Services, Persistence, and Entity Classes
• Creating RESTful Web Services from a Database
  • Creating the Project
  • Generating Entity Classes and RESTful Services
• Testing the RESTful Web Services
• Adding a Google Map Feature

To follow this tutorial, you need the following software and resources.

Software or Resource	Version Required
NetBeans IDE	Java EE download bundle
Java Development Kit (JDK)	version 6
Java EE-compliant web or application server	EE5 project: Tomcat web server 6.x-7.x, Oracle WebLogic Server 11g, or GlassFish Server Open Source Edition. Important: If you use Tomcat with this Tutorial, see the NetBeans Wiki on Tomcat with REST. EE6 project: GlassFish Server Open Source Edition 3.x
The jdbc/sample database on Java DB (Derby) database server or MySQL database server	On Java DB (Derby), The jdbc/sample database is generated by NetBeans IDE when you install the IDE with the GlassFish application server. On MySQL, the IDE populates the sample database after you create it on the MySQL server from within the IDE.

Both Tomcat and the GlassFish server can be installed with the Web and Java EE distribution of NetBeans IDE. Alternatively, you can visit the the GlassFish server downloads page or the Apache Tomcat downloads page.

Introduction

RESTful web services are services built using the RESTful architectural style. Building web services using the RESTful approach is emerging as a popular alternative to using SOAP-based technologies for deploying services on the internet, due to its lightweight nature and the ability to transmit data directly over HTTP.

The IDE supports rapid development of RESTful web services using JSR 311 - Java API for RESTful Web Services (JAX-RS) and Jersey, the reference implementation for JAX-RS.

For detailed information, refer to the following:

• JSR 311: JAX-RS: The Java API for RESTful Web Services
• Jersey, the open source JAX-RS (JSR 311) Reference Implementation for building RESTful Web services

In addition to building RESTful web services, the IDE also supports testing, building client applications that access RESTful web services, and generating code for invoking web services (both RESTful and SOAP-based.)

Here is the list of RESTful features provided by the IDE:

1. Rapid creation of RESTful web services from JPA entity classes and patterns.
2. Rapid code generation for invoking web services such as Google Map, Yahoo News Search, and StrikeIron web services by drag-and-dropping components from the Web Services manager in the Services window.
3. Generation of RESTful Java Clients for services registered in the Web Services manager.
4. Test client generation for testing RESTful web services.
5. Logical view for easy navigation of RESTful web service implementation classes in your project.
6. Fully integrated Spring framework, providing Spring transaction handling.

In this tutorial, you will be shown how the IDE supports you in generating, implementing, and testing RESTful web services.

RESTful Web Services, Persistence, and Entity Classes

RESTful web services in Java rely on the Java Persistence API to communicate with a database. Specifically, RESTful web services rely on entity classes and a persistence unit, as defined in the Persistence API. Entity classes are Java classes that map to objects in a relational database. According to The Java EE5 Tutorial, "An entity is a lightweight persistence domain object. Typically an entity represents a table in a relational database, and each entity instance corresponds to a row in that table." A persistence unit consists of the set of entity classes, the data source, the persistence provider, and the persistence unit's own name, as defined in a persistence.xml file.

You can use NetBeans IDE either to create entity classes and RESTful web services in the same process, or you can use the IDE to create RESTful web services from existing entity classes. In this tutorial, you use the RESTful Services from Database wizard to generate entity classes and RESTful web services in the same process. The wizard automatically generates the persistence unit.

Using a MySQL Database Server

If you use the MySQL database server instead of JavaDB (Derby), you need to register the database server with the IDE and add the sample database to the server.

To use a MySQL database server with this tutorial:

1. Register your MySQL server in the IDE, if the server is not registered. To register a MySQL server, go to the IDE's Services window, right-click the Databases node, and select Register MySQL server.
   

2. A dialog opens in which you type the configuration details of your MySQL server, including administrator user name and password. See "Configuring MySQL Server Properties" in Connecting to a MySQL Database.

   
3. Start the MySQL server and connect to it. See "Starting the MySQL Server" in Connecting to a MySQL Database.
4. Right-click the MySQL server node and select Create Database. The Create MySQL Database dialog opens.
   
5. Type sample as the new database name. Grant full access to your root user, or a user of your choice.
   
6. Click OK. A dialog opens informing you that sample is the name of a sample database, and asking you if you want to create the tables, objects, and data for this database.
   
7. Click Yes. The IDE creates and populates the database, and adds a connection to the database.
   

Creating RESTful Web Services from a Database

The goal of this exercise is to create a project and generate entity classes and RESTful web services from a database.

This section uses the JavaDB (Derby) database and the jdbc/sample data source. JavaDB is included with the SDK. The jdbc/sample data source is generated by NetBeans IDE automatically when you install the IDE together with GlassFish.

The IDE now generates the RESTful web services. When the IDE is finished, look in the Projects window. The generated entity classes are in the entities package. Services are in the service package. For an EE5 project, there are converter classes in the converter package and a web.xml deployment descriptor under Configuration Files.

Caution: The IDE might prompt you to Resolve Reference Problems for the project. In this case, right-click the CustomerDB project node and select Resolve Reference Problems. This issue can happen when the service is the first Jersey application to run on a WebLogic installation. In this case, the IDE solves the reference problem by copying the Jersey libraries to the server.

For EE6 RESTful web services from a database, NetBeans IDE uses JAXB annotations in the entity classes and EJB session facades for the service classes. This removes the need for converter classes and generates simpler code.

For more details about EE6 RESTful web services generated by NetBeans IDE 7.0 and later, see NetBeans to Generate Simpler RESTful Web Services.

Testing the RESTful Web Services

The goal of this exercise is to try out your application.

1. Right-click the project node and choose Test RESTful Web Services. The server starts and the application is deployed. When deployment is complete, the browser displays your application, with a link for each of the web services.

   If the output window shows an error message that one or more classes fails to exist and the project does not build, add the Jersey libraries to the compile-time libraries. Right-click the project node and select Properties. In the Properties tree menu, select Libraries. Click Add Library and browse for the Jersey libraries.

   

   On the left-hand side is the set of root resources. Here they are named customers and discountCodes.

   Warning: The RESTful web service tester is not supported by Chrome, Opera, or FireFox 4 and 5. Security features on those browsers block the tester's JavaScript from retrieving the WADL. The issue should be resolved in NetBeans IDE 7.0.1. See Issue 159653.

2. Click the customers node. The browser window shows you a list of parameters for testing the Customers service.
   

   You can set the following parameters:

   • Choose method to test: Choose the GET or POST method and the MIME type from a drop-down list.
   • Start: First entity to display. Note that the numbering begins with 0, not 1.
   • Max: Maximum number of entities to fetch. If set to 0, all entities are fetched.
   • Expand level: An advanced feature. Some services return an infinitely repeating tree hierarchy. This parameter specifies what depth of such hierarchies to display in the Raw View.
   • Query: An advanced feature. Searches the XML or JSON document according to JPA syntax.
3. Click on the Methods drop-down list to select GET(application/xml). Type "3" in the Max field. Leave default values in the other parameters and click Test. The result is displayed in the Test Output section.
   

   There are 5 tabs in the Test Output section.

   • The Tabular View is a flattened view that displays all the URIs in the resulting document, which you can navigate to by clicking on the links.
   • The Raw View displays the actual data returned. Depending on which mime type you selected (application/xml or application/json), the data displayed will be in either XML or JSON format, respectively.
   • The Sub Resource tab shows the URLs of the root resource and sub resources. When the RESTful web service is based on database entity classes, the root resource represents the database table, and the sub resources represent the columns.
   • The Headers tab displays the HTTP header information.
   • The HTTP Monitor tab displays the actual HTTP requests and responses sent and received.

   Note that you have 6 results listed although you specified a maximum of 3 entities to display. Open the Raw View tab to see the reason why. Each entity corresponds to a <customer> element, and you have only 3 customers in the test results. However, the Tablular view lists URIs, not entities, and each entity has two URIs, one as an attribute of the parent <customer> element and one as an attribute of the child <discountCode> element. So although there are only 3 customer entities, there are 6 URIs in total.

   
4. Exit the browser and return to the IDE.

Adding a Google Map Feature

The goal of this exercise is to add Google map functionality to our RESTful web services.

1. Open the CustomerResource class (EE 5) or CustomerFacade class (EE 6) in the editor.
2. Add the following method to the class:

   @GET
   @Produces("text/html")
   public String getGoogleMap() {
   // Drag and drop the getGoogleMap operation here
   
      return "";
   }

3. Sign up for a Google map key at http://www.google.com/apis/maps/signup.html. The Google map key request dialog has a field for your website's URL. Type http://localhost:8080 in that field.
4. In the IDE, open the Services tab and expand the Web Services node. Under Web Services, expand Google. Under Google, expand Map Service.
   
   
5. Drag the getGoogleMap item and drop it into the body of the getGoogleMap method you created in Step 2, just before the return = ""; line. The Customize getGoogleMap SAAS dialog opens. Accept the defaults and click OK.

   The IDE adds the following try block to the getGoogleMap method in the CustomerResource class.

   @GET
   @Produces("text/html")
   public String getGoogleMap() {
   // Drag and drop the getGoogleMap operation here
           
       try {
                
            String address = "16 Network Circle, Menlo Park";
            java.lang.Integer zoom = 15;
            String iframe = "false";
            RestResponse result = GoogleMapService.getGoogleMap(address, zoom, iframe);
            //TODO - Uncomment the print Statement below to print result.
            //System.out.println("The SaasService returned: "+result.getDataAsString());
       } catch (Exception ex) {
            ex.printStackTrace();
       }
   
       return "";
   
   }
                   

   The IDE also creates the packages org.netbeans.saas and org.netbeans.saas.google, which contain the following classes and resources:

   • RestConnection - A wrapper around HttpUrlConnection
   • RestResponse - A wrapper for the HTTP response
   • googlemapservice.properties - A properties file that stores the API key
   • GoogleMapService - A service wrapper containing the wrapper methods that uses RestConnection to make calls to the Google Map service.
   
6. In the try block of getGoogleMap(), replace the commented-out print statement with the line return result.getDataAsString();. The method now looks like this:

   @GET
   @Produces("text/html")
   public String getGoogleMap() {
   // Drag and drop the getGoogleMap operation here
           
       try {
                
            String address = "16 Network Circle, Menlo Park";
            java.lang.Integer zoom = 15;
            String iframe = "false";
            RestResponse result = GoogleMapService.getGoogleMap(address, zoom, iframe);
            return result.getDataAsString();
       } catch (Exception ex) {
            ex.printStackTrace();
       }
   
       return "";
   }

7. Open googlemapservice.properties. Paste in the API key you got from Google in Step 3.
8. Right-click the CustomerDB project node and select Test RESTful Web Services. The IDE undeploys and redeploys your project to the server and then opens a browser window with the test client.
9. Click customers in the left sidebar. Test criteria for customers open in the main pane. Leave the defaults and click Test. A table of customers opens.
10. From the table, click customer1. A test window for that customer opens in the main pane. From the drop-down menu, select the text/html MIME type. Click Test. The GoogleMap of 16 Network Circle, Menlo Park opens in the Raw View.
    

11. The Google map of the Menlo Park address appears for all customers in the database. To display the Google maps of the actual addresses of the customers, create an instance of Customer and set the address equal to a concatenation of address variables for that instance of Customer.

    For an EE5 service, use the getEntity() method to create an instance of Customer for each entity in the database (changes in bold):

    EE5 service:

    @GET
    @Produces("text/html")
    public String getGoogleMap() {
        try {
             Customer c = getEntity();
             String address = c.getAddressline1() + " " + c.getAddressline2() + " " +
                     c.getCity() + " " + c.getState() + " " + c.getZip();
             java.lang.Integer zoom = 15;
             String iframe = "false";
     
             RestResponse result = GoogleMapService.getGoogleMap(address, zoom, iframe);
             return result.getDataAsString();
         
         } catch (Exception ex) {
             ex.printStackTrace();
         } 
    
         
         return "";
     }

    For an EE6 service, create an instance of Customer by calling the generic find() method from the abstract facade. The generic find() method requires explicit argument type casting to Object and an explicid entity id. The following EE6 code displays the map location of customer id number 1 (changes in bold):

    EE6 service:

    @GET
    @Produces("text/html")
    public String getGoogleMap() {
        try {
             Customer c = getEntityManager().find(Customer.class, 1);
             String address = c.getAddressline1() + " " + c.getAddressline2() + " " +
                     c.getCity() + " " + c.getState() + " " + c.getZip();
             java.lang.Integer zoom = 15;
             String iframe = "false";
     
             RestResponse result = GoogleMapService.getGoogleMap(address, zoom, iframe);
             return result.getDataAsString();
         
         } catch (Exception ex) {
             ex.printStackTrace();
         } 
    
         
         return "";
     }

12. Test the RESTful web services again. For an EE5 service, select the text/html MIME type for one of the customers. A Google map of that customer's address in the database now displays in the Raw View. For an EE6 service, the customer id is specified as an argument for the find() method and the tester displays the raw view by default. For customer1, the following map displays:
    

    Note: If GoogleMaps cannot find an address, it shows a zoomed in view of the ocean.

See Also

For more information about using NetBeans IDE to develop Java EE applications, see the following resources:

• NetBeans to Generate Simpler RESTful Web Services
• Creating RESTful Service Clients in NetBeans Modules
• Web Services Learning Trail
• YouTube: RESTful Web Services, Building and Deploying (Part 1)
• YouTube: NetBeans RESTful Testing and Invoking RESTful Resources (Part 2)

To send comments and suggestions, get support, and keep informed on the latest developments on the NetBeans IDE Java EE development features, join the mailing list.