Spring web services at a glance -

Spring web services is focused on creating contract-first document oriented web services. Spring web services, being a product of Spring, offer first class support of using Spring configurations and integrating with Spring framework.

Spring promotes contract-first development completely and provides an ability to plug-in various XML APIs (SAX, DOM, STAXM, XOM, JDOM..) to handle XML messages. Using Spring web services, you can always ensure the XML contract (xml schemas) is marshaled correctly into Java objects. Spring web services support JAXB 1 and 2, Castor, XMLBeans, JiBX, and XStream as part of its XML Marshalling support.

Spring web-service provides options to secure web services using Acegi security and provides ability to encrypt/decrypt messages and support for webservices security standards.

CXF at a glance –

Apache CXF is an open source web service framework that provides an easy to use, standard-based programming model for developing web services. Web services can be implemented using different application protocols like SOAP, XML, JSON, RESTful HTTP, and support various transport protocols like HTTP or JMS (JavaMessage Service).

CXF supports both code-first and contract first development and provides first class support for using Spring configuration.  CXF supports all of the widely used web service specifications.

To get started with CXF, you can download a complementary chapter and index of Apache CFX Web Service Development book.

Which one should I use ?

The choice of selecting a web services stack depends on multiple factors like standards compliance, ease of development , deployment options, unit testing options, integration with leading frameworks like Spring, flexibility and extensibility and so on.

In my view, the strict enforcement on using contract first development only with spring web services can become a bottle neck, depending on your requirements.

There might be scenarios where you would want to use code-first development and can easily generate contracts (xml schemas) that way you intended. If you are aware of how Java objects are generated to XML and limitations associated with it, this would also help you to generate the right XML format.

CXF provides support for code first and contract first development, and provides ability to plug-in various flexible binding mechanisms. Leaving the choice of code-first and contract first development to a user based on their requirements is a big plus.  Using CXF, you could achieve what Spring web services offer today, although it doesn’t support the numerous XML API options and binding support offered by Spring web-services, but it should suffice for most of the requirements.

Tweet This Post Delicious Digg This Post

In this blog, we will look at how to create web services using Apache CXF framework starting with XML Schema (XSD). You will probably start with XSD, when you are using contract first development and defining contract for your web services or have an existing XSD that you would want to use as part of web service development.  Lot of industry schemas is available as XSD such as ACORD and while developing industry solutions for interoperability, you would typically use XSD approach if a standard schema is available for that industry domain. XSD would provide the input and output message format for web service operations.

We will revisit the sample example of Order process application that I had listed in my blog -  http://cxf.soaweb.co.in/index.php/2010/01/18/develop-simple-web-service-with-cxf-and-spring/ . In that blog, I had used the code first approach, where I started with Java code and exposed it as web services.

First we would create the contract for the Order Processing web service. We would name this as Order.xsd. Following shows the listing of Order.xsd. For simplicity, we would use the same Order.xsd schema for input and output operations.

<?xml version=”1.0″ encoding=”UTF-8″?>

<xs:schema attributeFormDefault=”qualified” elementFormDefault=”qualified”

targetNamespace=”http://order.demo/” xmlns:tns=”http://order.demo/”

xmlns:xs=”http://www.w3.org/2001/XMLSchema”>

<xs:complexType name=”order”>

<xs:sequence>

<xs:element minOccurs=”0″ type=”xs:string” />

<xs:element minOccurs=”0″ type=”xs:string” />

<xs:element minOccurs=”0″ type=”xs:double” />

<xs:element minOccurs=”0″ type=”xs:int” />

<xs:element minOccurs=”0″ type=”xs:string” />

</xs:sequence>

</xs:complexType>

</xs:schema>

Once you have created the contract, there are two alternatives that you have. First alternative is to  create a WSDL and include the XSD as part of it and than use the CXF WSDL2Java to create a service implementation. Next approach is to generate Java objects from XSD and used the generated object for input and output operations while creating web services. In this later approach, you don’t need to create a WSDL and instead can start off with Java code and use the generated object as input and output parameter for service methods. We would go with the second approach.

Next we would generate the Java type objects for XML Schema using XMLBeans . XMLBeans is a technology for accessing XML by binding it to Java types. Before that, let’s create the project structure for our web service project.  To get started, I have provided the project source code in a zip file. Download the project folder from CXF XSD Source Code – and unzip it any drive. You would see the following project folder .

The schemas folder contains the Order.xsd and src contains the source code for web service project. The build.xml contained in cxfxsdfirst folder, is the ant build file for building and running the project. The build.xml requires CXF_HOME environment variable to be set to CXF distribution as it uses CXF and dependent library files from CXF_HOME\lib for building and running the code .

Next we would, generate the Java XML schema code for Order.xsd by running the following command.

ant  buildOrderXMLBean

This buildOrderXMLBean uses the org.apache.xmlbeans.impl.tool.XMLBean class to generate Java types for Order.xsd. After running the above command, the generated compiled files would be packaged inside jar file named orderxmlbeans.jar and copied into build folder. The order element defined in Order.xsd would be mapped to the generated Order class. We would use the Order class as input and output parameter for the web service operation.

Next, we would create a service interface and service implementation for Order Process service. The service interface and implementation is exactly the same as Order Process service that was developed in code first approach in my earlier blog, hence we don’t go into much details on explaining the code. If you need more details, please refer to my earlier post- http://cxf.soaweb.co.in/index.php/2010/01/18/develop-simple-web-service-with-cxf-and-spring/

Following shows the service interface. The source code is available in cxfxsdfirst/src/demo/order

package demo.order;

import javax.jws.WebService;

@WebService

public interface OrderProcess {

Order processOrder(Order order);

}

Note that the Order class parameter comes from the generated Java types. That’s the only difference from code first approach in terms of service interface and implementation, where we have had created the Order java bean upfront.

The implementation class is OrderProcessImpl.java. Following shows the listing

package demo.order;

import javax.jws.WebService;

@WebService

public class OrderProcessImpl implements OrderProcess {

public Order processOrder(Order order) {

String orderID = validate(order);

order.setId(orderID);

return order;

}

//Rest of the code commented out. Refer to downloaded code

}

Next, we would create a Stand-alone server named Server.java that would publish the order process server.  The following shows the code listing. The code is available in cxfxsdfirst/src/demo/order.

package demo.order;

import java.io.BufferedReader;

import java.io.IOException;

import java.io.InputStreamReader;

import org.apache.cxf.databinding.DataBinding;

import org.apache.cxf.jaxws.JaxWsServerFactoryBean;

public class Server {

public static void main(String[] args) {

// Service instance

OrderProcess orderProcess = new OrderProcessImpl();

//AddressVerifyProcess orderProcess = new AddressVerifyProcessImpl();

JaxWsServerFactoryBean restServer = new JaxWsServerFactoryBean();

restServer.setServiceBean(orderProcess);

restServer.setAddress(”http://localhost:8080/”);

try {

restServer.setDataBinding(org.apache.cxf.xmlbeans.XmlBeansDataBinding.class.newInstance());

} catch (IllegalAccessException e1) {

e1.printStackTrace();

} catch (InstantiationException e1) {

e1.printStackTrace();

}

restServer.create();

BufferedReader br = new BufferedReader(new InputStreamReader(System.in));

try {

br.readLine();

} catch (IOException e) {

}

System.out.println(”Server Stopped”);

}

}

The code above uses the JaxWsServerFactoryBean for publishing the Order Process service class over address http://localhost:8080/. The most important code of the Order Process is the following line –

restServer.setDataBinding(org.apache.cxf.xmlbeans.XmlBeansDataBinding.class.newInstance());

This tells the CFX framework to uses XmlBeans data binding , instead of default JAXB data binding.

Next , we would create a stand-alone client that would invoke the Order Process service. The client and Spring configuration file s similar to one developed for code first. If you need details of the explanation of the code. please refer to Developing a client section in http://cxf.soaweb.co.in/index.php/2010/01/18/develop-simple-web-service-with-cxf-and-spring/ blog.

The client code is available in – cxfxsdfirst/src/demo/order/client folder. Following shows the code listing for Client.java

package demo.order.client;

import demo.order.OrderProcess;

import demo.order.Order;

import demo.order.impl.OrderImpl;

import org.springframework.context.support.ClassPathXmlApplicationContext;

public final class Client {

public Client() {

}

public static void main(String args[]) throws Exception {

ClassPathXmlApplicationContext context

= new ClassPathXmlApplicationContext(new String[] {”demo/order/client/client-beans.xml”});

OrderProcess client = (OrderProcess) context.getBean(”orderClient”);

Order order = Order.Factory.newInstance();

order.setCustomerID(”C001″);

order.setItemID(”I001″);

order.setQty(100);

order.setPrice(200.00);

Order orderResponse = client.processOrder(order);

String message = (orderResponse.getId() == null) ? “Order not approved” : “Order approved; order ID is ” + orderResponse.getId();

System.out.println(message);

}

}

The following shows the “client-beans.xml”, the Spring configuration file which is used by Client.java.

<?xml version=”1.0″ encoding=”UTF-8″?>

<beans xmlns=”http://www.springframework.org/schema/beans”

xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance”

xmlns:jaxws=”http://cxf.apache.org/jaxws”

xsi:schemaLocation=”

http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd

http://cxf.apache.org/jaxws http://cxf.apache.org/schemas/jaxws.xsd”>

<jaxws:client id=”orderClient” serviceClass=”demo.order.OrderProcess” address=”http://localhost:8080/orderapp/OrderProcess” >

<jaxws:dataBinding>

<bean class=”org.apache.cxf.xmlbeans.XmlBeansDataBinding”/>

</jaxws:dataBinding>

</jaxws:client>

</beans>

The following definition tells the CXF framework to use XMLBeans data binding framework.

<jaxws:dataBinding>

<bean class=”org.apache.cxf.xmlbeans.XmlBeansDataBinding”/>

</jaxws:dataBinding>

Next, we would see our code in action.  The outline is same as one defined in  Running the code section of my earlier blog – http://cxf.soaweb.co.in/index.php/2010/01/18/develop-simple-web-service-with-cxf-and-spring/

Navigate to cxfxsdfirst and type in the following command

• ant build

This would build the source code.

• ant server

This would execute the Java class – demo.order.Server and publish the OrderProcess service over address http://localhost:8080 .     You can see the WSDL for OrderProcess service by typing the URL – http://localhost:8080/OrderProcess?wsdl in the browser

• ant client

Open up a new window and type the above command. The would execute the Java class – demo.order.client.Client and invoke the OrderProcess service. You would see the order id being displayed in the console.

To know, more about how to develop SOAP and RESTful web services, get a copy of the Apache CXF Web Service Book -

Tweet This Post Delicious Digg This Post

In this blog, we we look at how to deploy CXF application on WebSphere Process Server (WPS). One of the readers had asked  me on how to deploy the sample application from Chapter 2 (Sample Apache CXF Web Service Book Chapter) in WPS, since the book covers deployment on tomcat server only. It was a good exercise for me to validate  if the sample CXF application run on other servers as I haven’t tried this before. I was able to run the application successfully with a modification to the module class loading policy . Given below are the steps required to deploy the sample CXF application (orderapp) in WPS. The version of WPS used was 7.0.

1. Build the war file (orderapp.war) as  mentioned in Chapter 2.
2. Logon to WPS Administration Console
3. Go to Applications -> Application Types – > WebSphere Enterprise applications. Click Install
4. In next screen , provide the location of orderapp.war file.Click Next
5. On the next screen, click Fast Path and click on Next
6. On the Install New Application screen, Click on Step 3 Map virtual hosts for Web modules and select the orderapp.war file to map it to default_host virtual host
7. On the Install New Application screen, Click on Step 4 Map context root for Web modules and enter  the context root as /orderapp as shown below. Click Next
8. On the Summary screen, click Finish.
9. The orderapp.war would be deployed. On the confirmation screen, click Save to save the configuration to master configuration.

Next,  you need to change the class loading policy for orderapp web module, to ensure that the CXF libraries, CXF JAX-WS and JAX-RS runtime and dependent files present in web module (all jar files in WEB-INF\lib) are loaded first , instead of WPS library to avoid any conflict. If  you don’t change the class loading policy , the application deployment would be successful but would receive the following exception when you run the application -

com.ibm.ws.webcontainer.servlet.ServletWrapper service SRVE0068E: Uncaught exception created in one of the service methods of the servlet CXFServlet in application orderapp_war. Exception created : java.lang.NoSuchMethodError: org/apache/ws/commons/schema/XmlSchema.getSchemaDocument()Lorg/w3c/dom/Document;
at org.apache.cxf.service.model.SchemaInfo.getElement(SchemaInfo.java:109)
at org.apache.cxf.wsdl11.ServiceWSDLBuilder.buildTypes(ServiceWSDLBuilder.java:267)
at org.apache.cxf.wsdl11.ServiceWSDLBuilder.build(ServiceWSDLBuilder.java:188)
at org.apache.cxf.wsdl11.ServiceWSDLBuilder.build(ServiceWSDLBuilder.java:148)

To change the class loading policy , follow these steps

1. Go to Applications -> Application Types – > WebSphere enterprise applications and select orderapp_war
2. Click on Manage modules
3. Click on orderapp.war
4. Change the class loader order to “Classes loaded with local class loader first (parent last)” as shown belo and click Apply. Save the configuration.
5. Start the orderapp_war enterprise application
6. Run the web service client as mentioned in Chapter 2

Note if you plan to use CXF JAX-WS implementation with WAS/WPS , you would not be able to leverage the WS-Specifications (like WS-Security) offered by WAS/WPS container for that application and instead need to rely on CXF WS-Specification implementation.

To know, more about how to develop SOAP and RESTful web services, get a copy of the Apache CXF Web Service Book

Tweet This Post Delicious Digg This Post

In this blog, we would provide an overview of CXF Architecture. The architecture of CXF is built upon the following components:

• Bus

• Frontend

• Messaging and Interceptors

• Service Model

• Data bindings

• Protocol bindings

• Transport

The following figure shows the overall architecture:

Bus

Bus is the backbone of the CXF architecture. The CXF bus is comprised of a Spring-based configuration file, namely, cxf.xml which is loaded upon servlet initialization through SpringBusFactory. It defines a common context for all the endpoints. It wires all the runtime infrastructure components and provides a common application context. The SpringBusFactory scans and loads the relevant configuration files in the META-INF/cxf directory placed in the classpath and accordingly builds the application context. It builds the application context from the following files:

• META-INF/cxf/cxf.xml

• META-INF/cxf/cxf-extension.xml

• META-INF/cxf/cxf-property-editors.xml

The XML file is part of the installation bundle’s core CXF library JAR. Now, we know that CXF internally uses Spring for its configuration. The following XML fragment shows the bus definition in the cxf.xml file.

<bean class=”org.apache.cxf.bus.CXFBusImpl” />

The core bus component is CXFBusImpl. The class acts more as an interceptor provider for incoming and outgoing requests to a web service endpoint. These interceptors, once defined, are available to all the endpoints in that context. The cxf.xml file also defines other infrastructure components such as BindingFactoryManager, ConduitFactoryManager, and so on. These components are made available as bus extensions. One can access these infrastructure objects using the getExtension method. These infrastructure components are registered so as to get and update various service endpoint level parameters such as service binding, transport protocol, conduits, and so on.

CXF bus architecture can be overridden, but one must apply caution when overriding the default bus behavior. Since the bus is the core component that loads the CXF runtime, many shared objects are also loaded as part of this runtime. You want to make sure that these objects are loaded when overriding the existing bus implementation.

You can extend the default bus to include your own custom components or service objects such as factory managers. You can also add interceptors to the bus bean. These interceptors defined at the bus level are available to all the endpoints. The following code shows how to create a custom bus:

SpringBeanFactory.createBus(”mycxf.xml”)

SpringBeanFactory class is used to create a bus. You can complement or overwrite the bean definitions that the original cxf.xml file would use. For the CXF to load the mycxf.xml file, it has to be in the classpath or you can use a factory method to load the file. The following code illustrates the use of interceptors at the bus level:

<bean class=”org.apache.cxf.bus.spring.SpringBusImpl”>

<property name=”outInterceptors”>

<list>

<ref bean=”myLoggingInterceptor”/>

</list>

</property>

</bean>

<bean class=”org.mycompany.com.cxf.logging. LoggingInterceptor”>

…

</bean>

The preceding bus definition adds the logging interceptor that will perform logging for all outgoing messages.

Frontend

CXF provides the concept of frontend modeling, which lets you create web services using different frontend APIs. The APIs let you create a web service using simple factory beans and JAX-WS implementation. It also lets you create dynamic web service clients. The primary frontend supported by CXF is JAX-WS. We will look at how to use the Frontend programming model in the next chapter.

JAX-WS

JAX-WS is a specification that establishes the semantics to develop, publish, and consume web services. JAX-WS simplifies web service development. JAX-WS defines Java-based APIs that ease the development and deployment of web services. The specification supports WS-Basic Profile 1.1 that addresses web service interoperability. It effectively means a web service can be invoked or consumed by a client written in any language. JAX-WS also defines standards such as JAXB and SAAJ. CXF provides support for complete JAX-WS stack.

JAXB provides data binding capabilities by providing a convenient way to map XML schema to a representation in Java code. The JAXB shields the conversion of XML schema messages in SOAP messages to Java code without the developers seeing XML and SOAP parsing. JAXB specification defines the binding between Java and XML Schema. SAAJ provides a standard way of dealing with XML attachments contained in a SOAP message.

JAX-WS also speeds up web service development by providing a library of annotations to turn Plain Old Java classes into web services and specifies a detailed mapping from a service defined in WSDL to the Java classes that will implement that service. Any complex types defined in WSDL are mapped into Java classes following the mapping defined by the JAXB specification.

As discussed earlier, two approaches for web service development exist: Code-First and Contract-First. With JAX-WS, you can perform web service development using one of the said approaches, depending on the nature of the application.

With the Code-first approach, you start by developing a Java class and interface and annotating the same as a web service. The approach is particularly useful where Java implementations are already available and you need to expose implementations as services.

You typically create a Service Endpoint Interface (SEI) that defines the service methods and the implementation class that implements the SEI methods. The consumer of a web service uses SEI to invoke the service functions. The SEI directly corresponds to a wsdl:portType element. The methods defined by SEI correspond to the wsdl:operation element.

@WebService

public interface OrderProcess {

String processOrder(Order order);

}

JAX-WS makes use of annotations to convert an SEI or a Java class to a web service. In the above example, the @WebService annotation defined above the interface declaration signifies an interface as a web service interface or Service Endpoint Interface. In the Contract-first approach, you start with the existing WSDL contract, and generate Java class to implement the service. The advantage is that you are sure about what to expose as a service since you define the appropriate WSDL Contract-first. Again the contract definitions can be made consistent with respect to data types so that it can be easily converted in Java objects without any portability issue.

WSDL contains different elements that can be directly mapped to a Java class that implements the service. For example, the wsdl:portType element is directly mapped to SEI, type elements are mapped to Java class types through the use of Java Architecture of XML Binding (JAXB), and the wsdl:service element is mapped to a Java class that is used by a consumer to access the web service.

The WSDL2Java tool can be used to generate a web service from WSDL. It has various options to generate SEI and the implementation web service class. As a developer, you need to provide the method implementation for the generated class. If the WSDL includes custom XML Schema types, then the same is converted into its equivalent Java class.

Simple frontend

Apart from JAX-WS frontend, CXF also supports what is known as ’simple frontend’. The simple frontend provides simple components or Java classes that use reflection to build and publish web services. It is simple because we do not use any annotation to create web services. In JAX-WS, we have to annotate a Java class to denote it as a web service and use tools to convert between a Java object and WSDL. The simple frontend uses factory components to create a service and the client. It does so by using Java reflection API. In Chapter 3 we will look at how to develop simple frontend web services

The following code shows a web service created using simple frontend:

// Build and publish the service

OrderProcessImpl orderProcessImpl = new OrderProcessImpl();

ServerFactoryBean svrFactory = new ServerFactoryBean();

svrFactory.setServiceClass(OrderProcess.class);

svrFactory.setAddress(”http://localhost:8080/OrderProcess”);

svrFactory.setServiceBean(orderProcessImpl);

svrFactory.create();

Messaging and Interceptors

One of the important elements of CXF architecture is the Interceptor components. Interceptors are components that intercept the messages exchanged or passed between web service clients and server components. In CXF, this is implemented through the concept of Interceptor chains. The concept of Interceptor chaining is the core functionality of CXF runtime.

The interceptors act on the messages which are sent and received from the web service and are processed in chains. Each interceptor in a chain is configurable, and the user has the ability to control its execution.

The core of the framework is the Interceptor interface. It defines two abstract methods—handleMessage and handleFault. Each of the methods takes the object of type Message as a parameter. A developer implements the handleMessage to process or act upon the message. The handleFault method is implemented to handle the error condition. Interceptors are usually processed in chains, with every interceptor in the chain performing some processing on the message in sequence, and the chain moves forward. Whenever an error condition arises, a handleFault method is invoked on each interceptor, and the chain unwinds or moves backwards.

Interceptors are often organized or grouped into phases. Interceptors providing common functionality can be grouped into one phase. Each phase performs specific message processing. Each phase is then added to the interceptor chain. The chain, therefore, is a list of ordered interceptor phases. The chain can be created for both inbound and outbound messages. A typical web service endpoint will have three interceptor chains:

• Inbound messages chain

• Outbound messages chain

• Error messages chain

There are built-in interceptors such as logging, security, and so on, and the developers can also choose to create custom interceptors.

Service model

The Service model, in a true sense, models your service. The Service model is a framework of components that represents a service in a WSDL-like model. It provides functionality to create various WSDL elements such as operations, bindings, endpoints, schema, and so on. The following figure shows the various components that form the Service model:

The components of the Service model can be used to create a service. As you can see from the above figure, the service model’s primary component is ServiceInfo which aggregates other related components that make up the complete service model. ServiceInfo is comprised of the following components that more or less represent WSDL elements:

• InterfaceInfo

• OperationInfo

• MessageInfo

• BindingInfo

• EndpointInfo

A web service is usually created using one of the frontends offered by CXF. It can be either constructed from a Java class or from a WSDL. CXF frontends internally use the service model to create web services. For example, by using a simple frontend, we can create, publish, and consume web services through factory components such as ServerFactoryBean and ClientProxyFactoryBean. These factory classes internally use the service model of CXF.

Data binding

Data binding is the key for any web service development. Data binding means mapping between Java objects and XML elements. As we know, with web service, messages are exchanged as XML artifacts. So there has to be some way to convert these XML into Java objects and vice versa for the application to process as service and client. Data binding components perform this mapping for you. CXF supports two types of data binding components—JAXB and Aegis. CXF uses JAXB as the default data binding component. As a developer, you have the choice of specifying the binding discipline through a configuration file or API. If no binding is specified, then JAXB is taken as a default binding discipline. The latest version of CXF uses JAXB 2.1. JAXB uses annotations to define the mapping between Java objects and XML. The following code illustrates the use of JAXB annotations:

@XmlRootElement(name=”processOrder”, namespace=” http://localhost/ orderprocess”)

@XmlAccessorType(XmlAccessType.FIELD)

@XmlType(name=”processOrder”, namespace= ” http://localhost/orderprocess”)

public class OrderProcess {

@XmlElement(name=”arg0″, namespace=”")

private order.Order arg0;

//Gettter and Setter

….

}

As shown in the previous code, the @Xml specific annotations represents the JAXB metadata that is used by JAXB to map Java classes to XML schema constructs. For example, the @XmlType annotation specifies that the OrderProcess class will be mapped to complex XSD element type ‘processOrder’ that contains an element ‘arg0′ of type ‘Order’ bean.

CXF also supports the Aegis data binding component to map between Java objects and XML. Aegis allows developers to gain control of data binding through its flexible mapping system. You do not have to rely on annotations to devise the mapping. Your Java code is clean and simple POJO.

Aegis also supports some annotations that can be used to devise binding. Some of the annotations that can be used with Aegis are:

• XmlAttribute

• XmlElement

• XmlParamType

• XmlReturnType

• XmlType

In Aegis, you define the data mapping in a file called <MyJavaObject>.aegis.xml, where MyJavaObject is the object that you are trying to map with XML. Aegis reads this XML to perform the necessary binding. Aegis also uses reflection to derive the mapping between Java object and XML. The following code fragment shows the sample Aegis mapping file:

<?xml version=”1.0″ encoding=”UTF-8″?>

<mappings>

<mapping name=”HelloWorld”>

<method name=”sayHi”>

<parameter index=”0″ mappedName= “greeting” nillable=’false’ />

</method>

</mapping>

</mappings>

The above XML fragment states that a string parameter of a method named sayHi of the bean HelloWorld should be mapped to a name as greeting.

You can configure your web service to use Aegis data binding as follows:

<jaxws:endpoint implementor=”demo.order. OrderProcessImpl” address=”/OrderProcess” >

<jaxws:dataBinding>

<bean class=”org.apache.cxf.aegis.databinding.AegisDatabinding” />

</jaxws:dataBinding>

</jaxws:endpoint>

Protocol binding

Bindings bind the web service’s messages with the protocol-specific format. The messages, in web service terminology, are nothing but an operation with input and output parameters. The message defined in the web service component is called a logical message. The logical message used by a service component is mapped or bound to a physical data format used by endpoints in the physical world.

Bindings are directly related to port types in a WSDL artifact. Port types define operations and input and output parameters which are abstract in nature. Port types define the logical message, whereas binding translates this logical message into actual payload data defined by the underlying protocol. The following WSDL portion shows the sample binding details:

<wsdl:binding name=”OrderProcessImplServiceSoapBinding” type=”tns:OrderProcess”>

<soap:binding style=”document” transport= “http://schemas.xmlsoap.org/soap/http” />

<wsdl:operation>

<soap:operation soapAction=”" style=”document” />

<wsdl:input>

<soap:body use=”literal” />

</wsdl:input>

<wsdl:output name=”processOrderResponse”>

<soap:body use=”literal” />

</wsdl:output>

</wsdl:operation>

</wsdl:binding>

As you can see from the above sample binding fragment, the binding is defined using the <binding> element. This element has two attributes, namely, name and type. The name attribute identifies the binding, and the type attribute maps it with the port type. The name attribute of the binding element is used to associate with the endpoint. The child elements of the <binding> parent element define the actual mapping of the messages with the protocol format. In the previous case, the communication protocol used is SOAP 1.1.

CXF supports the following binding protocols:

• SOAP 1.1

• SOAP 1.2

• CORBA

• Pure XML

Transports

Transport defines the high-level routing protocol to transmit the messages over the wire. Transport protocols are associated with the endpoints. One endpoint can communicate with another using a specific transport protocol. Transport details are nothing but networking details. Service endpoints are a physical representation of a service interface. Endpoints are composed of binding and networking details. In a WSDL artifact, transport details are specified as part of the <port> element. The port element is a child of the service element. The WSDL portion following shows the sample transport details:

<wsdl:service name=”OrderProcessImplService”>

<wsdl:port binding=”tns:OrderProcessImplServiceSoapBinding” name=”OrderProcessImplPort”>

<soap:address location=”http://localhost:8080/orderapp/ OrderProcess” />

</wsdl:port>

</wsdl:service>

As you see from the above XML fragment, transport details are specified as part of the service element. The service element has one child element as port element. The port element maps to binding as defined by the binding element and provides details of the transport. The previous example shows SOAP as binding protocol and HTTP as a transport protocol. In Chapter 4, the various transport protocols are explained in the context of web services development.

CXF supports the following transports for its endpoints:

• HTTP

• CORBA

• JMS

• Local

Summary

In this blog , we looked at the various components of the CXF Architecture. Each of these concepts , is explained in context of web service development through examples in Apache CXF Web Service CXF Book.

To know, more about how to develop SOAP and RESTful web services, get a copy of the Apache CXF Web Service Book -

Tweet This Post Delicious Digg This Post

In this blog we will look at how to develop a simple web service using CXF and Spring-based configurations. We will take a use case of a Order Processing Application and than develop a web service and client for this use case.

The Order Processing Application

The objective of the Order Processing Application is to process a customer order. The order process functionality will generate the customer order, thereby making the order valid and approved. A typical scenario will be a customer making an order request to buy a particular item. The purchase department will receive the order request from the customer and prepare a formal purchase order. The purchase order will hold the details of the customer, the name of the item to be purchased, the quantity, and the price. Once the order is prepared, it will be sent to the Order Processing department for the necessary approval. If the order is valid and approved, then the department will generate the unique order ID and send it back to the Purchase department. The Purchase department will communicate the order ID back to the customer.

For simplicity, we will look at the following use cases:

- Prepare an order

- Place the order

The client application will prepare an order and send it to the server application through a business method call. The server application will contain a web service that will process the order and generate a unique order ID. The generation of the unique order ID will signify order approval.

In real world applications a unique order ID is always accompanied by the date the order was approved. However, in this example we chose to keep it simple by only generating order ID.

Developing a service

Let’s look specifically at how to create an Order Processing Web Service and then register it as a Spring bean using a JAX-WS frontend.

The Sun-based JAX-WS specification can be found at the following URL: http://jcp.org/aboutJava/communityprocess/final/jsr224/index.html

JAX-WS frontend offers two ways of developing a web service—Code-first and Contract-first. We will use the Code-first approach, that is, we will first create a Java class and convert this into a web service component. The first set of tasks will be to create server-side components.

In web service terminology, Code-first is termed as the Bottoms Up approach, and Contract-first is referred to as the Top Down approach.

To achieve this, we typically perform the following steps:

• Create a Service Endpoint Interface (SEI) and define a business method to be used with the web service.
• Create the implementation class and annotate it as a web service.
• Create beans.xml and define the service class as a Spring bean using a JAX-WS frontend.

Creating a Service Endpoint Interface (SEI)

Let’s first create the SEI for our Order Processing Application. We will name our SEI OrderProcess. The following code illustrates the OrderProcess SEI:

package demo.order;
import javax.jws.WebService;
@WebService
public interface OrderProcess {
  @WebMethod
  String processOrder(Order order);
}

As you can see from the preceding code, we created a Service Endpoint Interface named OrderProcess. The SEI is just like any other Java interface. It defines an abstract business method processOrder. The method takes an Order bean as a parameter and returns an order ID String value. The goal of the processOrder method is to process the order placed by the customer and return the unique order ID.

One significant thing to observe is the @WebService annotation. The annotation is placed right above the interface definition. It signifies that this interface is not an ordinary interface but a web service interface. This interface is known as Service Endpoint Interface and will have a business method exposed as a service method to be invoked by the client.

The @WebService annotation is part of the JAX-WS annotation library. JAX-WS provides a library of annotations to turn Plain Old Java classes into web services and specifies detailed mapping from a service defined in WSDL to the Java classes that will implement that service. The javax.jws.WebService annotation also comes with attributes that completely define a web service. For the moment we will ignore these attributes and proceed with our development.

The javax.jws.@WebMethod annotation is optional and is used for customizing the web service operation. The @WebMethod annotation provides the operation name and the action elements which are used to customize the name attribute of the operation and the SOAP action element in the WSDL document.

The following code shows the Order class:

package demo.order;
import javax.xml.bind.annotation.XmlRootElement;
@XmlRootElement(name = "Order")
public class Order {
  private String customerID;
  private String itemID;
  private int qty;
  private double price;
  // Contructor
  public Order() {
  }
  public String getCustomerID() {
    return customerID;
  }
  public void setCustomerID(String customerID) {
    this.customerID = customerID;
  }
  public String getItemID() {
    return itemID;
  }
  public void setItemID(String itemID) {
    this.itemID = itemID;
  }
  public int getQty() {
    return qty;
  }
  public void setQty(int qty) {
    this.qty = qty;
  }
  public double getPrice() {
    return price;
  }
  public void setPrice(double price) {
    this.price = price;
  }
}

As you can see, we have added an @XmlRootElement annotation to the Order class. The @XmlRootElement is part of the Java Architecture for XML Binding (JAXB) annotation library. JAXB provides data binding capabilities by providing a convenient way to map XML schema to a representation in Java code. The JAXB shields the conversion of XML schema messages in SOAP messages to Java code without having the developers know about XML and SOAP parsing. CXF uses JAXB as the default data binding component.

The @XmlRootElement annotations associated with Order class map the Order class to the XML root element. The attributes contained within the Order object by default are mapped to @XmlElement. The @XmlElement annotations are used to define elements within the XML. The @XmlRootElement and @XmlElement annotations allow you to customize the namespace and name of the XML element. If no customizations are provided, then the JAXB runtime by default would use the same name of attribute for the XML element. CXF handles this mapping of Java objects to XML using the JAXB Binding.

Developing a service implementation class

We will now develop the implementation class that will realize our OrderProcess SEI. We will name this implementation class OrderProcessImpl. The following code illustrates the service implementation class OrderProcessImpl:

@WebService
public class OrderProcessImpl implements OrderProcess {
  public String processOrder(Order order) {
    String orderID = validate(order);
      return orderID;
  }
/**
 * Validates the order and returns the order ID
**/
  private String validate(Order order) {
    String custID = order.getCustomerID();
    String itemID = order.getItemID();
    int qty = order.getQty();
    double price = order.getPrice();
    if (custID != null && itemID != null && !custID.equals("")
                       && !itemID.equals("") && qty > 0
                       && price > 0.0) {
        return "ORD1234";
    }
    return null;
  }
}

As we can see from the preceding code, our implementation class OrderProcessImpl is pretty straightforward. It also has @WebService annotation defined above the class declaration. The class OrderProcessImpl implements OrderProcess SEI. The class implements the processOrder method. The processOrder method checks for the validity of the order by invoking the validate method. The validate method checks whether the Order bean has all the relevant properties valid and not null.

Next we will look at how to publish the OrderProcess JAX-WS web service using Spring configuration.

Spring-based server bean

What makes CXF the obvious choice as a web service framework is its use of Spring-based configuration files to publish web service endpoints. It is the use of such configuration files that makes the development of web service convenient and easy with CXF.

Spring provides a lightweight container which works on the concept of Inversion of Control (IoC) or Dependency Injection (DI) architecture; it does so through the implementation of a configuration file that defines Java beans and its dependencies. By using Spring you can abstract and wire all the class dependencies in a single configuration file. The configuration file is often referred to as an Application Context or Bean Context file.

We will create a server side Spring-based configuration file and name it as beans.xml. The following code illustrates the beans.xml configuration file:

<beans xmlns="http://www.springframework.org/schema/beans"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:jaxws="http://cxf.apache.org/jaxws"
  xsi:schemaLocation="
http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans.xsd
http://cxf.apache.org/jaxws http://cxf.apache.org/schemas/jaxws.xsd">
  <import resource="classpath:META-INF/cxf/cxf.xml" />
  <import resource="classpath:META-INF/cxf/cxf-extension-    soap.xml" />
  <import resource="classpath:META-INF/cxf/cxf-servlet.xml" />
  <jaxws:endpoint
    id="orderProcess"
    implementor="demo.order.OrderProcessImpl"
    address="/OrderProcess" />
</beans>

Let’s examine the previous code and understand what it really means. It first defines the necessary namespaces. It then defines a series of <import> statements. It imports cxf.xml, cxf-extension-soap.xml, and cxf-servlet.xml. These files are Springbased configuration files that define core components of CXF. They are used to kick start CXF runtime and load the necessary infrastructure objects such as WSDL manager, conduit manager, destination factory manager, and so on.

The <jaxws:endpoint> element in the beans.xml file specifies the OrderProcess web service as a JAX-WS  endpoint. The element is defined with the following three attributes:

• id—specifies a unique identifier for a bean. In this case, jaxws:endpoint is a bean, and the id name is orderProcess.
• implementor— specifies the actual web service implementation class. In this case, our implementor class is OrderProcessImpl.
• address— specifies the URL address where the endpoint is to be published. The URL address must to be relative to the web context. For our example, the endpoint will be published using the relative path /OrderProcess.

The <jaxws:endpoint> element signifies that the CXF internally uses JAX-WS frontend to publish the web service. This element definition provides a short and convenient way to publish a web service. A developer need not have to write any Java class to publish a web service.

Developing a client

In the previous section we discussed and illustrated how to develop and publish a web service. We now have the server-side code that publishes our OrderProcess web service. The next set of tasks will be to create the client-side code that will consume or invoke our OrderProcess web service. To achieve this, we will perform the following steps:

• Develop the client-beans.xml to define the client factory class as a Spring bean using JAX-WS frontend
• Develop a client Java application to invoke the web service

Developing a Spring-based client bean

We will create a client-side Spring-based configuration file and name it as client-beans.xml. The following code illustrates the client-beans.xml configuration file:

<beans xmlns="http://www.springframework.org/schema/beans"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:jaxws="http://cxf.apache.org/jaxws"
  xsi:schemaLocation="
http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans.xsd
http://cxf.apache.org/jaxws http://cxf.apache.org/schemas/jaxws.xsd">
<jaxws:client id="orderClient" serviceClass=
                 "demo.order.OrderProcess" address=
                 "http://localhost:8080/orderapp/OrderProcess" />
</beans>

The <jaxws:client> element in the client-beans.xml file specifies the client bean using JAX-WS frontend. The element is defined with the following three attributes:

• id—specifies a unique identifier for a bean. In this case, jaxws:client is a bean and the id name is orderClient. The bean will represent an SEI.
• serviceClass—specifies the web service SEI. In this case our SEI class is OrderProcess
• address—specifies the URL address where the endpoint is published. In this case the endpoint is published at the URL address: http://localhost:8080/orderapp/OrderProcess

<jaxws:client> signifies the client bean that represents an OrderProcess SEI. The client application will make use of this SEI to invoke the web service. Again, CXF internally uses JAX-WS frontend to define this client-side component.

Developing web service client code

We will now create a standalone Java class to invoke our OrderProcess web service. The following code illustrates the client invocation of a web service method:

public final class Client {
  public Client() {
  }
  public static void main(String args[]) throws Exception {
    // START SNIPPET: client
    ClassPathXmlApplicationContext context
        = new ClassPathXmlApplicationContext(new String[]
               {"demo/order/client/client-beans.xml"});
    OrderProcess client = (OrderProcess) context.
                          getBean("orderClient");
  // Populate the Order bean
  Order order = new Order();
  order.setCustomerID("C001");
  order.setItemID("I001");
  order.setQty(100);
  order.setPrice(200.00);
    String orderID = client.processOrder(order);
    String message = (orderID == null) ?
                     "Order not approved" : "Order approved;
                      order ID is " + orderID;
    System.out.println(message);
    System.exit(0);

As you can see from the above code, we have the main method that first loads the client-beans.xml configuration file. It uses the Spring application context component ClassPathXmlApplicationContext to load the configuration file. The context component’s getBean method is passed the bean ID orderClient. This method will return the OrderProcess SEIcomponent. Using the SEI, we then invoke the web service method processOrder. One thing to observe here is that the client always uses the interface to invoke a web service method.

We have now finished developing server and client side components. To summarize, we created the OrderProcess service endpoint interface and the implementation class. We then created server and client-side Spring-based configuration files and finally we created the client application. The relevant components are developed and we are all set to run or execute our code. But before we do that, you will have to create one final component that will integrate Spring and CXF.

We need to wire Spring and CXF through web.xml. The following code illustrates the web.xml file:

<web-app>
  <context-param>
    <param-name>contextConfigLocation</param-name>
    <param-value>WEB-INF/beans.xml</param-value>
  </context-param>
  <listener>
    <listener-class>
      org.springframework.web.context.ContextLoaderListener
    </listener-class>
  </listener>
  <servlet>
    <servlet-name>CXFServlet</servlet-name>
    <display-name>CXF Servlet</display-name>
    <servlet-class>
      org.apache.cxf.transport.servlet.CXFServlet
    </servlet-class>
    <load-on-startup>1</load-on-startup>
  </servlet>
  <servlet-mapping>
    <servlet-name>CXFServlet</servlet-name>
    <url-pattern>/*</url-pattern>
  </servlet-mapping>
</web-app>

Let’s go through the above piece of code. The web.xml, as we know, is the web application configuration file that defines a servlet and its properties. The file defines CXFServlet, which acts as a front runner component that initiates the CXF environment. It defines the listener class ContextLoaderListener, which is responsible for loading the server-side configuration file beans.xml. So upon the web server startup, the order process web service endpoint will be registered and published.

Running the program

Before running the program, we will organize the code so far developed in the appropriate folder structure. You can create the folder structure, as shown in the following screenshot, and put the components in the respective sub folders. Following shows the code layout  of the project

The developed code will go into the following:

• The Java code will go into the respective package folders
• The beans.xml and web.xml will go into the webapp\WEB-INF folder (the folder name – WEB-INF should be in caps)
• The client-beans.xml file will go into the demoorderclient folder

Once the code is organized, we will go about building and deploying it in the Tomcat server. It will typically involve three steps:

• Building the code
• Deploying the code
• Executing the code

Building the code

Building the code means compiling the source Java code. We will use the ANT tool to do this. The ANT file is provided in Chapter2orderapp folder. The following code illustrates the sample build.xml build script:

<?xml version="1.0" encoding="UTF-8"?>
<project name="CXF Chapter2 example" default="build" basedir=".">
  <import file="common_build.xml"/>
    <target name="client" description=
                 "run demo client" depends="build">
        <property name="param" value=""/>
        <cxfrun classname="demo.order.client.Client" />
    </target>
    <target name="server" description=
                 "run demo server" depends="build">
        <cxfrun classname="demo.spring.servlet.Server"/>
    </target>
    <property name="cxf.war.file.name" value="orderapp"/>
      <target name="war" depends="build">
    <cxfwar filename="${cxf.war.file.name}.war" webxml=
                     "webapp/WEB-INF/web.xml" />
    </target>
</project>

Alongside build.xml, you will also find common_build.xml in the same folder. The common_buid.xml refers to CATALINA_HOME environment variable to find location of tomcat installation. Please set CATALINA_HOME environment to point to tomcat installation installation. Open the command prompt window, go to C:/orderapp folder and run the ant command. It will build the code and put the class files under the newly created build folder. The following figure shows the output generated upon running the ant command.

Deploying the code

Having built the code, we will deploy it. Deployment effectively means building and moving the code archive to the server deploy path. We will be using the Tomcat web container to deploy and run the application. To deploy our built code, navigate to project root folder, and enter the following command:

ant deploy

This will build the WAR file and put it under the Tomcat server webapp path. For example, if you have installed the Tomcat under the root folder, then the WAR will be deployed to /Tomcat/webapp folder.

Executing the code

Following code deployment, we are all set to run the Order Process Application. You will execute the Java client program Client.java to invoke the Order Process web service. The program will invoke the processOrder method that will generate the order ID if the specified order is approved. Before running the client program, we need to start the Tomcat web server. There are several ways of starting the Tomcat server depending on the Tomcat version that is installed. Once the server is started, you need to run the client program by giving the following command at the command prompt window:

ant client

Upon executing this command, it will generate the following output:

Thus we have successfully executed the order processing web service.

Summary

In this blog we provided an overview of a sample Order Processing Application and saw how to develop a web service with Spring-based configuration. We also saw how to build, deploy, and execute a web service using ANT and Tomcat.

To know, more about how to develop SOAP and RESTful web services, get a copy of the Apache CXF Web Service Book -

Tweet This Post Delicious Digg This Post

Invoking a web service using the Java client
A web service exposes a set of operations over the network, typically via HTTP protocol. In order to invoke the web services, the web service client needs to know the following information:

• What operations are exposed by the web service
• The input and output message formats required to access the service operations
• What protocol, for instance HTTP or JMS, to use to invoke the web service
• The URL location of the web service

All of the above information is contained in the standard XML descriptor called WSDL (Web Service Description Language). The WSDL file provides a format contract between the web service provider and the web service client. The web service client typically inspects the WSDL file to determine what operations are exposed by the web service, what parameters need to be supplied to invoke the web service operation and to formulate the request, and invokes the web service over the supported protocol. Similarly, the web service clients need to write the code to inspect the response and convert it into the required format. CXF hides the complexity of creating web service clients by providing the WSDL to Java command line tool, which takes a WSDL file and generates client code. The client code can be used by developers with no changes to invoke the web services.

In this blog, we will look at how to generate client code from an existing WSDL. We will invoke a  .NET service located over the Web, using the Java client generated by the WSDL to Java tool. This shows the true power of web service interoperability, where applications implemented in different languages can communicate with each other.

The process of generating web service clients does not differ for web services implemented in different languages, as you generate web service clients from WSDL and XML Schema definitions.

Before invoking the .NET service, let’s examine the WSDL to determine which operations are exposed by the web service.

Analyzing the service WSDL definition

We will invoke a publicly available .NET web service located at http://www.ignyte.com/webservices/ignyte.whatsshowing.webservice/moviefunctions.asmx?wsdl. This web service retrieves US Theaters and Movie Showtime information based on a valid US zip code and a radius supplied by the web service clients.

The .NET web service is a WS-I compliant web service.

The Web Services Interoperability Organization (WS-I), an open industry organization, was formed to promote web services interoperability across platforms, operating systems, and programming languages. One concrete product of WS-I is the Basic Profile. Basic Profile narrows the scope of specifications to a reasonable set of rules and guidelines that are best suited to help interoperability.

If you type in the given URL in the browser, you see the WSDL definition, as shown in the following screenshot:

Let’s analyze the important sections of the WSDL file to get an understanding of which operations are exposed by the movie information web service and which message formats are required to invoke the web service.

The web service provides two operations, GetTheatersAndMovies and GetUpcomingMovies, as shown in listing below. For this tutorial, we will focus on how to invoke the GetTheatersAndMovies operation. The GetTheatersAndMovies takes the GetTheatersAndMoviesSoapIn message as the input and provides GetTheatersAndMoviesSoapOut as the output message.

<wsdl:portType name=”MovieInformationSoap”>
<wsdl:operation name=”GetTheatersAndMovies”>
<wsdl:documentation xmlns:wsdl=”http://schemas.xmlsoap.org/
wsdl/”>This method will retrieve a list of all theaters and the movies
playing today.</wsdl:documentation>
<wsdl:input message=”tns:GetTheatersAndMoviesSoapIn” />
<wsdl:output message=”tns:GetTheatersAndMoviesSoapOut” />
</wsdl:operation>
</wsdl:portType>

The web service client invokes the GetTheatersAndMovies operation to get theater and movie information. The input to the GetTheatersAndMovies operation is the GetTheatersAndMoviesSoapIn XML message.

The GetTheatersAndMoviesSoapIn message references the GetTheatersAndMovies element, which defines the actual XML schema definition for the input message. The following is the code listing of GetTheatersAndMovies schema definition:

<s:element name="GetTheatersAndMovies">
  <s:complexType>
    <s:sequence>
      <s:element minOccurs="0" maxOccurs="1"
      name="zipCode" type="s:string" />
      <s:element minOccurs="1" maxOccurs="1"
      name="radius" type="s:int" />
    </s:sequence>
  </s:complexType>
</s:element>

The GetTheatersAndMovies contains an element zipCode of type String and radius which is of type integer that needs to be passed as input by the web services client as an input to the GetTheatersAndMoviesSoapIn operation. The minOccurs and maxOccurs attribute associated with zipCode and radius is used to specify the minimum and maximum occurrence of the element inside a GetTheatersAndMovies element. The zipCode and radius element can appear only once inside a GetTheatersAndMovies element as it specifies the value of maxOccurs=”1″. If maxOccurs has the value Unbounded, then it implies that multiple occurrences of the element can exist.Similarly, the GetTheatersAndMoviesResponse specifies the output message format for the response. The following is the code listing of the GetTheatersAndMoviesResponse schema definition. We will break down the schema for better understanding:

• The GetTheatersAndMoviesResponse schema
  The following shows the definition of GetTheatersAndMoviesResponse. The GetTheatersAndMoviesResponse contains an element ArrayOfTheater

<s:element name=”GetTheatersAndMoviesResponse”>
<s:complexType>
<s:sequence>
<s:element minOccurs=”0″ maxOccurs=”1″
name=”GetTheatersAndMoviesResult” type=
“tns:ArrayOfTheater” />
</s:sequence>
</s:complexType>
</s:element>

• The ArrayOfTheater Schema
  The following shows the definition of ArrayOfTheater schema.
  The ArrayOfTheater is an array which consists of Theatre elements.
  The maxOccurs=”unbounded” specifies that multiple occurrences of Theatre elements can exist in an ArrayOfTheater element.

<s:complexType name=”ArrayOfTheater”>
<s:sequence>
<s:element minOccurs=”0″ maxOccurs=
“unbounded” name=”Theater” nillable=
“true” type=”tns:Theater” />
</s:sequence>
</s:complexType>

The Theater elements consist of the Name and Address elements of type String, which specifies the name and address of the Theater and an array of ArrayOfMovie element.

• The ArrayOfMovie Schema
  The following is the ArrayOfMovie definition. The ArrayOfMovie is an array which consists of Movie elements. The maxOccurs=”unbounded” specifies that multiple occurrences of Movie elements can exist in an ArrayOfMovie element.

<s:complexType name="ArrayOfMovie">
  <s:sequence>
    <s:element minOccurs="0" maxOccurs=
    "unbounded" name="Movie" nillable=
    "true" type="tns:Movie" />
  </s:sequence>
</s:complexType>

Based on the Schema definitions above, the CXF WSDL2Java tool generates Java code that maps to these XML elements. The web service clients communicate with the web services using these generated Java objects to invoke a Java method representing the GetTheatersAndMoviesoperation and leave the SOAP XML to Java conversion and low level implementation details with the CXF framework.The SOAP address in the WSDL file specifies the location of the service, which is http://www.ignyte.com/webservices/ignyte.whatsshowing.webservice/moviefunctions.asmx, as shown in the listing below:

<wsdl:service name=”MovieInformation”>
<wsdl:port name=”MovieInformationSoap” binding=
“tns:MovieInformationSoap”>
<soap:address location=”http://www.ignyte.com/webservices/
ignyte.whatsshowing.webservice/moviefunctions.asmx” />
</wsdl:port>
<wsdl:port name=”MovieInformationSoap12″ binding=
“tns:MovieInformationSoap12″>
<soap12:address location=”http://www.ignyte.com/webservices/
ignyte.whatsshowing.webservice/moviefunctions.asmx” />
</wsdl:port>
</wsdl:service>

We will now look at how to generate the web service client code for the Movie information web service.

Building and running the Java web service clients

The source code and build files for the example are available in the wsdl2Java folder of the downloaded source code. We will follow the steps below to build and execute the web service client:

• Generate the web service clients
• Analyze the generated artifacts
• Modify the generated code
• Build the web service client
• Run the web service client

Generate the web service clients

We will use the Ant build script (build.xml) for generating the web service client code and building the project code as shown below. Navigate to the wsdl2java folder of the downloaded source code. Execute the cxfWSDLToJava target by navigating to the wsdl2java folder and running the following command:

ant cxfWSDLToJava

The following figure shows the output generated upon running the ant command:

The cxfWSDLToJava ant target calls the CXF tool apache.cxf.tools.wsdlto.WSDLToJava to generate web service client code based on the URL http://www.ignyte.com/webservices/ignyte.whatsshowing.webservice/moviefunctions.asmx?wsdl

The following is a code snippet of ant target cxfWSDLToJava in build.xml:

<target name="cxfWSDLToJava">
  <java classname="org.apache.cxf.tools.wsdlto.WSDLToJava"
  fork="true">
    <arg value="-client"/>
    <arg value="-d"/>
    <arg value="src"/>
    <arg value="http://www.ignyte.com/webservices/ignyte.
    whatsshowing.webservice/moviefunctions.asmx?wsdl"/>
    <classpath>
      <path refid="cxf.classpath"/>
    </classpath>
  </java>
</target>

WSDLToJava generates JAX-WS compliant Java code for the services defined in the WSDL document. Based on the parameters passed, it can generate the starting point of the code for developing the web service client and service. The client option, as shown in above snippet, generates the client code. The know about more about the options supported by the WSDLToJava tool , refer to CXF website—http://cwiki.apache.org/CXF20DOC/wsdl-to-java.html

After executing the command, the generated code is created in the wsdl2java/src folder.

Analyzing the JAX-WS and client generated artifacts

The following artifacts are generated in the wsdl2Java/src/com/ignite/whatsshowing folder:

• JAXB classes— these are generated by reading the schema definitions defined in the Movie information WSDL. The classes generated for the Movie information web service are ArrayOfMovie, ArrayOfTheater, ArrayOfUpcomingMovie, Movie, Theater UpcomingMovie, and ObjectFactory.
• The RequestWrapper and ResponseWrapper classes—as the Movie information web service uses the document-literal web service style, the Request and Response wrapper objects are generated for input and output message formats for the operations GetTheatersAndMovies and GetUpcomingMovies. The Request and Response Wrapper objects wrap the input and output for document-literal wrapped style web services. The GetTheatersAndMovies (Request Wrapper) and GetTheatersAndMoviesResponse (Response Wrapper) are generated for the getTheatersAndMovies operation.
• The next code snippet shows the generated GetTheatersAndMovies.java. As you can see below, the class has JAXB annotations that are defined to map Java to an XML element. The @XmlRootElement defines the root element of the input request which has the name GetTheatersAndMovies. The attributes zipCode and radius are contained in the GetTheatersAndMovies XML element. The annotations are used to map Java to an XML request.

@XmlAccessorType(XmlAccessType.FIELD)
@XmlType(name = “”, propOrder = {
“month”,
“year”
})
@XmlRootElement(name = “GetTheatersAndMovies”)
public class GetTheatersAndMovies {
protected String zipCode;
protected int radius;
public String getZipCode() {
return zipCode;
}
public void setZipCode(String value) {
this.zipCode = value;
}
public int getRadius() {
return radius;
}
public void setRadius(int value) {
this.radius = value;
}
}

• Service Interface: This class contains the service interface for the Movie information web service. The service interface generated for Movie information web service is MovieInformationSoap.java
• Service class—this is the class that web service clients will use to make requests to the web service. The service class generated for the Movie information web service is MovieInformation.java. The service class contains the @WebServiceClient annotation and lookup methods to retrieve the Service Interface.
• Client code— the standalone web service client code that provides a starting point for the client code, which calls various operations of the web service. You need to modify the client code to provide the input for each of the operations being invoked. The client code generated for the Movie information web service is MovieInformationSoap_MovieInformationSoap12_Client.java and MovieInformationSoap_MovieInformationSoap_Client.java. Two client codes are generated as there are two ports defined for the Movie information service, MovieInformationSoap and MovieInformationSoap12. You can use any of the client code. There are two port types provided to support SOAP 1.1 and SOAP 1.2 request.

Modifying the generated client

We will now modify the generated client MovieInformationSoap_MovieInformationSoap12_Client.java to provide input to the getTheatersAndMovies operations method. Open the MovieInformationSoap_MovieInformationSoap12_Client.java in any text editor, and modify the generated code, as highlighted in bold.

package com.ignyte.whatsshowing;
import java.io.File;
//Other imports…..
import java.util.List;
public final class MovieInformationSoap_MovieInformationSoap12_Client
{
  public static void main(String args[]) throws Exception {
    //Refer to generated code for compete listing
    System.out.println("Invoking getTheatersAndMovies...");
    java.lang.String _getTheatersAndMovies_zipCode = "78750";
    int _getTheatersAndMovies_radius = 2;
com.ignyte.whatsshowing.ArrayOfTheater _getTheatersAndMovies__
return = port.getTheatersAndMovies(_getTheatersAndMovies_zipCode, _
getTheatersAndMovies_radius);
System.out.println("getTheatersAndMovies.result=" + _
getTheatersAndMovies__return);
  System.out.println("Theater List is : "
    + _getTheatersAndMovies__return.getTheater().size());
List<Theater> theatreList = _getTheatersAndMovies__return.
getTheater();
  for (int i = 0; i < theatreList.size(); i++) {
    System.out.println("Theatre Name : " +
    theatreList.get(i).getName());
    List<Movie> movieList =
    theatreList.get(i).getMovies().getMovie();
      for (int j = 0; j < movieList.size(); j++) {
    System.out.println("Movie Name : " +
          movieList.get(j).getName());
    System.out.println("Movie Rating : " +
    movieList.get(j).getRating());
    }
    System.out.println("End of Movies for Theatre :"
    + theatreList.get(i).getName());
  }
//Remaining code block

As you can see in the previous code, we specify the zip code as 78750 and radius as 2. Next, the operation getTheatersAndMovies(_getTheatersAndMovies_zipCode, _getTheatersAndMovies_radius) is invoked. The operation returns the com.ignyte.whatsshowing.ArrayOfTheater response. We then get the list of theatres from com.ignyte.whatsshowing.ArrayOfTheater object by calling the _getTheatersAndMovies__return.getTheater() method. Next we iterate through the theatreList and print the name, theatreList.get(i).getName(). For each theatre, we retrieve the list of movies running in that theatre, by calling theatreList.get(i).getMovies().getMovie(). We then iterate through the set of movies and print the name, movieList.get(j).getName() and rating, movieList.get(j).getRating() for each movie.

Building the client

To build the client, navigate to the wsld2java folder, and run the following command to build the code:

ant build

The following screenshot shows the output generated on running the ant command:

Running the client

To run the client, navigate to the wsld2java folder, and run the following command to build the code:

ant runClient

This command calls the target runClient in build.xml, and executes the MovieInformationSoap_MovieInformationSoap_Client class.

The following output will be printed on the console. Look for the Theater List is system output message to determine how many theatres are retrieved for that area code. For each theatre you see the movie information being printed on the console. Look for the Movie Name and Movie Rating system output message, as shown in the next screenshot. Note that this

We have thus successfully invoked the Movie information web service.

Summary

In this blog , we looked at how to:

• Utilize CXF tools for web services development
• Create Java web service clients from WSDL and invoke real world web services

To know, more about how to develop SOAP and RESTful web services, get a copy of the Apache CXF Web Service Book -

Tweet This Post Delicious Digg This Post

Tweet This Post Delicious Digg This Post

Tweet This Post Delicious Digg This Post

Chapter 1: Getting Familiar with CXF revisits web service concepts and provides an introduction to CXF framework and its usage, and prepares the CXF environment for the following chapters.

By the end of this chapter the reader will be able to understand the core concepts of CXF.

Chapter 2: Developing a Web Service with CXF focuses on getting the reader quickly started with the CXF framework by developing a simple web service and running it under the Tomcat container. Chapter 2 would also provide details on CXF architecture.

By the end of this chapter the reader will be able to develop a simple web service using CXF.

Chapter 3: Working with CXF Frontends illustrates the use of different frontends, like JAX-WS and CXF simple fronted API, and shows how to apply code-first and contract first development approaches for developing web services. We will look at how to create dynamic web service clients, the use of web service context, and how to work directly with XML messages using CXF Provider and Dispatch implementation.

By the end of this chapter the reader will be able to apply different frontends to develop a web service.

Chapter 4: Learning about Service Transports explains basic transport protocols for a service and shows you how to configure HTTP, HTTP(s), JMS, and Local protocol for web services communication. You will get introduced to the concept of HTTP conduit, which enables the client program to apply policies or properties to HTTP and HTTPs protocols, and how to generate a crypto key and a key store for HTTPs based service communication. You will learn how to use JMS protocol for web services communication and how to facilitate web services message exchange using CXF Local service transport.

By the end of this chapter the reader will be able develop services with different transports

Chapter 5: Implementing Advanced Features will explain advanced concepts using CXF Features, Interceptors, and Invokers, and how to integrate these concepts in existing applications.

By the end of this chapter the reader will be able develop services with features like Interceptors and Invokers

Chapter 6: Developing RESTful Services with CXF explains the concept of REST technology and JAX-RS specifications, how CXF realizes the JAX-RS specification, and demonstrates additional features for developing enterprise RESTful services. We will look at how to design, develop, and unit test the RESTful Service by taking a real world example using CXF JAX-RS implementation.

By the end of this chapter the reader will be able to design, develop, and unit test the RESTful service

Chapter 7: Deploying RESTful Services with CXF will explain how to deploy REST services in a container like Tomcat using Spring configuration, and how to test out the various operations exposed by the RESTFul application using CXF RESTful client API and using a web service development tool. We will look at how to enable exception handling, JSON message support, and logging support for RESTful applications using CXF framework.

By the end of this chapter the reader would be able utilize various CXF features for developing RESTful services and how to leverage Spring configuration for deploying RESTful service in the tomcat container.

Chapter 8: Working with CXF Tools will explain some of the commonly used CXF tools that assist us in web services development. We will look at how to invoke a real world .NET service over the internet using a Java client and JavaScript, create web service implementation from WSDL files, generate WSDL files from web service implementation, and validate the WSDL file for compliance.

By the end of this chapter the reader will be able to use different CXF tools to develop a service.

Appendix A deals with how to set up the CXF environment, provides details on how the source code for each chapter is organized, and shows how to run the source code examples using the ANT tool and Maven Tool.

Appendix B provides an explanation of the basics of the Spring framework and IoC concepts, along with an end-to-end example which utilizes Spring IoC concepts.

By the end of this Appendix chapter the reader will have a good understanding of Spring capabilities used in the context of CXF web   services development in this book.

Tweet This Post Delicious Digg This Post

This book is for developers who want to design and develop SOAP and RESTful services using Apache CXF framework and leverage various CXF features for service development. It is ideal for developers who have some experience in Java application development as well as some basic knowledge of web services, but it covers some of the basic fundamentals of web services and REST to get you acquainted with these technologies before using these concepts to develop services using the CXF framework. As part of Appendix, it also has a dedicated Chapter on Spring framework, to get the readers acquainted with the Spring capabilities used in the context of CXF web services development for this book.

We would love to hear any feedbacks on the book. If you find any errata or suggestions for the book, please post it in our forums.

Tweet This Post Delicious Digg This Post