The tree-based structure of XML may lead to some apparent problems. A common debate is about the fact that XML is not the best way to represent an arbitrary object because of its limitations when it comes to sharing object references. Think about the previous example. Imagine you have a number of customers in London, with the above representation you would have an overhead of redundant data (a number of identical "city" blocks), which is barely acceptable.

Indeed this example was made just to show a common misuse, where the attribute<city> should be considered as an independent entity, rather than a value.

A better approach would be to handle the problem just like you would do with a relational database that is moving repeated data outside of the main object and embedding just a reference to them in the latter.

With a Stateful approach, the client could have retrieved the list of all "city" entities at a previous stage. So when it calls the getAllCustomers service, this could return just the city ids.

<Customers>
<customer>
<id>4</id>
<name>Smith Ltd</name>
<location>
<address>39, Kensington Rd.</address>
<city>LND</city>
</location>
</customer>
<customer>
<id>7</id>
<name>Merkx & Co.</name>
<location>
<address>39, Venice Blvd.</address>
<city>LAX</city>
</location>
</customer>
...
</Customers>

<Entireresponse>
<cities>
<city>
<id>LND</id>
<name>London</name>
<country>UK</country>
</city>
<city>
<id>LAX</id>
<name>Los Angeles</name>
<country>USA</country>
</city>
</cities>
<customers>
<customer>
<id>4</id>
...
<location>
...
<city>LND</city>
</location>
</customer>
<customer>
<id>7</id>
...
<location>
...
<city>LAX</city>
</location>
</customer>
...
</customers>
</Entireresponse>

The process of designing services yields to a number of results. First of all, it produces a list of service definitions which is sometime referred to as a "Catalog of Services". This, naturally, should not have the form of a flat list, but will be organized into sections or "Functional Domains". So we could have, for example, the "Item", "Order", and "Customer" functional domains. Under these functional domains, the following services can be defined:

Item Functional domains are as follows:

Order Functional domains are as follows:

Often there will be the need for some "orthogonal" services. In fact, some services could share common mechanisms, such as a control flow or transaction handling.

Generally, at the beginning of any software design process, a common task is to focus on the basic domain objects and their essential handling operations: Create (or insert), Read (select), Update, and Delete. This is usually referred to as CRUD. No matter which language you are using, which architecture is adopted, all projects virtually have to deal with CRUD actions. In our case, a basic domain object is the Item entity and the first four listed services are exactly the CRUD functions.

Let's begin by analyzing and designing the services that handle the item domain. The insertItem service, for example, could have the following form:

<Item>
<id>0</id>
<code>RX004</code>
<description>
Eth. Cable
</description>
</Item>

<Result>
<retCode>
OK
</retCode>
<id>137</id>
</Result>

<ItemId>
<id>137</id>
</ItemId>

<Item>
<id>137</id>
<code>
RX004
</code>
<description>
Eth. Cable 4 ft.
</description>
</Item>

<Item>
<id>137</id>
<code>RX004</code>
<description>
Eth. Cable 4 ft.
</description>
</Item>

<Result>
<retCode>
OK
</retCode>
<id>137</id>
</Result>

<ItemId>
<id>137</id>
</ItemId>

<Result>
<retCode>
OK
</retCode>
<id>0</id>
</Result>

<ItemAction>
<method>
findById
</method>
<item>
<id>137</id>
<code></code>
<description>
</description>
</item>
</ItemAction>

<ItemActionResponse>
<retCode>OK</retCode>
<item>
<id>137</id>
<code>RX004</code>
<description>
Eth. Cable 4 ft.
</description>
</item>
</ItemActionResponse>

<Items>
<item>
<id>137</id>
<code>RX004</code>
<description>
Eth. Cable 4 ft.
</description>
</item>
...
</Items>

Web Service Decoupling

Now, to complete the example, we will see how to implement the findById service in the Java language. For the automatic binding, we decided to use the JAXB library. This component is included into the latest Java 6 JDK. So if you use this version of Java you do not need any additional jars. Otherwise, you will have to download JAXB and add it explicitly to your server and client class paths. However, since we will make use of Java Annotations, the following source code requires at least a JDK 5 release in order to be compiled and executed. For the server side service implementation, we adopted Tomcat 5.5. The implementation we are stepping through is in fact made up of a simple Java Servlet.

Let's start with the classes that will be exchanged between the client and the server: Item, ItemAction, and ItemActionResponse. There is very little indeed to say about them; they are basic POJO (Plain Old Java Object) with a Java annotation that has a key role in the process of XML serialization/deserialization.

@XmlRootElement(name="Item")

public class Item {
private int id;
private String code;
private String description;
... getter/setter methods omitted ...
@XmlRootElement(name="ItemAction")

public class ItemAction{
private String method;
private Item item;
...
@XmlRootElement(name="ItemActionResponse")

public class ItemActionResponse{
private String retCode
private Item item;
...

protected void doPost(HttpServletRequest request, HttpServletResponse response)
throws ServletException, IOException
{
try{
JAXBContext jaxbContext = JAXBContext.newInstance (ItemAction.class, ItemActionResponse.class);
Unmarshaller unmarshaller = jaxbContext.createUnmarshaller();

//Receiving the XML request and transform it into a Java object
ItemAction itemAction = (ItemAction)
unmarshaller.unmarshal(request.getInputStream());

//Do some action depending on the request content
String method = itemAction.getMethod();
//Prepare the response as a Java object
ItemActionResponse itemActionResponse = new ItemActionResponse();
if ("findById".equals(method)){
int id = itemAction.getItem().getId();
//Retrieve item (e.g. from db)
Item item = new Item();
item.setId(id);
item.setCode("Item XYZ");
item.setDescription("Description item XYZ");
//Fill the response
itemActionResponse.setRetCode("OK");
itemActionResponse.setItem(item);
}
Marshaller marshaller = jaxbContext.createMarshaller();
marshaller.setProperty(Marshaller.JAXB_FORMATTED_OUTPUT,
Boolean.TRUE);

//The following line is not required, it was inserted
//just to see the content of the generated XML message
marshaller.marshal(itemActionResponse, System.out);
//Send the XML message to the client
marshaller.marshal( itemActionResponse,

response.getOutputStream());
}
catch (JAXBException e){
throw new ServletException(e);
}
}

//Prepare the request
ItemAction itemAction = new ItemAction();
Item item = new Item();
item.setId(26);
itemAction.setMethod("findById");
itemAction.setItem(item);
//Prepare and establish the connection with the service
URL url = new URL("http://localhost/SoaBookPoxHttp/itemCrudService");
HttpURLConnection con = (HttpURLConnection) url.openConnection();
con.setDoOutput(true);

//Set the HTTP request method
con.setRequestMethod("POST");
con.connect();
JAXBContext jaxbContext = JAXBContext.newInstance (ItemAction.class, ItemActionResponse.class);
Marshaller marshaller = jaxbContext.createMarshaller();
marshaller.setProperty(Marshaller.JAXB_FORMATTED_OUTPUT, Boolean.TRUE);

//The following line is not required, it was inserted
//just to see the content of the generated XML message
marshaller.marshal(itemAction, System.out);
//Send the XML request to the service
marshaller.marshal(itemAction, con.getOutputStream());
//Get the XML response from the service and deserialize it

Unmarshaller unmarshaller = jaxbContext.createUnmarshaller();
ItemActionResponse itemActionResponse = (ItemActionResponse)
unmarshaller.unmarshal(con.getInputStream());

//Show the response content
System.out.println("retCode="+itemActionResponse.getRetCode()+ "
" +
"id="+itemActionResponse.getItem().getId()+ "
" +
"code="+itemActionResponse.getItem().getCode()+ "
"+"description="+itemActionResponse.getItem() .getDescription());

protected void doPost(HttpServletRequest request,
HttpServletResponse response)
throws ServletException, IOException
{
try {

JAXBContext jaxbContext = JAXBContext.newInstance (ItemList.class, Item.class);

ItemList itemList = new ItemList();
itemList.setList(new ArrayList());
Item i1 = new Item();
i1.set ... ;
itemList.getList().add(i1);
... populate itemList ...

Marshaller marshaller = jaxbContext.createMarshaller();
marshaller.setProperty(Marshaller.JAXB_FORMATTED_OUTPUT,
Boolean.TRUE);

//Just to see the content of the generated XML message
marshaller.marshal(itemList, System.out);
//Send the XML message to the client

marshaller.marshal(itemList, response.getOutputStream());

}
catch (JAXBException e) {
throw new ServletException(e);
}
}

import java.util.List;
import javax.xml.bind.annotation.XmlRootElement;

@XmlRootElement(name="ItemList")

public class ItemList {
private List list;
...

URL url = new URL("http://localhost/SoaBookPoxHttp/findAllItems");
HttpURLConnection con = (HttpURLConnection) url.openConnection();
con.setRequestMethod("POST");
con.connect();

//Void Request
//Get Response

JAXBContext jaxbContext = JAXBContext.newInstance (ItemList.class, Item.class);
Unmarshaller unmarshaller = jaxbContext.createUnmarshaller();
ItemList itemList = (ItemList)
unmarshaller.unmarshal(con.getInputStream());

for (Iterator iterator = itemList.getList().iterator();
iterator.hasNext();)
{
Item item = (Item) iterator.next();
System.out.println( item.getId()+" - "+ item.getCode()+" - "+
item.getDescription());
}

The Representational State Transfer ( REST) is a web architectural style presented by Roy Fielding back in 2000 in his doctoral thesis. The basic idea of REST is the full exploitation of the HTTP protocol, in particular:

In the basic POX-over-HTTP example, which we saw previously, you may have noticed that we assumed to use POST as HTTP verb. Although, we listed the source code for just one out of the several services we defined, all of them can be implemented using the same verb (not necessarily POST, any other method will do the job right). Therefore, the idea is, why not exploit this transportation protocol feature to map the usual CRUD and other methods in order to have a clearer communication protocol?

An association between the four CRUD methods and the correspondent HTTP verbs was therefore established and is shown in the following table:

Keeping in mind that the set of resources, each one with its values, represents the State of the system, the following rules should be applied:

All this may sound quite interesting, but what exactly is a "resource"? Basically, a resource is a scope within which the four HTTP verbs can cover all requested actions. Take for instance the Item domain we explored earlier. Well, that is a good candidate to be treated as a resource. As you see in the implementation source (Listing 5), a switch was introduced (in the if-then block) to do different actions depending on the method name contained in the request. This conditional flow control can be avoided and its role can be done by the HTTP verbs. Let's see how to do that in practice:

In order to create a new Item (the insertItem service), an XML document containing the object can be sent to the server with the POST method, while the response may be a generic outcome object:

@XmlRootElement(name="Outcome")

public class 
Outcome {
private String retCode;
private String retMessaget;
...
}

protected void doPost(HttpServletRequest request,
HttpServletResponse response)
throws ServletException, IOException
{
try{
JAXBContext jaxbContext = JAXBContext.newInstance (Item.class, Outcome.class);
Unmarshaller unmarshaller = jaxbContext.createUnmarshaller();
//Receiving the XML request and transform it into a Java object
Item item = (Item) unmarshaller.unmarshal (request.getInputStream());
System.out.println("Inserting item# "+item.getId());
// ... insert item
Marshaller marshaller = jaxbContext.createMarshaller();
marshaller.setProperty(Marshaller.JAXB_FORMATTED_OUTPUT, Boolean.TRUE);
Outcome outcome = new Outcome();
outcome.setRetCode("OK");
outcome.setRetMessaget("Item was inserted successfully");
marshaller.marshal(outcome, response.getOutputStream());
}
catch (Exception e) {
throw new ServletException(e);
}
}

Item item = new Item();
item.set...
//Prepare and establish the connection with the service

URL url = new URL("http://localhost/SoaBookREST/itemService");
HttpURLConnection con = (HttpURLConnection) url.openConnection();
con.setDoOutput(true);

//Set the HTTP request method

con.setRequestMethod("POST");
con.connect();
JAXBContext jaxbContext = JAXBContext.newInstance (Item.class, Outcome.class);
Marshaller marshaller = jaxbContext.createMarshaller();
marshaller.setProperty(Marshaller.JAXB_FORMATTED_OUTPUT, Boolean.TRUE);

//Send the XML request to the service

marshaller.marshal(item, con.getOutputStream());

//Get the XML response from the service and deserialize it

Unmarshaller unmarshaller = jaxbContext.createUnmarshaller();
Outcome outcome = (Outcome)
unmarshaller.unmarshal(con.getInputStream());

<servlet-mapping>
<servlet-name>ItemService</servlet-name>
<url-pattern>/itemService/*</url-pattern>
</servlet-mapping>

protected void doGet(HttpServletRequest request, HttpServletResponse response)
throws ServletException, IOException
{
try{
if (request.getPathInfo()==null){
//findAllItems

ItemList itemList = new ItemList();
itemList.setList(new ArrayList());
//retrieve all items
...
itemList.getList().add(...);
...
//Send the XML message to the client

JAXBContext jaxbContext = JAXBContext.newInstance (ItemList.class, Item.class);
Marshaller marshaller = jaxbContext.createMarshaller();
marshaller.setProperty(Marshaller.JAXB_FORMATTED_OUTPUT, Boolean.TRUE);
marshaller.marshal(itemList, response.getOutputStream());

} else {
//
findItemById

int id = (new Integer(
request.getPathInfo().substring(1)))
.intValue();
//retrieve item by id (e.g. from a database)
Item item = ...

JAXBContext jaxbContext = JAXBContext.newInstance(Item.class);
Marshaller marshaller = jaxbContext.createMarshaller();
marshaller.setProperty(Marshaller.JAXB_FORMATTED_OUTPUT, Boolean.TRUE);
marshaller.marshal(item, response.getOutputStream());

}
}
catch (Exception e) {
throw new ServletException(e);
}
}

PUT http://localhost/SoaBookREST/itemService/14

http://localhost/SoaBookREST/itemService?id=14

The Simple Object Access Protocol (SOAP) is a web service standard communication protocol defined by the W3C. It basically defines the structure of the exchanged message, which is composed of an "envelope" with a "header" and a "body". As you will see next, this protocol adds various levels of complexity. But it also offers a wide range of powerful features, among which are:

In order to show you a straightforward implementation of the services of our domain sample, we will use the JDK 6 embedded capabilities to define and publish web services. In fact, while in the previous examples we exploited the JAXB component to perform the automatic binding between XML documents and Java objects, here we will make use of the JAX-WS library, which will increase the abstraction level significantly.

Look how easy it is to create a couple of services such as insert and update:

package com.packt.soajava.soap.service.item;
import javax.jws.WebMethod;
import javax.jws.WebService;
import javax.xml.ws.Endpoint;
import com.packt.soajava.model.item.Item;
import com.packt.soajava.model.item.Outcome;

@WebService

public class ItemWs {

@WebMethod
public Outcome insert(Item item) {
//Insert item ...
System.out.println("Inserting item "+item.getId());
Outcome outcome = new Outcome();
outcome.setRetCode("OK");
outcome.setRetMessage("Item was inserted successfully");
return outcome;
}

@WebMethod
public Outcome update(Item item) {
//Update item ...
System.out.println("Updating item "+item.getId());
Outcome outcome = new Outcome();
outcome.setRetCode("OK");
outcome.setRetMessage("Item was updated successfully");
return outcome;
}

<JDK6_HOME>in
wsgen -cp <ProjectClassesRoot> 
-d <ProjectSourceRoot>
 -keep com.packt.soajava.soap.service.item.ItemWs

Endpoint.publish( "http://localhost:8001/SoaBookSOAP_server/itemWs",
new ItemWs());

http://localhost:8001/SoaBookSOAP_server/itemWs?WSDL

<JDK6_HOME>inwsimport -d <ClientProjectSourceRoot>
-p com.packt.soajava.soap.client.test.item
-keep http://localhost:8001/SoaBookSOAP_server/itemWs?WSDL

ItemWsService service = new ItemWsService();

ItemWs itemWs = service.getItemWsPort();

Item item1 = new Item();
item1.set ...
Outcome outcome = itemWs.insert(item1);

<?xml version="1.0" ?>
<soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:ns1="http://item.service.soap.soajava.packt.com/">
<soapenv:Body>
<ns1:insert>
<arg0>
<code>XY</code>
<description>xy desc</description>
<id>26</id>
</arg0>
</ns1:insert>
</soapenv:Body>
</soapenv:Envelope>

while the response content is as follows:

<?xml version="1.0" ?>
<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
<S:Body>
<ns2:insertResponse
xmlns:ns2="http://item.service.soap.soajava.packt.com/">
<return>
<retCode>OK</retCode>
<retMessage>Item was inserted successfully</retMessage>
</return>
</ns2:insertResponse>
</S:Body>
</S:Envelope>

As you can see, the XML content of a SOAP message is structured as an envelope which contains a mandatory body, while the header is optional. The content of the body element represents the payload that is the exchanged XML document.

However, when dealing with SOAP, a wide range of options are available. In our last example, we just adopted the default settings to keep things simpler and straightforward.

You may have heard, for example, about binding style (RCP or Document) or use (Encoded or Literal) or parameter style (Bare or Wrapped). In this paragraph, we will explore these concepts with particular emphasis on the binding style.

Before getting into this analysis though, we should spend some time on WS-I. The term stands for Web Service — Interoperability and represents a set of standards put together in order to allow the process of exchanging data throughout web services in a heterogeneous environment (for example, between Java and .NET). Of all the combinations of binding style, use, and parameter style, only the following are WS-I compliant, and we will concentrate exactly on them:

The "encoded" value for the use attribute is prohibited by WS-I. With this value, in fact, the data is serialized following the SOAP encoding described in Section 5 of SOAP 1.1 specification. Validating a SOAP encoded message against a WSDL description is quite a hard work, and since the validation is a fundamental step toward interoperability, only the use "literal" is allowed by WS-I.

One of the first architectural choices that has to be made when we decide to develop SOAP web services is whether to use RPC or Document binding style. Remote Procedure Call (RPC) is a generic mechanism throughout which is a procedure that resides on a computer (or a virtual machine) can be called by a program running on a different computer (or virtual machine). This paradigm has been around for decades and was implemented by several technologies, among which, the most popular are CORBA, DCOM, and RMI.

Despite the changes in technologies, an RPC call is always characterized by:

Note that, aside from the first, it shares the same characteristics of a classic local method call.

What does this old RPC paradigm have to do with SOAP and web services? Well, quite a lot indeed. In fact, in the early days of its definition (before being publicly published), SOAP was designed to support only RPC. It was, in a sense, a standardized evolution of the various distributed programming technologies.

With some modification in the annotation of the web service we designed last, we can switch it to RPC style (the JAX-WS default is "Document") and begin to explore this approach.

@WebService
@SOAPBinding(style=SOAPBinding.Style.RPC)

public class ItemWs {
@WebMethod
public Outcome insert(@WebParam(name="itemParam") Item item,
@WebParam(name="categoryParam") String category)
{
//Insert item ...

Outcome outcome = itemWs.insert(item1, "A");

<soapenv:Body>
<ans:insert xmlns:ans="http:// ... ">
<itemParam>

<code>XY</code>
<description>xy desc</description>
<id>26</id>
</itemParam>

<categoryParam>A</categoryParam>
</ans:insert>

</soapenv:Body>

<types>
<xsd:schema>
<xsd:import schemaLocation="http://127.0.0.1:8002/ SoaBookSOAP_RPC_server/itemWs?xsd=1" namespace="http://item.service. soap.soajava.packt.com/"></xsd:import>
</xsd:schema>
</types>
<message name="insert">
<part name="itemParam" type="tns:item"></part>
<part name="categoryParam" type="xsd:string"></part>
</message>
<message name="insertResponse">
<part name="return" type="tns:outcome"></part>
</message>

<portType name="ItemWs">
<operation name="insert" parameterOrder= "itemParam categoryParam">
<input message="tns:insert"></input>
<output message="tns:insertResponse"></output>
</operation>

</portType>
<binding name="ItemWsPortBinding" type="tns:ItemWs">
<soap:binding style="rpc" transport="http://schemas.xmlsoap.org/soap/http">
</soap:binding>
<operation name="insert">
<soap:operation soapAction=""></soap:operation>
<input>
<soap:body use="literal" namespace= "http://item.service.soap.soajava.packt.com/">
</soap:body>
</input>
<output>
<soap:body use="literal" namespace=
"http://item.service.soap.soajava.packt.com/">
</soap:body>
</output>
</operation>
</binding>
<service name="ItemWsService">
<port name="ItemWsPort" binding="tns:ItemWsPortBinding">
<soap:address location=
"http://127.0.0.1:8002/SoaBookSOAP_RPC_server/itemWs">
</soap:address>
</port>
</service>
</definitions>

http://127.0.0.1:8001/SoaBookSOAP_RPC_server/itemWs?xsd=1

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:tns="http://item.service.soap.soajava.packt.com/" xmlns:xs="http://www.w3.org/2001/XMLSchema" targetNamespace="http://item.service.soap.soajava.packt.com/" version="1.0">
<xs:element name="Item" type="tns:item"></xs:element>
<xs:element name="Outcome" type="tns:outcome"></xs:element>
<xs:complexType name="item">
<xs:sequence>
<xs:element name="code" type="xs:string" minOccurs="0"></xs:element>
<xs:element name="description" type="xs:string" minOccurs="0"></xs:element>
<xs:element name="id" type="xs:int"></xs:element>
</xs:sequence>
</xs:complexType>
<xs:complexType name="outcome">
<xs:sequence>
<xs:element name="retCode" type="xs:string" minOccurs="0"></xs:element>
<xs:element name="retMessage" type="xs:string" minOccurs="0"></xs:element>
</xs:sequence>
</xs:complexType>

</xs:schema>

This style is also known as Document "bare" or "unwrapped" and we will soon get into the explanation of this term. For the moment the thing to pay attention to is that, using JAX-WS, the default value for the parameter style is "wrapped". Hence, in order to use the Document bare style, we have to set it explicitly.

@SOAPBinding(style=SOAPBinding.Style.DOCUMENT, parameterStyle=SOAPBinding.ParameterStyle.BARE)
public class ItemWs {
@WebMethod
public Outcome insert(@WebParam(name="itemParam") Item item,
@WebParam(name="categoryParam") String category) { ...

error: operation "insert": more than one part bound to body

@XmlRootElement(name = "ItemInsertRequest")
public class ItemInsertRequest {
private Item item;

private String category;

...

@WebMethod
public Outcome insert(
@WebParam(name="itemInsertRequestParam")
ItemInsertRequest itemInsertRequest) {
...

ItemInsertRequest req = new ItemInsertRequest();


req.setItem(item1);

req.setCategory("A");
Outcome outcome = itemWs.
insert(req);

<ns1:itemInsertRequestParam>
<category>A</category>
<item>

<code>XY</code>
<description>xy desc</description>
<id>26</id>

</item>
</ns1:itemInsertRequestParam>

<message name="insert">
<part element="tns:itemInsertRequestParam"
name="itemInsertRequestParam"></part>
</message>
...
<binding name="ItemWsPortBinding" type="tns:ItemWs">
<soap:binding style="document"

<xs:element name="Item" type="tns:item"></xs:element>
<xs:element name="ItemInsertRequest"
type="tns:itemInsertRequest"></xs:element>
<xs:element name="Outcome" type="tns:outcome"></xs:element>
<xs:element nillable="true" name="insertResponse"
type="tns:outcome"></xs:element>
<xs:element nillable="true" name="itemInsertRequestParam"
type="tns:itemInsertRequest"></xs:element>
<xs:complexType name="itemInsertRequest">
<xs:sequence>
<xs:element name="category" type="xs:string"
minOccurs="0"></xs:element>
<xs:element name="item" type="tns:item"
minOccurs="0"></xs:element>
</xs:sequence>
</xs:complexType>
<xs:complexType name="item">
<xs:sequence>
<xs:element name="code" type="xs:string"
minOccurs="0"></xs:element>
<xs:element name="description" type="xs:string"
minOccurs="0"></xs:element>
<xs:element name="id" type="xs:int"></xs:element>
</xs:sequence>

</xs:complexType>

This style is the default in JAX-WS, and we have already made use of it in our very first SOAP example (see Listing 14). The following annotation is in fact useless with JAX-WS:

@SOAPBinding(style=SOAPBinding.Style.DOCUMENT,
parameterStyle=SOAPBinding.ParameterStyle.WRAPPED)

@WebMethod
public Outcome insert(@WebParam(name="itemParam") Item item, @WebParam(name="categoryParam") String category) {

<ns1:insert>
<itemParam>
<code>XY</code>
<description>xy desc</description>
<id>26</id>
</itemParam>
<categoryParam>A</categoryParam>
</ns1:insert>

In the previous paragraph, we introduced the difference between RPC and Document style. At first, one can argue that, after all, examining the exchanged messages and their WSDL, the two approaches are not that different, especially the RPC and Document wrapped ones. Well, in a sense, this is true.

The difference is indeed more philosophical than practical, at least for most of us accustomed for decades to the "method call" paradigm. We may have gone through several programming languages and technologies, but we always could count on a rock pillar that is of being able to call a method (sometimes named "procedure", "function", or whatever) passing a sequence of parameters and (optionally) getting the result.

In this scenario, when SOAP was initially conceived, web services were more or less an extension of this model in order to allow the call of a remote procedure (RPC) in a more standardized fashion. In fact, as mentioned before, the initial SOAP specification was based upon RPC style.

Now, we intend to show how the Document approach is shifting the focus for a new programming model that will arguably take the leading way in the future.

A document is similar to a message, that is, something to be "sent" or "forwarded" to a destination which is designed to process it.

Document Style

Self-Containing Documents and Asynchronous Models

We should not focus on when this processing will take place, but must instead ensure that the message contains all the information needed for the processing itself. Therefore, the message should be a self-contained business document. This is a fundamental prerequisite when dealing with an asynchronous transportation protocol (for example SMTP or JMS, both supported by SOAP), but is anyway a good practice even when not explicitly required.

Another situation where a self-contained business document is a requirement is when a work-flow system is used. In fact, since the transitions inside a work-flow are intrinsically asynchronous, the Document style fits well in this scenario.

Validating Capabilities

We have already highlighted one intrinsic advantage of this style: the capability to perform a full validation of the exchanged documents against their correspondent XML schemas.

Loose Coupling

One of the major weaknesses of the RPC approach is the tight coupling that it imposes on architectures. A change in a service method signature has an immediate impact throughout the system, forcing the refactoring up to the client layer. With Document style, the problem is drastically reduced since a change in the structure of a message (like, adding a new attribute) does not affect the document exchange mechanisms. On the other hand, a change in a back-end (internal) method signature has generally no effect upon the messages structure.

This loose coupling, intrinsic in the Document style, leads to more robust and reliable architectures that are easier to maintain, and having a modular aspect.

Interoperability

Finally, we have to consider the value of interoperability, which is the ability to work together with different technologies and systems. This can be obtained primarily by adhering to standard communication protocols and directives, with an eye open though, to the market trends. The Document style is gaining consensus and is largely adopted by most vendors. It is a matter of fact that both the Java reference implementation of JAX-WS, along with most other Java WS implementations (see Chapter 6), and the .NET platform use the Document style as the default setting.

We have indeed already been introduced to JAX-WS in the previous paragraphs. What should be noted first, about this option, is that it is a specification (JSR-224), rather than an implementation. In fact, its name stands for "Java API for XML Web Services" and it follows the previousJAX-RPC (Java API for XML-based Remote Procedure Call) specification.

One of the main advantages of this choice is that its Reference Implementation is included both into Java SE 6 and Java EE 5. Thus no external library is needed in order to use it. If you adopt this embedded version, then you will be working with the version 2.0 of the product, though, at the time of writing, it has reached version 2.1 as a separate implementation.

As far as the data binding model is concerned, it uses JAXB, while the XML parser engine is the stream-based pull parser StAX (Streaming API for XML). This parsing approach, where the client gets XML data only when requested, allows better performances compared to a DOM-based approach, where the entire XML document is parsed to obtain an in-memory object tree. In fact, not only is the requested memory footprint smaller, but also there is the advantage of having the parser start its process earlier.

JAX-WS supports both SOAP and REST communication protocols, though RESTful services cannot take advantage of the automatic code generation (in contrast with the SOAP/WSDL approach) since a standard for RESTful services description has not yet been defined.

It strongly relies on the usage of annotations and supports a number of transportation protocols, going beyond HTTP including SMTP and JMS.

Moreover the range of WS-* features covered is indeed wide. It goes from WS-Security and Policy to WS-Atomic Transaction and WS-ReliableMessaging.

Finally, among its features, there is also the capability to build Stateful web services.

This tool is part of "Web Service Project @ Apache", a set of several projects that cover various aspects related to the development and usage of web services. They are for the majority implementations of protocols and specifications.

Axis2 is a complete re-factoring of the previous 1.x version, and upon its architecture two different implementations were built, Axis2/Java and Axis2/C.

The SAX event-based XML parser used in the previous version has been replaced by the pull-based StAX, which allows greater control over the document processing that translates into higher efficiency and performances.

Indeed Axis2 uses AXIOM (AXIs Object Model), a light-weight object model for XML processing, which is based on StAX and offers enhancing features.

Axis2 can be used to develop both SOAP-based and RESTful web services. Also, it supports Asynchronous (or Non-Blocking) web services invocation, which is implemented by Callback mechanisms.

It has been designed with a modular and extensible architecture. The processes of sending and receiving the SOAP messages are performed by two "Pipes" (or "Flows"): the In Pipe and Out Pipe. Each pipe is designed to process the message throughout a sequence of phases which can have pluggable "Handlers", there by giving the whole architecture a high-level of extensibility. In fact, in addition to built-in phases, there is the option to add User-defined phases with custom handlers inside them, in order to perform new mechanisms or to override existing ones.

Another important level of Handlers grouping is the concept of Module. Each module defines a set of handlers, and a descriptor of the phase rules. A handler can specify not only the phase where it will perform its action, but also its execution order inside the phase throughout the phase rules. In the Axis2 language, a module is "available" when it is present in the system, though not active. The activation of a module turns it to the "engaged" state, after which its handlers are placed into their associated phases and enabled. Thus, it is easy, for example, to plug-in modules that handle WS-* specifications such as WS-Security (Apache Rampart module) or WS-Atomic Transaction (Apache Kandula2 module).

The data binding is not part of the core of Axis2, but it is provided by an extension mechanism that allows the choice among ABD (AxisData Binding), XMLBeans, JAX-Me, and JibX. Also, the range of the transmission protocols supported is complete (HTTP, TCP, SMTP, and JMS).

The default Axis2 installation procedure consists of deploying the "WAR distribution" to the application server (for Tomcat (the declared recommended container) and just copying the file into the CATALINA_HOME/webapps directory). This will deploy the "axis2" web application (the Axis2 Administration Application) that allows the addition and configuration of services and modules.

Please note that services, modules, phases, and handlers are configured in an independent way with respect to the other deployed web applications. In other words, if you have a set of deployed web applications, each with its own business layer, you will not put a service into one of these web applications. Instead, it will be defined and configured into axis2 application and therefore generally available to every consumer (a client or another server application).

Also consider that every configuration made with the Axis2 Administration Application will not be saved and will therefore be lost after a restart of Axis2 application. Now, the situation will go back to the manually edited configuration files.

Alternatively, you can install the "standard binary distribution", which includes, in addition to all the necessary jars, a number of command line tools for:

Spring Framework is certainly one of the more popular and interesting products today available in the Java development area. It has definitely revolutionized the approach to designing software projects. With its aspect-oriented philosophy, and the introduction of the concept of "Inversion of Control (IoC)" or "Dependency Injection", it has made the process of building the architecture of a J2EE application easier and cleaner. But Spring is much more than an IoC container. It provides out-of-the-box patterns and templates, and integrates well with a number of other frameworks and tools, brings flexibility, modularity, and robustness.

This great community has made, among the others, its contribution to the web services area, and its name is "Spring Web Services" or "Spring-WS".

Therefore, an immediate advantage in adopting this framework is the inheritance of the Spring concepts and patterns, as well as, the re-use of the know-how you may have already consolidated. The loose coupling between the service contract (or interface) and its implementation is, for example, one of the first pros of this choice.

A mainstream web service recipe recommends starting the designing from the WSDL (contract-first) rather than from the Java code. Spring-WS pushes this approach further, driving the designer to start from the schemas (XSD) of the input and output XML messages. The WSDL will then be automatically generated from the XSDs.

The XML handling can be configured to use a DOM-based library (W3C DOM, JDOM, dom4j, XOM), SAX, StAX and XPath, while for XML binding, you can choose between JAXB, Castor, XMLBeans, JiBX, and XStream.

Spring-WS has a powerful and flexible Message Dispatcher which can handle the XML message distribution.

Particular care has been dedicated to the WS-Security aspects regarding Authentication, Digital signatures, Encryption, and Decryption.

XFire has been developed with the goal of obtaining better performance with respect to Axis 1.x (the de facto standard at that time). In fact, it uses a fast object model based on StAX.

It is simple and easy to use; it provides support for several binding libraries: JAXB, Castor, and XMLBeans. But the default is Aegis Binding — a fast binding mechanism with a small memory requirement.

XFire integrates well with many containers, among which are Spring and PicoContainer (another Inversion-of-Control framework). A set of easy-to-use client API makes it easy to build the client side, and to develop unit tests. The transports supported are HTTP, JMS, and Jabber/XMPP.

Recently, XFire and another web service framework, Celtix, have converged to a new product, CXF 2.0, which should be considered the continuation of XFire 1.x. The goal of this new tool is to go further in the directions of high performances, and ease of use.

CXF supports a number of protocols in addition to SOAP, including REST (via Annotations) and CORBA. It adheres to several standards and WS-* specifications.

Its focus is also on being made embeddable into other programs and pushes on the code-first methodology instead of contract-first.