Monday, July 7, 2008

Project Jersey and Java-based REST

Project Jersey is the reference implementation of JSR 311 ("The Java API for RESTful Web Services"). The main page states that Jersey is currently available as an "early access" version and cannot transition to 1.0 until the specification it implements (JAX-RS/JSR-311) receives final approval.

There are several highly useful resources provided to learn how to apply Jersey in Java-based web services, especially in the Project Jersey Community Wiki. The REST Web Services Developers Guide is available in both HTML and PDF formats. This 34-page document introduces basic concepts of REST (Representational State Transfer) and covers how to use Jersey to apply REST. The Jersey Getting Started page shows how to create a simple Hello World style REST-based web service. One thing I found particularly interesting about this is that it uses the Lightweight HTTP Server distributed with Sun's implementation of Java SE 6.

Another useful resource on using Jersey with REST is the Enterprise Java Technology Tech Tip Implementing RESTful Web Services in Java.

If you use the NetBeans IDE, two particularly useful articles on using NetBeans 6.0 with Jersey are Getting Started with RESTful Web Services on GlassFish and Getting Started with RESTful Web Services on Tomcat. In the remainder of this article, I will demonstrate how to use NetBeans 6.1 with Jersey and the Oracle database HR schema to generate a RESTful web service.

SIDE NOTE: I started working on this example before discovering the two NetBeans/Jersey articles related to Tomcat and GlassFish described above. However, even after discovering these articles, I decided that it could be worthwhile to publish this blog entry because I am going to use NetBeans 6.1 (the articles use NetBeans 6.0), I am going to use an external Oracle database, and I am going to add different commentary than that available in the two articles hosted on the NetBeans site. However, because the basic Jersey support seems to be largely the same between NetBeans 6.0 and NetBeans 6.1, I am going to try to not repeat much of what is already available in those articles unless the repetition is necessary to make this blog entry flow more smoothly.

The Jersey distribution can be downloaded, but this step is unnecessary with NetBeans 6.1. The snapshot below (click on snapshots to see larger versions) demonstrates the "Jersey (JSR 311) Libraries" library (and its content JARs) that is available with NetBeans and can be included in a project using Jersey.



NetBeans 6.1 includes a plugin for Jersey. This is shown in the next screen snapshot:



With the Jersey library added to my NetBeans 6.1 project and the plugin installation verified, it is time to start developing a simple Jersey-based web service. For this example, I will be using the Oracle HR database schema. When one runs a SELECT table_name FROM user_tables SQL command in SQL*Plus on this schema, the following tables are shown


TABLE_NAME
------------------------
LOCATIONS
COUNTRIES
DEPARTMENTS
REGIONS
JOB_HISTORY
JOBS
EMPLOYEES


With existing database tables like those shown above, it is trivial to generate Java Persistence API (JPA) entity classes from the database tables in NetBeans 6.1.

The next three screen snapshots indicate how simple it is to generate "Entity Classes from Database," to select appropriate tables from which JPA entity classes should be generated, and to specify a package structure for the generated JPA entity classes.







You may have noticed some tables and generated JPA entities in the above screen snapshots that are not normally in the HR schema. These tables are in my schema because I created them and am using them for something else, but they are not significant for this example.

The next screen snapshot shows the generated JPA entity classes as they appear in the NetBeans 6.1 IDE.



The icons with exclamation points in the middle of red circles indicate classes that do not compile with the current NetBeans compiler classpath settings. To address this, I needed to add the TopLink Essentials (JPA 1.0 reference implementation) library to the project. This library is delivered with NetBeans 6.1, so this is a relatively easy task. The next screen snapshot indicates how the addition of the TopLink Essentials library allows the generated entity classes to build properly.



Thus far, NetBeans 6.1 has done most of the heavy lifting. We have not done anything REST or even Web Service specific, but we do have JPA entity classes generated and corresponding to the database tables we started with. The next step is to let NetBeans 6.1 generate the appropriate Jersey-based artifacts to support RESTful web services access of these newly generated entity classes. The next four screen snapshots show how to generate "RESTful Web Services from Entity Classes," how to select the entity classes from which REST/Jersey artifacts should be generated, which Jersey/REST artifacts are to be generated, and the generation of Jersey-based REST web services in action.









When the steps shown in the screen snapshots immediately above are executed, the Jersey-based web services artifacts shown in the next four screen snapshots are generated or set up.

Converters - Convert Between JPA Entities and Jersey Services


Services - Workhorse Classes for Jersey-based REST Web Services Support


Jersey Libraries Automatically Associated with NetBeans Project


NetBeans RESTful Web Services


NetBeans 6.1 has done most of the work to go from database tables to JPA entities and from JPA entities to RESTful Web Services. NetBeans does even more for us by providing an easy testing and monitoring mechanism. By right-clicking on the "RESTful Web Services" icon shown in the last screen snapshot (in NetBeans' Project window) and selecting , a web browser comes up with a basic "Test RESTful Web Services" web page that can be used to test and monitor the running REST-based web services. The next screen snapshot shows a snippet of this using a REST query for employee with employee ID of 170.



There is much to look at in the web page for testing, but my focus here is on the simplicity of the REST-style URL (see Resource toward top of web page), the tabs at the bottom that allow you to see the "raw" XML in addition to the useful Tabular View and HTTP Monitor tabs, and the URL for the WADL (see top left corner).

In this blog, I used NetBeans to create the RESTful web services from JPA entity classes that were generated by NetBeans from an Oracle database schema. I also performed simple testing of my newly generated RESTful web services using NetBeans' automatic support. I intend to follow up with additional blog entries in which I use non-NetBeans clients to contact these RESTful web services.

No comments: