Create Restful Web Service With CXF 2.1.X/CXF 2.2, Part 1: Create a service in Tomcat

Create Restful Web Service With CXF 2.1.X/CXF 2.2, Part 1: Create a service in Tomcat

Recently, Rest architecture style or Restful web service is a hot topic for SOA, web service design and architecture style. But unfortunately, there are not many articles introducing how to develop a real restful web services. So, this series of articles try to introduce how to develop a Restful web services with CXF. The reason why i choose CXF is just because we are using CXF to develop SOAP web service, and CXF 2.1.X already supports JSR-311 API version 0.8 and CXF 2.2 plans to support JSR-311 1.0 API.

Some of the examples and comments are directly copies from CXF Restful page (http://cwiki.apache.org/CXF20DOC/restful-services.html), thanks for CXF team's great work.

This article will focus on a simplest service and how to config it as a Restful web service in tomcat. My tomcat version is 6.0.X.

Software: Tomcat 6.0.x, CXF 2.1
1. use CXF in Tomcat. please refer to CXF doc. It is pretty easy.
2. the major configuration file for CXF is  WEB-INF/cxf-servlet.xml, we will add related configuration into this file.

< beans  xmlns ="http://www.springframework.org/schema/beans"
      xmlns:xsi ="http://www.w3.org/2001/XMLSchema-instance"
      xmlns:jaxrs ="http://cxf.apache.org/jaxrs"   <!-- This is the name space for jax rs -->
      xmlns:jaxws ="http://cxf.apache.org/jaxws"
      xmlns:soap ="http://cxf.apache.org/bindings/soap"
      xsi:schemaLocation ="
      http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.0.xsd
      http://cxf.apache.org/bindings/soap http://cxf.apache.org/schemas/configuration/soap.xsd
      http://cxf.apache.org/jaxrs                                             <!-- This is the schema location for CXF jax rs -->
      http://cxf.apache.org/schemas/jaxrs.xsd                     <!-- This is the schema location for CXF jax rs xsd -->
      http://cxf.apache.org/jaxws
      http://cxf.apache.org/schemas/jaxws.xsd" >

     <!--  JAX-RS  -->
   < jaxrs:server  id ="customerService"  address ="/" >     <!--NOTE: the address is relative address, the whole URL pattern will be http://localhost:8080/web app/services /, and the services  -->
     < jaxrs:serviceBeans >
        < bean  class ="com.starcite.commonsearch.example.rs.CustomerServiceImpl"   />    <!-- this is the class path, cannot be interface-->
     </ jaxrs:serviceBeans >
   </ jaxrs:server >

</ beans >

3. Sample Service interface & implementation class

@Path( " /customerservice/ " )            <!-- URI for this service, the whole URI will be http://localhost:8080/web app/services /customerservice/ -->
public   interface  CustomerService {

    @GET                                    <!-- i guess @GET and @Path annotation is pretty easy to understand, if not, please read http://www.blogjava.net/justinchen/archive/2008/11/05/238760.html -->
    @Path( " /customers/ " )       <!-- URI for this service, the whole URI will be http://localhost:8080/web app/services /customerservice/customers/ -->
     public Customer getCustomers();
    
    @GET
    @Path( " /customers/{id}/ " )    <!-- URI for this service, the whole URI will be http://localhost:8080/web app/services /customerservice/customers/ 123/ etc -->
     public  Customer getCustomer(@PathParam( " id " ) String id);  <!-- @PathParam is the parameter extracts the value of a URI template parameter. -->

    @PUT
    @Path( " /customers/ " )
     public  Response updateCustomer(Customer customer);
    
    @POST
    @Path( " /customers/ " )
     public  Response addCustomer(Customer customer);
    
    @DELETE
    @Path( " /customers/{id}/ " )
     public  Response deleteCustomer(@PathParam( " id " ) String id);
    
    @Path( " /orders/{orderId}/ " )
     public  Order getOrder(@PathParam( " orderId " ) String orderId);
    
}

Service impl class code. NOTE: there are no need any annotation. But also, there are a little bit different on return value comparing to SOAP web service. In SOAP web service, we can directly use any java class. But here, we used some special class, like Response, we will disucss this more in other articles.

public   class  CustomerServiceImpl  implements  CustomerService {
    
     private   long  currentId  =   123 ;
    Map < Long, Customer >  customers  =   new  HashMap < Long, Customer > ();
    Map < Long, Order >  orders  =   new  HashMap < Long, Order > ();

     public  CustomerServiceImpl() {
        init();
    }

     public  Customer getCustomers() {
        System.out.println( " ----invoking getCustomer, Customer id is: XXX  "  ); 
        
        Customer c  =  customers.get( 123 );
        
         return  c;
    }
    
     public  Customer getCustomer(String id) {
        System.out.println( " ----invoking getCustomer, Customer id is:  "   +  id);
         long  idNumber  =  Long.parseLong(id);
        Customer c  =  customers.get(idNumber);
         return  c;
    }

     public  Response updateCustomer(Customer customer) {
        System.out.println( " ----invoking updateCustomer, Customer name is:  "   +  customer.getName());
        Customer c  =  customers.get(customer.getId());
        Response r;
         if  (c  !=   null ) {
            customers.put(customer.getId(), customer);
            r  =  Response.ok().build();
        }  else  {
            r  =  Response.notModified().build();
        }

         return  r;
    }

     public  Response addCustomer(Customer customer) {
        System.out.println( " ----invoking addCustomer, Customer name is:  "   +  customer.getName());
        customer.setId( ++ currentId);

        customers.put(customer.getId(), customer);

         return  Response.ok(customer).build();
    }

     public  Response deleteCustomer(String id) {
        System.out.println( " ----invoking deleteCustomer, Customer id is:  "   +  id);
         long  idNumber  =  Long.parseLong(id);
        Customer c  =  customers.get(idNumber);

        Response r;
         if  (c  !=   null ) {
            r  =  Response.ok().build();
            customers.remove(idNumber);
        }  else  {
            r  =  Response.notModified().build();
        }

         return  r;
    }

     public  Order getOrder(String orderId) {
        System.out.println( " ----invoking getOrder, Order id is:  "   +  orderId);
         long  idNumber  =  Long.parseLong(orderId);
        Order c  =  orders.get(idNumber);
         return  c;
    }

     final   void  init() {
        Customer c  =   new  Customer();
        c.setName( " John " );
        c.setId( 123 );
        customers.put(c.getId(), c);

        Order o  =   new  Order();
        o.setDescription( " order 223 " );
        o.setId( 223 );
        orders.put(o.getId(), o);
    }

}

4. POJO Class, such as Customer. POJO class is pretty similar, we can also use JAXB to covert object to XML.

@XmlRootElement(name  =   " Customer " )
public   class  Customer {
     private   long  id;
     private  String name;

     public   long  getId() {
         return  id;
    }

     public   void  setId( long  id) {
         this .id  =  id;
    }

     public  String getName() {
         return  name;
    }

     public   void  setName(String name) {
         this .name  =  name;
    }
}

5. Now, you can deploy this web app as normal web app. and after you start tomcat, you are able to try the following link in browser -
http://localhost:8080/vendor_search/services/customerservice/customers/ Or
http://localhost:8080/vendor_search/services/customerservice/customers/123/

the browser will return a XML for a cusomer object.

In next articles, we will implement more complex user case to prove the Restful web service.