JAX-RS Service Development

Overview

This sample includes a basic REST-based web service developed using JAX-RS (JSR-311). The client code in this sample demonstrates how to send HTTP GET/POST/PUT/DELETE requests. The server code demonstrates how to build a RESTful endpoint through JAX-RS (JSR-311) APIs.

What happens when you run the sample

The following events occur on the client and server when you run this sample:

A RESTful customer service is provided on the URL http://localhost:9000/customers. Users access this URI to operate on a customer.
The server responds to an HTTP GET request to the URL http://localhost:9000/customerservice/customers/123 and returns an XML document with customer information for a customer instance whose id is 123.
The server responds to an HTTP GET request to the URL http://localhost:9000/customerservice/orders/223/products/323 and returns an XML document with product information for product 323 that belongs to order 223.
The server responds to an HTTP POST request to the URL http://localhost:9000/customerservice/customers and adds a customer named Jack.
The server responds to an HTTP PUT request to the URL http://localhost:9000/customerservice/customers and updates the customer instance whose id is 123.

Using Maven

These instructions use Maven to build and run the sample. If you prefer to use wsdl2java, javac, and java to build and run the sample, see the ReadMe file located in your install_dir\samples\jax_rs\basic\ directory.

See About Maven and Installing and setting up Maven for more information about using Maven with the FUSE Services Framework samples.

Building and running the sample using Maven

The pom.xml file located in the base directory of this sample is used to build and run the demo.

To build and run the sample:

Open a console to the sample directory, install_dir\samples\jax_rs\basic\ and enter the following command to build the sample:

mvn install

Maven builds the sample and downloads required JAR files to your Maven repository:

[INFO] Scanning for projects...
[INFO] ------------------------------------------------------------------------
[INFO] Building Unnamed - org.apache.cxf.samples:jax_rs_basic:jar:1.0
[INFO]    task-segment: [install]
[INFO] ------------------------------------------------------------------------
...
[INFO] Installing install_dir\samples\jax_rs\basic\target\jax_rs_basic-1.0.jar to
C:\Documents and Settings\kpatras\.m2\repository\org\apache\cxf\samples\jax_rs_basic\
1.0\jax_rs_basic-1.0.jar
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESSFUL
[INFO] ------------------------------------------------------------------------
...

Enter the following command to start the server:
```
mvn -Pserver
```
When the server is started, the console displays the message Server ready....
Open another console at the same location and enter the following command to start the client:
```
mvn -Pclient
```
The client starts and sends a greeting to the server. Messages in the client and server consoles show the messages sent as the sample runs.

Examining the output

The messages between the client and server appear rapidly in the consoles as messages are exchanged. When the messages have all been sent, you can examine the output in the client and server consoles to observe the following events:

The client requests customer information:

Sent HTTP GET request to query customer info

The server invokes getCustomer to get customer information:

invoking getCustomer, Customer id is: 123

The client receives the customer information in an XML document:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Customer>
   <id>123</id>
   <name>John</name>
</Customer>

The client requests product information:

Sent HTTP GET request to query sub resource product info

The server invokes getOrder and getProduct:

invoking getOrder, Order id is: 223
invoking getProduct with id: 323

The client receives the product information in an XML document:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Product>
   <description>product 323</description>
   <id>323</id>
</Product>

The client request an update to the customer information:
```
Sent HTTP PUT request to update customer info
```
The server invokes updateCustomer:
```
invoking updateCustomer, Customer name is: Mary
```
The client receives a response with status code:
```
Response status code: 200
Response body:
```

The client requests adding the customer:

Sent HTTP POST request to add customer

The server invokes addCustomer:

invoking addCustomer, Customer name is: Jack

The client receives a response with an XML document, and the sample ends:

Response status code: 200
Response body:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Customer>
   <id>124</id>
   <name>Jack</name>
</Customer>

Client Invoking is succeeded!

Understanding the sample

When you run the Maven mvn install command, Maven compiles the Java files and creates Java class files. Maven creates the install_dir\\samples\jax_rs\basic\target directory, which includes the client and server class files.

When you run the Maven mvn -Pserver and mvn -Pclient commands, Maven starts the server and client and executes the operations in the Java class files.

The sample files in the jax_rs\basic directory include the following:

pom.xml — This file is used by the Maven tooling when creating the service unit and required files for packaging and deploying the service into a container.

install_dir\samples\jax_rs\basic\src\demo\jaxrs\client\*.java — Java files that define the client classes, including Client.java, which sends HTTP GET, PUT, and POST requests:

Example 5.6. JAX-RS Sample: Client.java

...
private Client() {
}
                  
public static void main(String args[]) throws Exception {
   ...
   // Sent HTTP GET request to query customer info
   System.out.println("Sent HTTP GET request to query customer info");
   URL url = new URL("http://localhost:9000/customerservice/customers/123");
   InputStream in = url.openStream();
   System.out.println(getStringFromInputStream(in));
                  
   // Sent HTTP GET request to query sub resource product info
   ...
   System.out.println("Sent HTTP GET request to query sub resource product info");
   url = new
      URL("http://localhost:9000/customerservice/orders/223/products/323");
   in = url.openStream();
   System.out.println(getStringFromInputStream(in));
                  
    // Sent HTTP PUT request to update customer info
   ...
   System.out.println("Sent HTTP PUT request to update customer info");
   Client client = new Client();
   String inputFile = client.getClass().getResource("update_customer.txt").getFile();
   File input = new File(inputFile);
   PutMethod put = new
      PutMethod("http://localhost:9000/customerservice/customers");
   RequestEntity entity = new FileRequestEntity(input, "text/xml; charset=ISO-8859-1");
   put.setRequestEntity(entity);
   HttpClient httpclient = new HttpClient();
   ... 
   // Sent HTTP POST request to add customer
   System.out.println("Sent HTTP POST request to add customer");
   inputFile = client.getClass().getResource("add_customer.txt").getFile();
   input = new File(inputFile);
   PostMethod post = new
      PostMethod("http://localhost:9000/customerservice/customers");
   post.addRequestHeader("Accept" , "text/xml");
   entity = new FileRequestEntity(input, "text/xml; charset=ISO-8859-1");
   post.setRequestEntity(entity);
   httpclient = new HttpClient();
 ...
}

install_dir\samples\jax_rs\basic\src\demo\jaxrs\server\*.java — Java files that define the server classes. These files include Server.java, which creates a new instance of the RESTful service, CustomerService():

Example 5.7. JAX-RS Sample: Server.java

package demo.jaxrs.server;
                  
import org.apache.cxf.jaxrs.JAXRSServerFactoryBean;
import org.apache.cxf.jaxrs.lifecycle.SingletonResourceProvider;
                  
public class Server {
                  
   protected Server() throws Exception {
      JAXRSServerFactoryBean sf = new JAXRSServerFactoryBean();
      sf.setResourceClasses(CustomerService.class);
      sf.setResourceProvider(CustomerService.class, 
      new SingletonResourceProvider(new CustomerService()));
      sf.setAddress("http://localhost:9000/");
                  
      sf.create();
   }
                  
   public static void main(String args[]) throws Exception {
      new Server();
      System.out.println("Server ready...");            
   ...
}