JAX-RS Entry 1: Basic

Introduction

JAX-RS is a set of JAVA Implementation of the rest Service Specification, provides some annotation to a resource class, a pojojava class, encapsulated as web resources. Annotations include:

• @ Path: indicates the relative path of the Resource class or method.
• @ Get, @ put, @ post, @ Delete. The annotation method is the type of the HTTP request used.
• @ Produces: indicates the mime media type returned.
• @ Consumes: indicates the mime media type that can accept the request.
• @ Pathparam, @ queryparam, @ headerparam, @ cookieparam, @ matrixparam, @ formparam, respectively indicate that the parameters of the method come from different locations of the HTTP request. For example, @ pathparam comes from the URL path, @ queryparam is the URL query parameter, @ headerparam is the header information of the HTTP request, and @ cookieparam is the cookie of the HTTP request.

The current JAX-RS implementation includes:

• Apache cxf is an open-source Web Service Framework.
• Jersey, a reference implementation of the JAX-RS provided by Sun.
• Resteasy, JBoss implementation.
• Restlet, developed by Jerome louvel and Dave pawson, is the earliest rest framework that appeared prior to JAX-RS.
• Apache wink, an Apache Software Foundation incubator project, its service module implements JAX-RS specifications

(From: http://zh.wikipedia.org/wiki/JAX-RS)

 

Equipment

The tools used in this article include:

• Eclipse-jee-Helios
• Java-1.6.0_26
• Apache -- tomcat-6.0.30
• SoapUI-3.6

The external jar packages used are available (required and must be added to the Web container)

• Neethi-3.0.2.jar
• Jsr311-api-1.1.1.jar
• Cxf-bundle-2.6.0.jar

The external jar packages used are available (optional, when and only treated as an independent application runtime)

• Jetty-http-7.5.4.v20111024.jar
• Jetty-io-7.5.4.v20111024.jar
• Jetty-server-7.5.4.v20111024.jar
• Jetty-util-7.5.4.v20111024.jar
• Jetty-continuation-7.5.4.v20111024.jar
• Wsdl4j-1.6.2.jar

Preparation

(Example from: oreilly-restful Java with JAX-RS (12-2009) (atticaworkflow)

 

Create a project

In order to proceed smoothly, create a dynamic web project on Eclipse first. After the project directory that conforms to the war structure is created automatically, the file can be easily exported as a war file, put the following jar package
/Webcontent/WEB-INF/libIn:

• Neethi-3.0.2.jar
• Jsr311-api-1.1.1.jar
• Cxf-bundle-2.6.0.jar

In addition, in the project directory, create a new Lib folder to store the following optional jar packages:

 

• Jetty-http-7.5.4.v20111024.jar
• Jetty-io-7.5.4.v20111024.jar
• Jetty-server-7.5.4.v20111024.jar
• Jetty-util-7.5.4.v20111024.jar
• Jetty-continuation-7.5.4.v20111024.jar
• Wsdl4j-1.6.2.jar

The last step is to add all the nine jar files to the build path of the project, so that the project is ready.

 

Define Service

Here we need to implement a simple rest service for customer management, including:

• Create Customer
• View customer
• Update customer

First, provide the corresponding service interfaces for these operations:

Java code

1. Import java. Io. inputstream;
3. Import javax. ws. Rs. consumes;
4. Import javax. ws. Rs. Get;
5. Import javax. ws. Rs. post;
6. Import javax. ws. Rs. Put;
7. Import javax. ws. Rs. path;
8. Import javax. ws. Rs. pathparam;
9. Import javax. ws. Rs. Produces;
10. Import javax. ws. Rs. Core. response;
11. Import javax. ws. Rs. Core. streamingoutput;
13. @ Path ("/customers ")
14. Public interface customerresource {
16. @ Post
17. @ Consumes ("application/XML ")
18. Public Response createcustomer (inputstream is );
20. @ Get
21. @ Path ("{ID }")
22. @ Produces ("application/XML ")
23. Public streamingoutput getcustomer (@ pathparam ("ID") int ID );
25. @ Put
26. @ Path ("{ID }")
27. @ Consumes ("application/XML ")
28. Public void updatecustomer (@ pathparam ("ID") int ID, inputstream is );
29. }

 

Surprisingly, this interface already contains all the key parts for achieving our stated goals:

1. @ Path: Defines the service path. The top-level path of the entire service defined in the interface is"/Mers MERs
   ", The Service path corresponding to the method is the path value defined by the interface path plus method. If not defined, the interface path is used. For example, the Service path of getcustomer () is :"
   /Customers/{ID}". Therefore, the rest external service path isService context path/customers/
   Sub-Level directory,
2. @ Post, @ get, @ put: Types of HTTP requests supported by the annotation method (refer to the above description)
3. @ Produces, @ consumes: The request MIME type supported or returned by the annotation method.

We can see that the conditions for each method to be called are as follows:

1. Createconsumer ():The request HTTP method is post, the request MIME type is application/XML, and the Request Path is:
   Context path/Mers MERs
2. Getcustomer ():The HTTP Method of the request is get. The MIME type of the request is application/XML. The Request Path is:
   Context path/customers/{ID}
   Note: {ID} is the number of an existing (or nonexistent) customer.
3. Updatecustomer ():The HTTP Method of the request is put; the MIME type of the request is application/XML; The Request Path:
   Context path/customers/{ID}
   Note: {ID} is the number of an existing (or nonexistent) customer.

A good implementation method is to separate the definition and implementation of the rest service. In this way, the code structure is concise and clear, and the implementation and modification of the service definition can be easily carried out in the future.

 

The following describes how to add an implementation:

Java code

1. Public class customerresourceservice implements customerresource {
2. Private Map <integer, Customer> customerdb = new concurrenthashmap <integer, Customer> ();
3. Private atomicinteger idcounter = new atomicinteger ();
5. Public Response createcustomer (inputstream is ){
6. Customer customer = readcustomer (is );
7. Customer. setid (idcounter. incrementandget ());
8. Customerdb. Put (customer. GETID (), customer );
9. System. Out. println ("created customer" + customer. GETID ());
10. Return response. Created (URI. Create ("/Mers MERs/" + customer. GETID ()))
11. . Build ();
12. }
14. Public streamingoutput getcustomer (int id ){
15. Final customer = customerdb. Get (ID );
16. If (customer = NULL ){
17. Throw new webapplicationexception (response. Status. not_found );
18. }
19. Return new streamingoutput (){
20. Public void write (outputstream) throws ioexception,
21. Webapplicationexception {
22. Outputcustomer (outputstream, customer );
23. }
24. };
25. }
27. Public void updatecustomer (int id, inputstream is ){
28. Customer update = readcustomer (is );
29. Customer current = customerdb. Get (ID );
30. If (current = NULL)
31. Throw new webapplicationexception (response. Status. not_found );
32. Current. setfirstname (update. getfirstname ());
33. Current. setlastname (update. getlastname ());
34. Current. setstreet (update. getstreet ());
35. Current. setstate (update. getstate ());
36. Current. setzip (update. getzip ());
37. Current. setcountry (update. getcountry ());
38. }
40. Protected void outputcustomer (outputstream OS, customer Cust)
41. Throws ioexception {
42. Printstream writer = new printstream (OS );
43. Writer. println ("<customer ID = \" "+ Cust. GETID () +" \ "> ");
44. Writer. println ("<first-name>" + Cust. getfirstname () + "</first-name> ");
45. Writer. println ("<last-name>" + Cust. getlastname () + "</last-name> ");
46. Writer. println ("<Street>" + Cust. getstreet () + "</street> ");
47. Writer. println ("<city>" + Cust. getcity () + "</city> ");
48. Writer. println ("<State>" + Cust. getstate () + "</State> ");
49. Writer. println ("<zip>" + Cust. getzip () + "</zip> ");
50. Writer. println ("<country>" + Cust. getcountry () + "</country> ");
51. Writer. println ("</customer> ");
52. }
54. Protected customer readcustomer (inputstream is ){
55. Try {
56. Documentbuilder builder = documentbuilderfactory. newinstance ()
57. . Newdocumentbuilder ();
58. Document Doc = builder. parse (is );
59. Element root = Doc. getdocumentelement ();
60. Customer Cust = new customer ();
61. If (root. getattribute ("ID ")! = NULL
62. &&! Root. getattribute ("ID"). Trim (). Equals ("")){
63. Cust. setid (integer. valueof (root. getattribute ("ID ")));
64. }
65. Nodelist nodes = root. getchildnodes ();
66. For (INT I = 0; I <nodes. getlength (); I ++ ){
67. Node item = nodes. item (I );
68. If (! (Item instanceof element )){
69. Continue;
70. }
71. Element element = (element) nodes. item (I );
72. If (element. gettagname (). Equals ("first-name ")){
73. Cust. setfirstname (element. gettextcontent ());
74. } Else if (element. gettagname (). Equals ("last-name ")){
75. Cust. setlastname (element. gettextcontent ());
76. } Else if (element. gettagname (). Equals ("street ")){
77. Cust. setstreet (element. gettextcontent ());
78. } Else if (element. gettagname (). Equals ("city ")){
79. Cust. setcity (element. gettextcontent ());
80. } Else if (element. gettagname (). Equals ("state ")){
81. Cust. setstate (element. gettextcontent ());
82. } Else if (element. gettagname (). Equals ("Zip ")){
83. Cust. setzip (element. gettextcontent ());
84. } Else if (element. gettagname (). Equals ("country ")){
85. Cust. setcountry (element. gettextcontent ());
86. }
87. }
88. Return Cust;
89. } Catch (exception e ){
90. Throw new webapplicationexception (E, response. Status. bad_request );
91. }
92. }
93. }

 

The implementation of these methods is very direct and I will not elaborate on it. However, note the following:

 

It is best not to include the definition of a service in the implementation, such as the @ path label and @ pathparam label. If you want to modify the definition, it is best to modify it in the interface; or, if you want to override an annotation of an interface method, the annotation definitions of all interfaces and methods must be rewritten, rather than modifying the changed ones.