Apache CXF Web Service Development

XML stands for Extensible Markup Language. XML is a markup language that specifies or describes the format of the data to be exchanged between two parties. The data is significantly structured as tags or elements in a hierarchical order. A user can create his/her own tag to represent structured information. XML has become the de facto standard for representing structured information. Some of the important standard technologies associated with an XML document are listed below:

<?xml version="1.0"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" 
xmlns:ns1="http://apress.com/beginjava6/address" 
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soapenv:Header></soapenv:Header>
<soapenv:Body>
<ns1:Address>
<ns1:addressLine1>1501ACity</ns1:addressLine1>
<ns1:addressLine2>UCity</ns1:addressLine2>
<ns1:city>SFO</ns1:city>
<ns1:state>CA</ns1:state>
<ns1:country>US</ns1:country>
</ns1:Address>
</soapenv:Body>
</soapenv:Envelope>

<?xml version='1.0' encoding='UTF-8'?><wsdl:definitions name="AddressVerifyProcessImplService" targetNamespace="http://order.demo/" xmlns:ns1="http://schemas.xmlsoap.org/soap/http" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:tns="http://order.demo/" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<wsdl:types>
<!-- Schema definition for Address element. This serves as the input message format for invoking the Address verification service. -->
<xs:schema attributeFormDefault="unqualified" elementFormDefault="unqualified" targetNamespace="http://order.demo/" xmlns:tns="http://order.demo/" xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="Address" type="tns:address" />
<xs:element name="verifyAddress" type="tns:verifyAddress" />
<xs:element name="verifyAddressResponse" type="tns:verifyAddressResponse" />
<xs:complexType name="verifyAddress">
<xs:sequence>
<xs:element minOccurs="0" name="arg0" type="tns:address" />
</xs:sequence>
</xs:complexType>
<xs:complexType name="address">
<xs:sequence>
<xs:element minOccurs="0" name="addressLine1" type="xs:string" />
<xs:element minOccurs="0" name="addressLine2" type="xs:string" />
<xs:element minOccurs="0" name="city" type="xs:string" />
<xs:element minOccurs="0" name="country" type="xs:string" />
<xs:element minOccurs="0" name="state" type="xs:string" />
</xs:sequence>
</xs:complexType>
<xs:complexType name="verifyAddressResponse">
<xs:sequence>
<xs:element minOccurs="0" name="return" type="xs:string" />
</xs:sequence>
</xs:complexType>
</xs:schema>
  </wsdl:types>
  <!-- Specifies the Messages for Address Verification Service. -->
  <wsdl:message name="verifyAddressResponse">
    <wsdl:part element="tns:verifyAddressResponse" name="parameters">
    </wsdl:part>
  </wsdl:message>
  <wsdl:message name="verifyAddress">
    <wsdl:part element="tns:verifyAddress" name="parameters">
    </wsdl:part>
  </wsdl:message>
    <!-- Specifies the Operations for Verify Address service. -->
  <wsdl:portType name="AddressVerifyProcess">
    <wsdl:operation name="verifyAddress">
      <wsdl:input message="tns:verifyAddress" name="verifyAddress">
    </wsdl:input>
      <wsdl:output message="tns:verifyAddressResponse" name="verifyAddressResponse">
    </wsdl:output>
    </wsdl:operation>
  </wsdl:portType>
  <!-- Specifies the SOAP Binding for Verify Address Process. -->
  <wsdl:binding name="AddressVerifyProcessImplServiceSoapBinding" type="tns:AddressVerifyProcess">
    <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http" />
    <wsdl:operation name="verifyAddress">
      <soap:operation soapAction="" style="document" />
      <wsdl:input name="verifyAddress">
        <soap:body use="literal" />
      </wsdl:input>
      <wsdl:output name="verifyAddressResponse">
        <soap:body use="literal" />
      </wsdl:output>
    </wsdl:operation>
  </wsdl:binding>
    <!-- Service definition for Verify Address . -->
    <!-- The soap location specifies the URL where the address verify service is located. -->
  <wsdl:service name="AddressVerifyProcessImplService">
  <wsdl:port binding="tns:AddressVerifyProcessImplServiceSoapBinding" name="AddressVerifyProcessImplPort">
      <soap:address location="http://localhost:9000/AddressVerifyProcess" />
    </wsdl:port>
  </wsdl:service>
</wsdl:definitions>

REST (Representational State Transfer) is neither a technology nor a standard; it's an architectural style—a set of guidelines for exposing resources over the Web. The REST architecture style is related to a resource, which is a representation identified by a Uniform Resource Indicator (URI), for example, http://cxf.soaweb.co.in/mybook. The resource can be any piece of information such as a book, order, customer, employee, and so on. The client queries or updates the resource through the URI and, therefore, influences a state change in its representation. All resources share a uniform interface for the transfer of state between client and resource.

The World Wide Web is a classic example built on the REST architecture style. As implemented on the World Wide Web, URIs identify the resources (http://amazon.com/mybook), and HTTP is the protocol by which resources are accessed. HTTP provides a uniform interface and set of methods to manipulate the resource. A client program, like a web browser, can access, update, add, or remove a Web resource through URI using various HTTP methods, like GET and POST, thereby changing its representational state.

Service Registry provides a mechanism to look up web services. Traditionally, there was UDDI specification that defined the standards on registering and discovering a web service, but it lacked enterprise-wide adoption. Enterprises started shipping their own version of Service Registry, providing enterprise capabilities like service versioning, service classifications, and life cycle management.

Two of the most widely used approaches for developing web services are SOAP (Simple Object Access Protocol) and the REST (Representational State Transfer) architecture style. In depth details on developing SOAP-based web services are provided in Chapters 2-5, while Chapters 6 and 7 are dedicated to RESTful web service development.

A web service involves three types of roles—a service consumer , a service provider, and an optional service registry. The following diagram shows the interaction between the service provider, the service consumer, and the service registry:

The service providers furnish the services over the web and respond to web service requests. The service consumer consumes the services offered by the service provider. In SOAP-based web services, the service provider publishes the contract (WSDL file) of the service over the web where a consumer can access it directly or by looking up a service registry. The service consumer usually generates a web service client code from a WSDL file using the tools offered by the web service framework to interact with the web service. In the next chapter you will look at how to create web service clients from a WSDL file.

With RESTful Web Services there is no formal contract between the service provider and the service consumer. The service requestor needs to know the format of the message, for instance, XML or JSON (Java Script Object Notation), and operations supported by the service provider. The service provider exposes the set of operations using standard HTTP methods like GET or POST. The service requestor invokes one of the methods defined for the resources using the URI over the HTTP protocol.

The choice of adopting SOAP rather than REST depends on your application's requirements. If your requirement consists of transmitting and receiving simple XML messages, then you would probably go with RESTful Web Services. However, if your requirement consists of various contracts to be defined and negotiated between the provider and consumer such as using a WSDL (Web Service Description Language) file and adhering to various web services specifications (WS Specifications) such as web service security for enterprise adoption, then SOAP-based web services is the right option. If you are developing SOAP-based services, then you also need to be aware of SOAP communication styles.

The web service SOAP communication style plays a significant role in communicating SOAP XML messages between the service provider and the service consumer. There exist two types of SOAP message styles, Document and RPC. The SOAP message styles are defined in a WSDL document as SOAP binding. A SOAP binding can have either an encoded use or a literal use. Encoding as the term implies, the message would be encoded using some format, while literal specifies plain text messages without any encoding logic.

Document style, as the name suggests, deals with XML documents as payloads which adhere to well defined contracts, typically created using XML schema definitions. The XML schema format specifies the contract for business messages being exchanged between web service provider and consumer, which the consumers can call and adhere to. The XML schema defines the request and response message format between the service provider and the service consumer. Document literal style is the preferred way of web service communication for achieving interoperability.

RPC (Remote Procedure Call) style, on the other hand, indicates that the SOAP body contains an XML representation of a method. In order to serialize method parameters into the SOAP message so it can be deserialized back by any web service implementation, the SOAP specification defines a standard set of encoding rules. As RPC is traditionally used in conjunction with SOAP encoding rules, the combination is referred to as RPC/encoded. You also have an RPC/literal communication style model where you don't have any encoding formats, but the messages are still limited to RPC method-based communication, where messages can't be validated as they are not tied to any XML Schema definition. You should probably avoid developing RPC style web services as it has a lot of interoperability issues.

Exactly what does CXF stand for? Apache CXF is the product of two projects, Celtix and XFire, hence the name CXF. Celtix, an open source Java-based Enterprise Service Bus (ESB) project, is a product of ObjectWeb consortia that delivers open source middleware solutions. The project was sponsored by IONA. On the other hand, XFire, a Java-based SOAP framework, is an open source project from Codehaus. Both Celtix and XFire, while in their initial versions, had many things in common and therefore the developers of both projects decided to bring out the best of both worlds and planned a better 2.0 version of Celtix and XFire. The communities of both these projects entered incubation at the Apache Software foundation to develop version 2.0. It took about 20 months at the Apache incubator before CXF finally rolled out. CXF is now formally known as Apache CXF which concentrates on delivering an open source web service framework. The framework which had its first release as v2.0, is now evolved as v2.2, with bug fixes, and the addition of new features.

Picking up a framework is always a challenging task. There are many web service frameworks available today. Historically, there was Axis 1 which evolved into Axis 2, providing better flexibility and enhanced support for web service standards. Other widely used web service frameworks are GlassFish Metro, Glue, JBossWS, and so on. Every web services framework aims to provide a robust infrastructure for the developer to conveniently build, deploy, and publish the web services. So which one is the better framework? That's a million dollar question!

We choose CXF rather than other web service frameworks as it supports all the leading web service standards and provides a simplified programming model for developing SOAP and RESTful-based web services, along with options for various other application protocols. CXF provides a flexible deployment model for implementing web services. More specifically, we choose CXF as it provides the following capabilities.

You will have to download and install the following software before setting up the environment. The book illustrates the setup process in a Windows environment. The same can be emulated in a Unix-based environment with ease:

Once the above list of software is installed, we go about setting up the following environment variables:

The environment setup can also be automated using batch script. The script might look like the following:

@echo off
rem ---------------------------------------------------------------
rem CXF Environment Setup script
rem ---------------------------------------------------------------
set JAVA_HOME=C:\jdk1.5.0_12
set CATALINA_HOME=C:\Program Files\Tomcat 6.0
set ANT_HOME=C:\apache-ant-1.7.1
set CXF_HOME=C:\apache-cxf-2.2.3
set PATH=%PATH%;%JAVA_HOME%\bin;%CATALINA_HOME%\bin;%ANT_HOME%\bin;%CXF_HOME%\bin
rem ---------------------------------------------------------------

Apache CXF also supports a Maven-based build and installation. For readers using Maven 2 for developing their applications, the CXF artifacts can be accessed from the Maven central repository itself. The complete release is available at the following location:

http://repo1.maven.org/maven2/

The following POM dependencies need to be declared to build CXF code using Maven:

<properties>
  <cxf.version>2.2.1</cxf.version>
</properties>

<dependencies>
   <dependency>
      <groupId>org.apache.cxf</groupId>
      <artifactId>cxf-rt-frontend-jaxws</artifactId>
      <version>${cxf.version}</version>
   </dependency>
   <dependency>
      <groupId>org.apache.cxf</groupId>
      <artifactId>cxf-rt-transports-http</artifactId>
      <version>${cxf.version}</version>
   </dependency>
   <dependency>
            <groupId>org.apache.cxf</groupId>
            <artifactId>cxf-rt-transports-http-jetty</artifactId>
            <version>${cxf.version}</version>
    </dependency>
</dependencies>

In each chapter we have developed the source code from scratch along with Ant build files to build and run the code. If you are interested in running the examples directly without developing it from scratch, the entire source code is available at the Packt website (www.packtpub.com/files/code/5401_Code.zip). The appendix chapter Getting Ready with the Code Examples provides detailed instructions on how to download the source code from the Packt site. If you plan to use Maven, relevant pom.xml files are provided with the source code download. Refer to the Using Maven for Build management section in the Getting Ready with the Code Examples appendix chapter on how to use Maven to build the examples.