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 6.1 supports
this architectural style.
Tomcat web server 6.0 and/or
GlassFish application server v2 Important: If you use Tomcat with this Tutorial, see the NetBeans Wiki on Tomcat with REST
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.
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:
Rapid creation of RESTful web services from JPA entity
classes and patterns.
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 RESTful component palette.
Generation of JavaScript client stubs from RESTful web
services for building RESTful client applications.
Test client generation for testing RESTful web services.
Logical view for easy navigation of RESTful web service implementation
classes in your project.
In
this
tutorial, you will be shown how the IDE supports you in generating,
implementing, and testing
RESTful web services.
Generating Entity Classes from a Database
The goal of this exercise is to create a project and generate entity classes from a database.
Choose File > New Project. Under Categories, select Web.
Under Projects, select Web Application and click Next.
Under Project Name, enter CustomerDB. Click Next.
Under Server, select GlassFish. Click through the remaining options and click Finish.
Open the Services tab. Under Databases, right-click the Java DB and start it.
Right-click the CustomerDB node and
choose New > Entity Classes from Database. Alternatively, you can select it from the Persistence category in the New File wizard (Ctrl-N).
In the Database Tables panel, select the jdbc/sample data source from the Data Source drop-down field.
Note: On Tomcat, this data source may not exist. In this case, choose New Data Source from the Data Source drop-down field. The Create Data Source dialog opens. Type jdbc/sample in the JNDI Name field. From the Database Connection drop-down field, select jdbc:derby://hostname:1527/sample [app on APP]. Click OK. The dialog closes and you return to the Database Tables panel. See also the RESTful Service on Tomcat tutorial for NetBeans IDE 6.0.
Under Available Tables, select CUSTOMER and then click Add. The DISCOUNT_CODE
table, which has a relationship with the CUSTOMER table, is automatically
added to the Selected Tables list too. You should now
see the following:
Click Next.
Under Package, type customerdb. You now see the following.
Click Create Persistence Unit. The following dialog appears.
Click Create and then click Finish.
Look in the Projects window. You now see
the following.
Generating RESTful Web Services from Entity Classes
The goal of this exercise is to generate
RESTful web services from the entity classes that
we generated in the previous section.
Right-click the package that contains the entity classes
and choose New > RESTful Web Services from Entity Classes.
In the New RESTful Web Services from Entity Classes wizard, click
Add All. After the entity classes appear in the Selected Entity Classes field, click Next. The Generated Classes panel opens.
In the Resource Package field, type customerdb.service, and in the Converter Package field, type customerdb.converter. Accept all other default settings, as shown below:
Here you can see everything that the IDE
will generate for you.
The IDE uses the container-item pattern to
generate the resource classes. For example,
for the Customer entity class, the IDE generates
a container resource called CustomersResource
and an item resource called CustomerResource. Also,
for each resource class, the IDE generates a
converter class used for generating the resource
representation from the corresponding entity
instance, such as CustomersConverter and
CustomerConverter. Furthermore, there is an
additional converter class called reference
converter, such as CustomerRefConverter,
for representing relationships.
Click Finish.
Look in the Projects window. You now see the following:
The RESTful Web Services node in the Projects window
displays all the RESTful web services in your project.
The value between the square brackets, such as [/customers/],
is the value for the URI template. You can also navigate to the
source file by doubling clicking on this node. This view also displays
all the HTTP methods and Sub-resource locator methods. Again, you
can navigate to the methods by double clicking on the nodes.
Now that your entity classes and RESTful web services have been
generated, test your application. The IDE provides a useful
utility for testing RESTful web services. You will make use of it
in the next section.
Testing the RESTful Web Services
The goal of this exercise is to try out your application.
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.
First select a root resource, such as customers.
Click on the Methods drop-down list to select either
GET(application/xml) or GET(application/json).
Click Test. The result is displayed in the Test Output section.
There are 4 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 Headers Tab displays the HTTP header information. There is also
a tab called HTTP Monitor, which displays the actual HTTP requests
and responses sent and received.
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.
Open the CustomerResource class
in the editor.
Add the following methods to CustomerResource:
@GET
@ProduceMime("text/html")
public String getGoogleMap() {
// Drag and drop the getGoogleMap operation here
return "";
}
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.
In the IDE, open the Services tab and expand the Web Services node. Under Web Services, expand Google. Under Google, expand Map Service.
Drag the getGoogleMap item and drop it into the body of the getGoogleMap method you created in Step 2, just before the return = null; 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
@ProduceMime("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.
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
@ProduceMime("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 "";
}
Open googlemapservice.properties. Paste in the API key you got from Google in Step 3.
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.
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.
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.
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 for each entity in the database and set the address equal to a concatenation of address variables for each Customer. If you are using a version of the IDE earlier than 6.5, also add a line at the end of the try block to close the instance of Customer. The method now looks like the following (changes in bold):
@GET
@ProduceMime("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();
}
//The close() method is only necessary with versions of NetBeans IDE earlier than 6.5
finally {
PersistenceService.getInstance().close();
}
return "";
}
Test the RESTful web services again. Again, 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 customer1, the following map displays:
Note: If GoogleMaps cannot find an address, it shows a zoomed in view of the ocean.
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.
