Sunday, August 28, 2011

Layers versus Tiers

There is one question that is often confused in design/architectural considerations namely - Tiers versus Layers.
Here we try to analyze the difference between the 2.
Layers: A Layer is considered to be a discrete, orthogonal area of concern within an application. A layer generally would be a logical section of the code that deals with unique features. For example a persistence layer would deal with all the code related to database operations in a section of the code. This way it is easy to divide the work and isolate problems. If we have any change related to a database we know which part of the code gets affected and we can isolate the area of concern.
The other features of layers are:
1. Layers are conceptual boundaries and are not necessarily physically isolated. More often than not the layers would be placed in the same VM.
2. Thinking in layers can help conceptualize the flow through an application and help in more organized design.

Tiers: By contrast a tier is best thought of as a physical deployment of the layers. Thinking in tiers is more related to system administration and architectural decision making where it helps us decide what would be the different server, V.M. and other hardware requirements. Mostly multiple layers are mapped onto a tier.

The best example of a tiered architecture is a 3 tiered architecture where we deal with client-server-database.
In contrast the 3 layered architecture deals with the 3 layers in the form Controller-Service-DAO layers at the server side.

Tuesday, April 19, 2011

Simple JAX-WS Client example

    In my previous articles I have discussed server side code of a web service which deals essentially with publishing a web service. However in most of the business situation that one comes across the role is of a web service client rather than a web service provider. This articles deals with the creation of a web service client using JAX-WS.

    In JAX-WS clients are of 2 types. a) Static Clients b) Dynamic Clients.

Static Clients – The more commonly developed clients, these clients are generally developed by creating auto-generated code on the WSDL provided. These are specific to a WSDL hence the provider cannot be changed at runtime.

Dynamic Client – The lesser common of the two forms of clients, used when developing a client dynamically at runtime. This method is used when we may want to change our web service provider at runtime (or for REST services since they do not have a WSDL).

In this article we discuss the creation of a Static Client. The brief process of creation of a static client is highlighted below:

Step 1. Identify the WSDL location of the service provider

Step 2. Run the auto generate tool, to generate the artifacts/ stubs that are needed to create a web service client.

Step 3. Create the client code that will create the request object and then call the service using the stubs created in Step 2.

Let us try to create a sample code for a Web Service Client for the HelloWorld service that we created here. For my case, the service is deployed on Glassfish and the WSDL is located at the following location: http://localhost:8080/JAXWSHelloWorld/HelloWorld?wsdl

To create the stubs/artifacts use the wsimport command available with the web service provider (in my case Glassfish or Java 6). Though the name may vary with different providers the basic syntax normally remains the same. Run the command to create a list of artifacts as given below:

Command: wsimport -s src -keep -d build\classes -verbose -p com.jaxws.helloworld.client http://localhost:8080/JAXWSHelloWorld/HelloWorld?wsdl

The parameters / arguments which have been passed are:

-s [folder]Location to place the generated .java source files
-d [folder]Location to place the generated class files
-keepInstructs wsimport to keep the generated source files and not delete them
-verboseTo output the trace logs in stdout (to debug / follow)
-p [package name]To use a custom package name for generated classes. The default value would be taken from the target namespace if this is not specified


On running the above command the following files are generated. Please note the files generated below will vary according to WSDL.

File NamePurpose
package-info.javaThis defines the mapping between the namespace and package name as an annotation
ObjectFactory.javaThis factory class which is used to create request and response objects.
HelloWorldEndpoint.javaThe SEI (Service Endpoint Interface) generated to map the WSDL port. It makes all the exposed operations available to the client.
HelloWorld.javaThe Service class which implements the code for the SEI, allowing us to call the remote server (web service provider) to get the response. This class takes the request in object form, marshals it into XML, sends the XML / SOAP to service, gets back the response as XML/SOAP, un-marshals it to an object and gives us back.
The Request and Response objects that are created.


The above generated files are called stubs and are used to access the web service. A sample simple program to access the service is shown below:

class HelloWorldClient {


    private HelloWorldEndpoint helloWorld;

    public static void main(String[] args) {

        HelloWorldClient client = new HelloWorldClient();


            HelloWorld helloWrldService = new HelloWorld();

            client.helloWorld = helloWrldService.getHelloWorldEndpointPort();


        String resp = client.helloWorld.greet("Aditya", "Keyal");




The above code is a standalone main program which is used to access the web service. There are few points to be noted here. The SEI member variable has an annotation @WebServiceRef added. If deployed in a web service container (i.e. if this piece of code was present in a Servlet instead of a standalone main program and the Servlet deployed in the same glassfish server as the service) then the SEI Implementation [] is used to automoatically look up the "Port" which is then injected through dependency injection. In this program since I have used a main program I had to create an instance of and assign the port to the SEI variable.

In the next article I will create a Dynamic client for the sample service.

Thursday, March 24, 2011

JAXWS annotations

In the previous post I discussed how to create a simple JAX-WS enabled web service. For accomplishing the same we used the following 2 annotations:

  1. @WebService
  2. @WebMethod

By using the above 2 annotations and a number of pre-defined defaults for annotations not added we were able to generate a WSDL mapping to the Java implementation. In case we wish to customize the WSDL generated, JAX-WS gives us a set of annotations that can be used. The different annotations come from 3 different JSR's and can be used to customize the different parts of the WSDL. The different JSR's are:

  1. Web Services Metadata Annotations (JSR 181)
  2. JAX-WS Annotations (JSR 224)
  3. JAX-WS Common Annotations (JSR 250)

One point worth noting here is that these annotations are useful in customizing the WSDL file but not the JAXB binding part of it. If we want to customize the JAXB binding (i.e. the XSD Schema details) we need to add JAXB annotations on the JAXB classes (request/response parameters).

To get a list of each of the annotations in JAXWS please refer the following site.

Wednesday, March 16, 2011

JAX-WS Hello World Example

    In this article I provide a step-by-step illustrated example on creating a simple Hell World Service example by using JAX-WS.

Service – Hello World service exposing one method called greet. The method implementation accepts a first name and a last name and returns a greeting string.

Stack – JAX-WS with Glassfish Server, Eclipse for development.


Step 1: Create a Dynamic Web Project in eclipse, with the name "JAXWSHelloWorld".

Step 2: Create a simple implementation class called com.jaxws.example.HelloWorldEndpoint. It will contain a single public method called greet() which accepts 2 strings (firstname and lastName) and returns a greeting message. Then annotate the class with the @WebService annotation and the greet method with @WebMethod annotation.

The @WebService has the serviceName attribute. The value of this attribute is the name of the service in the WSDL and also the URL at which the service is available.

The @WebMethod has the attribute operationName. The value of this attribute is the name of the operation defined in the WSDL.

Please note these are not mandatory and are used only for reference/ease of debugging.

The sample source is given below.

Note: The values attributes of annotation are optional. More details on what they mean will be explained later.

Step 3: Create the related resources (JAXB binding files, WSDL and schema files and corresponding classes). For the run the wsgen bat available with JDK 1.6 or Glassfish with the following parameters:

wsgen –verbose –cp build/classes –s src –wsdl –r WebContent\WEB-INF\wsdl –d build\classes com.jaxws.example.HelloWorldEndpoint

-verbose : prints the operation being executed

- cp <folder> : the location of the base folder where the class file of the Endpoint (HelloWorldEndpoint) is located.

-s <folder> : the location where the generated source files (JAXB binding) are stored

-wsdl : specifies that the WSDL should be generated

-r <folder> : the location of the folder where the resources/artifacts will be generated

-d <folder> : the location of the folder where the generated class files (of JAXB Binding and JAXWS files) will be kept.

Step 4: Deploy the application on the server (Glassfish). To deploy the application, import the glassfish server into eclipse and then just simply right click the project choose Run As > Server. When the server starts monitor the logs. In the logs you will see a line about the WebService Endpoint successfully deployed and the location of the endpoint.

Note: The location is of the format -> http://url:portNumber/applicationName/serviceName[Of Endpoint]

Step 5: The web service is deployed. Hit the URL of the endpoint specified during deployment [http://locahost:8080/JAXWSHelloWorld/HelloWorld] in my case. You should be able to see a dynamically generated page detailing the service and operations exposed.

Step 6: The Web service is now deployed. To confirm check the WSDL deployed the link for which is available on the generated screen. [http://localhost:8080/JAXWSHelloWorld/HelloWorld?wsdl] in my case.

This is a generated WSDL by the JAXWS implementation (Glassfish in my case). The Service is of the type document/literal [wrapped]. The XSD is also available.

Step 7: To test the service, use Web Service Explorer available with eclipse or SOAPUI and set the endpoint to the location of the endpoint. The sample request response in my case are as given below.

 <soapenv:Envelope xmlns:soapenv="" xmlns:q0="" xmlns:xsd="" xmlns:xsi="">  

 <S:Envelope xmlns:S="">  
    <ns2:greetResponse xmlns:ns2="">  
      <return>Hello AdityaKeyal</return>  

The above example is available for download here. It is a complete eclipse project. Just download and import into eclipse and build then deploy on Glassfish for it to run.

JAX-WS explained in layman terms with an example

    JAX-WS, often touted as the "Holy Grail" of Java Web Services, is the most popular technology available in recent years; however what is disappointing is the lack of any detailed information that tries to clearly explain in layman terms what is JAX-WS? In this article I try to explain to the best what "JAX-WS" is with an example.

JAX-WS -> is a specification (JSR 224) provided by Sun which consists of a set of API used for creating Web Services. We have heard this statement in almost every web site but what this really means?

JAX-WS, like all specifications, is divided into 2 parts:

  1. The First part consists of an API provided by SUN. This API is accompanied by a JSR. The API consists of a set of interfaces, annotations, xml files and abstract classes (sometimes maybe a few base classes) which are to be used when using that feature. One very important thing about this API that should be noted is that the API in itself is not capable of achieving the intended objective of the specification. The JSR lays down a set of rules and regulations governing the API.
  2. The Second part of any specification is the implementation. The implementation follows all the rules laid down by the JSR and uses the API (i.e. provides all implementation for interfaces, and classes that use the annotations to get the desired objective) to provide a base. For example, in EJB 3.0 by annotating a class by @Stateless annotation we can create an EJB. The @Stateless annotation is useless by itself, however when this class is deployed on an EJB 3.0 enabled server (which contains an implementation for EJB 3.0 API) the server makes sense of the annotation and creates the corresponding EJB and gives the desired result.
Similarly in the case of JAX-WS, we have 2 parts: the API which is available from SUN and multiple reference implementations by different vendors like: Sun (JDK 1.6), Apache (CXF, AXIS 2), IBM (Web sphere), ORACLE (Weblogic App Server), Glassfish (Metro).

How to create a Web Services: As discussed in a previous article JAX-WS supports Java First, WSDL First and Meet in the Middle approach. However for the most basic discussion, I shall be using a Java First approach to create a sample web service. A few of the important features that JAX-WS provides are:

  1. JAXB data binding framework which can be switched ON or OFF.
  2. Automatic generation of WSDL when using Java First
  3. Automatic generation of Binding data when using Java First
  4. Automatic generation of skeleton classes when using WSDL First
  5. Automatic generation of Binding when using WSDL First.
  6. Customization for both Java First and WSDL First approaches.
The simplest way to create a web service consists of the following steps:

  1. Create an implementation class
  2. Annotate the class with @WebService annotation
  3. Annotate the methods to be exposed with @WebMethod annotation
  4. Generate WSDL, XSD and Binding classes using wsgen functionality (glassfish)
  5. Deploy the service on server (Glassfish)
  6. Get WSDL
  7. Test service using Eclipse Web Service Explorer
Check out the step by step illustrated JAX-WS example here.

Sunday, March 13, 2011

When “WSDL First”? When “Java First”? Where do we “Meet in the Middle”?

In most of the books that I have read on JAX-WS, JAX-RPC or any other on Java Web Services, one of the initial chapters is inadvertently based on "the different approaches to developing services", discussing Java or WSDL First approach. What I have always found unsatisfying about these chapters is the fact that they talk of how we can create/implement such methodologies, but, never about why or even when we use which approach? This article I try to explain when and why do we use the different approaches rather than how do we use them.

For the purpose of discussion let us consider the following case study.

    "An online book store wants to expose its products as a service. It would be offering search services to any customer that maybe interested in looking up data about the books that it has in stock. The book store sells Books and Periodicals"

Data to be exposed
Publishing HousePublishing House
Revision NumberPrint Date

Business View:

In the above table, it is evident that according to the business, a book and a periodical are 2 totally different entities. Conceptually also a book is a onetime published entity while a periodical is a regularly published entity. They have different business significance and probably different business sections. So when the business team tries to visualize a Book or a Periodical in a web service, they see it as an xml with the below defined attributes:


Architect/Technical View:

When an architect or a technical designer is asked to look at the same problem given above, he will try to apply all the principles of OOP and create a design solution that looks like the one give below:

As shown above, the use inheritance to extract out the common properties by creating a base class and then extending the base class to create the actual classes of Books and Periodicals; is one of the first solutions provided. This extraction probably also has ramifications on the signature and number of methods exposed.

It must be noted that both the views are correct and proper. The Business is trying to visualize a solution that is more acceptable to them while the designer/technical architect is trying to visualize a solution more palatable to his taste. The choice of "WSDL First" approach or "Java First" approach largely depends on whether we choose the business vision (WSDL) of the web service or whether we choose a Technical vision (Java) of the web service. If we try to please them both, we may adopt to bridge the gap and "meet in the middle". This is definitely a great solution but a tedious one sing satisfying both business and technical viewpoint often has ramifications on the kind of technologies and the stack structure that we may use.

Note: The above article is based squarely on the design of server side components. When designing a client side more often than not we will go for a WSDL First since we would be consuming a web service and not creating one.

Web Service Addressing Mechanisms

    Any web service request from a client to a service goes through the process defined below at the server-side:

  1. The request is received by a Servlet (for a HTTP request)
  2. The Servlet identifies which Endpoint to call (using a strategy mapping)
  3. The Servlet identifies which method/operation in the endpoint to call (using same/alternative strategy)
  4. The Incoming request XML is un-marshaled into an Object (method parameters)
  5. The method is invoked using the parameters from step 4

When we are using a web service framework/toolkit, all of the steps identified above (i.e. step a to step e) are configurable through code/configuration files. The 2 major configurable/customizable feature that are generally provided by any framework are

  1. Addressing System – (step b and c)
  2. Marshalling System (step d)
We limit our discussion to the addressing system in this article and leave the marshalling system for discussion in a later article.

Addressing is the process of identifying the endpoint when a web service request is received by a server/service. In the case of rpc/literal (refer here) this identification is comparatively simpler since the operation name is already available in the incoming request. In the case of document/literal the task gets a lot more challenging since the incoming soap request contains a document alone(which may or maynot have any direct relation to the endpoint/method) and identification of an operation is difficult. In such a case the identification of the operation is determined by some strategy which is commonly known as addressing strategy. Few of the commonly used strategies are discussed below:

    In the above example, the servlet shown in the figure above would be mapped to /* URLs and receive all incoming requests. Once the request is received, based on the URL it would identify which Endpoint and which operation does it invoke.

  • SOAPActionBasedAddressingStrategy
    – In this strategy, the endpoints are mapped to the incoming 'soapAction' value (present in the header of the protocol of the request e.g. HTTP Header). This value could be pre-decided and mentioned in the WSDL (soap:action tag). Since the 'soapAction' value can be different for different method invocations, the method identification (step c) can be resolved using this method also. It should be noted here that soapAction attribute is not supported under SOAP specification 1.2. Hence this approach is applicable only as long as we use SOAP 1.1.

  • PayloadRootQNameAddressingStrategy
    – In this strategy (most commonly used for document-wrapped style) the operations/endpoints are identified by using the PayloadRootQName of the incoming request. PayloadRootQName signifies the Fully Qualified Name (namespace with tag) of the root tag of payload (the contents of the SOAP Body).
       <tns:DocumentRoot xmlns:tns="" >  
In the above example the PayloadRootQName would be {}DocumentRoot. The system can map such unique QNames to specific methods in endpoints or endpoints with pre-defined methods.

  • WS-AddressingBasedStrategy – WS-Addressing specifies a transport neutral routing mechanism based on a 'To' and 'Action' tag present in the SOAP:Header. The 'To' tag identifies the destination (the endpoint) and the 'Action' tag signifies the operation (the method). This combination is used to identify step b and step c. Both these data can be specified in a WSDL (through the usage of wsa tags) to communicate to a client. The biggest advantage of using ws-addressing is that it is an industry standard specified by WS-I for promoting inter-operability.

     <SOAP-ENV:Envelope xmlns:SOAP-ENV=""  
      <wsa:To S:mustUnderstand="true">http://example/com/fabrikam</wsa:To>  
      <f:Delete xmlns:f="">  

In the above example, each unique Action is mapped to an operation.

In all the above discussed strategies, it is the responsibility of the Server Side toolkit (Axis or JAX-WS or Spring-WS) to use some form of metadata (annotations or xml file) to create a map of "strategy value versus the operation/endpoint" and invoke the correct method when a particular request is received by the toolkit. Once the proper method is identified, the toolkit can then go on to un-marshal the incoming request and invoke the identified method. It should also be noted, that there is no sure shot formula in addressing strategy to decide which has to be applied when. The choice of a strategy id decided based on a number of considerations which includes

  • Which version of SOAP we are using?
  • Which strategies are supported by our framework?
  • What level of scalability and complexity is needed?
Most of the above considerations decide finally what kind of addressing strategy is adopted.However this is not the only consideration, often a number of other considerations such as technical viability, development time and cost of development take precedence.

Sunday, March 6, 2011

SOAP Service using Basic J2EE

In the previous article we discussed about creating a REST service using Basic J2EE. Here we expand our discussion to SOAP services. ABC Inc is now expanding and adding clients by the day. To increase the facilities offered they have now decided to move from REST to SOAP form of Web Services. As a prototype we will try to create the same order service as discussed before in a SOAP service.

    The transition from REST to SOAP has a few features that need to be looked into. A few of them are:

  1. The service operation no longer is decided by the HTTP methods. We need a new addressing strategy.
  2. The data/order can no longer be identified through URL (resourceId), We need to pass the data through XML.
  3. The Body content would now be a standardized SOAP Envelope.
  4. The authentication/encryption and other metadata is sent through SOAP Headers.
There could be a few more features that need to be added. However for the purpose of discussion we shall limit ourselves to the above mentioned points. Thus our new Servlet ( looks something like the following.

 public class SOAPEndpoint extends HttpServlet {  
      protected void doGet(HttpServletRequest req, HttpServletResponse resp)  
                throws ServletException, IOException {  
                // process only POST requests   
           throw new IllegalArgumentException("GET NOT Supported");  
      protected void doPost(HttpServletRequest req, HttpServletResponse resp)  
                throws ServletException, IOException {  
      private void processSOAPMessage(HttpServletRequest req,  
                HttpServletResponse resp) throws IOException {  
           String operation = req.getHeader("soapAction");  
           InputStream inputStream = req.getInputStream();  
           String soapXML = convertStreamToString(inputStream);  
           String payload = extractPayloadFromSOAPXML(soapXML);  
           String soapHeader = extractHeaderBlockFromSOAPXML(soapXML);  
           String orderId = extractOrderIdFromHeader(soapHeader);  
                // get order xml from DB using order id  
 // enclose Order XML in the SOAP:Body and send back a SOAP:Envelope XML.  
           }else if("http://localhost:8080/POSTORDER".equalsIgnoreCase(operation)){  
                // set/store order xml into DB using order id and payload.  

As evident from the above snippet, the main operational method in the endpoint is the processSOAPMessage(HttpServletRequest, HttpServletResponse). The salient features of the method are as given below:

  1. Extract the SOAP Action header from the HTTP Header. This stores the name of the operation to be performed. (This is called the addressing strategy. Different strategies will be discussed later).
  2. Convert the HTTP Body to SOAP XML.
  3. Extract the SOAP Body from SOAP XML which contains the payload/order XML
  4. Extract the SOAP Headers from SOAP XML which contains the order id, authentication data and any encryption data.
  5. Process the business logic.
As is evident from the above steps, process a. through d. would be almost common throughout all implementations of ABC Inc and also for any other implementation code for web services. This "boilerplate" code can be standardized so as to reduce the effort required for development of web services. Examples of such framework or toolkit are Axis, JAX-WS and Spring-WS.

Create REST using Basic J2EE

    We have already seen what a REST Web Service looks like. Let us try to create a sample for the same. Consider an Order Service example for a company ABC Inc. which needs a service (OrderService) for its clients. In its most basic form, it will have 2 operations

  1. To retrieve an order when an order id is passed. (HTTP GET)
  2. To store an order. (HTTP POST)
Any client who wishes to know the details of a particular order can just pass the order id and retrieve the order xml which contains all the order data. Alternatively if we need to create a new order or update an existing order, we can "POST" the data (the complete order xml) and save it. ABC Inc has decided to implement such a service using REST owing to the simplicity of the service.

In a true REST service, all data is viewed as resources. Thus each order (i.e. the order xml) is a unique xml which is identified by a unique URL. (eg. http://localhost:8080/RestOrderService/order/123 corresponds to the order xml against the order id 123, while http://localhost:8080/RestOrderService/order/456 will correspond to the order xml against the order id 456). Depending on the HTTP method (GET/POST/DELETE/PUT) we will either retrieve (GET) or store (POST) the data.

    Thus the service endpoint can be implemented as a Servlet ( targeting all requests with /order/* URL. The Servlet overrides 2 methods the doGet method and doPost method. The doGet method is used to retrieve the XML from the database and stream back to the user. The doPost method is used to send the new order xml to the service. The order xml is contained in the HTTP Body, where it is read and then stored in the database. The sample code is given below.

 public class RestEndpoint extends HttpServlet {  
      @Override // This method is for the get verb.  
      protected void doGet(HttpServletRequest req, HttpServletResponse resp)  
                throws ServletException, IOException {  
           String orderId = req.getPathTranslated();   
 // Authenticate User  
           // retrieve file from DB using id = orderId  
           OutputStream out = resp.getOutputStream();  
           out.write("<?xml version=\"1.0\" > <order><id>1234</id><custId>2122</custId></order>".getBytes());  
           // stream back the response retrieved from DB.  
      @Override // this method is for the post verb  
      protected void doPost(HttpServletRequest req, HttpServletResponse resp)  
                throws ServletException, IOException {  
           String orderId = req.getPathTranslated();  
           InputStream orderXML = req.getInputStream();  
 // Validate Incoming XML  
           //store orderXML stream in DB against the orderId.   

Looks simple right? It is. However before we actually "publish" this service, we need to add a few features like

  1. Validation of incoming XML data
  2. Authentication of User
  3. Buffered streaming of data
  4. Exception Handling
And as our service functionality expands we land up repeating a large part of the code in multiple places (all the above mentioned code). Thus we actually spend a large amount of time in actually performing repetitive tasks like those listed above instead of concentrating on business logic. What if this code, commonly known as "boilerplate code", could be extracted out into an API and we could have someone else do the job for us using either configuration metadata or interceptors. (We can achieve the same by actually ourselves doing the same job however one should realize that it would take more time than writing the business logic itself). This is where toolkits like JAX-WS, Axis and Spring-WS come in. They help us provide the boilerplate code that we need to provide for our service and make our lives simpler. We look at another example using SOAP in the next article where we actually see how hugely repetitive tasks are extracted and moved into frameworks (or toolkits) to make web service development easier.


Friday, March 4, 2011

What are ReST, SOAP, JSON?

    Last week I was having a discussion with a friend regarding his current project, frankly it was a wonderful conversation until he said the following statement to me – "We are NOT using Web Services, We are using ReST". That's when suddenly it all seemed so pointless, if ignorance is bliss then he must be grinning from teeth to teeth. This article I try to bust the myths and misconceptions about ReST and another (not so) popular technology JSON. If people have followed my articles they remember about how we have many layers in the web service stack. IMHO the most powerful layer of the entire stack is the XML Messaging Layer, which deals with the actual data being transferred between client-and-server. The most popular way of transferring data is undoubtedly SOAP, but ReST and JSON are replacements for SOAP in that layer. The remaining layers of the stack can and would be retained as it is. So let us try and understand the differences between them.

ReST – Representational State Transfer is an idea that was conceptualized by Roy Fielding in the year 2000. This deals with the passing of vanilla XML documents (without any SOAP Envelope, Head or Body) as the XML Message over the HTTP network protocol. So put simply if we take the SOAP Payload (or the contents of SOAP Body) and pass it directly over HTTP we get ReST. Is it really that simple? Yes.
If we were to really understand ReST as Fielding conceptualized it, then we need to visualize the service as a URI. For example if I am talking of an order service (maybe books or ticketing or purchase order) , then such a service would be available to me at the following url:, At this service/URL we could perform 4 different operations (CRUD operations) using the HTTP verbs.

OperationSQL VerbHTTP Verb
Create New OrdercreatePUT
Retrieve Existing OrderselectGET
Update Existing OrderupdatePOST
Delete/Cancel existing orderdeleteDELETE

Thus if we want to add a fifth operation then we actually need to create a new service (i.e. a new URL) and then define all 4 or fewer verbs with the operation. Also there is currently no standard way to describe the ReST service (i.e. no IDL/WSDL), so the contents of the request would have to be pre-determined between the client and the server (this is not entirely true since WSDL 2.0 now supports ReST). Another important feature of ReST is it is always stateless, we DO NOT maintain any session between 2 interactions. [Also it should be noted that there is no standard way of providing Security or Reliability in ReST unlike SOAP]. Given so many limitations is ReST actually useful or is it just a fad. Well actually there are a number of places/situations where ReST is useful:
  1. Where the service is not complicated, (i.e. no requirements of security and state)
  2. When high level of scalability/performance is needed. (ReST allows for caching to increase the scalability)
  3. Bandwidth is of importance and needs to be limited. (In SOAP we are passing a lot of extra data all the time, ReST allows for URI based identification of resources)
  4. ReST allows easy aggregation of services.
I think the most popular usage of ReST is in blogging. If any of you have tried to post to a blog site using Microsoft Word, or retrieve a blog using Word, you are using ReST.

JSON – JavaScript Object Notation involves passing data in formatted text (NOT XML) across HTTP protocol. The main advantage of using JSON is that it is directly understood by JavaScript so we do not need to further process the data. JSON is almost exclusively used by AJAX clients and allows for easy serialization/de-serialization of data. The bandwidth is also minimized and speed is increased. The most popular user of JSON is Google. Almost all Google operations (gmail, http chat client, google docs) exclusively use JSON. The popularity of JSON is still very limited and hence I will not discuss too much into it. If you want to know more about it please do a Google search on it and get the required data.
In my next article I try to create a simple web service implementation for ReST and then port it to SOAP.


The following table shows briefly the differences between SOAP,REST and JSON

Message FormatXML inside a SOAP envelopeXMLTEXT
Interface DefinitionWSDL 1.1 , WSDL 2.0WSDL 2.0None

Wednesday, March 2, 2011

WSDL – What, Where and How

    In this article we briefly discuss the Web Service Description Language or WSDL. To know about the basis of WSDL and where they fit in the context of Web Services please read here. WSDL (generically Service Description, SD) is a XML based document that lets us describe the complete information of a service offering. It can contain definitions for the following things related to a web service:

  • Types – Allows for custom data type definition
  • Message – Defines data being sent to, and received from, the web service
  • Operation – Defines one abstract operation supplied by the web service
  • Port Type – Defines an interface, consisting of one or more operations of a web service
  • Binding – Specifies the protocol and data format to be used by a particular port type
  • Port – Defines an web service endpoint by assigning a network address to a binding
  • Service – The grouping of one or more web service endpoint(s)

The picture above shows the basic structure of a WSDL. A WSDL is divided into 2 main parts the abstract definition and the concrete definition. The abstract definition deals with the "What" part of the service, ("What" – What are the operations provided, What are the data needed,). The concrete definition deals with the "Where" and "How" part of a service description (Where is the service located, How is the request shaped and How is the service accessed).

When we try to map a WSDL to an implementation code (like Java) the abstract definition part of the WSDL maps to a set of interfaces which contains all the exposed operations, parameters that need to be passed and the return types. The message elements are mapped to POJO's whose structure is governed by the wsdl:type defined schema. These message types serve as the parameters passed in a method/operation. A single portType element is directly mapped to an Interface (popularly known as Service Endpoint Interface or SEI) which enlists all the operations enclosed within that portType. The operation tag contains the information pertaining to the input to be passed (wsdl:input), return type (wsdl:output) and custom faults (wsdl:fault). The other information that we can gather from the operation tag is whether it is a one-way operation or a request-response model. Based on the above information we can have the basic information of "What" the service has to offer. However we still do not know "How" this information is encoded into a message.

The concrete definition elements of the WSDL structure provides the information regarding "How" should the message be shaped? What element should go in the body and what element in the Head? Which protocol does the service use? Where is the service located? The binding is the most important element when it comes to giving information related to the message structure. The binding tag is mapped to a portType tag and follows the same structure. The only difference is that the binding tag has provision for "extensions". These extensions allow us to bind an implementation to the abstract portType. We can specify the format of the message (SOAP), format of message (which of the parameters are passed in the soap:head or soap:body), the network protocol used for communication. It also provides data regarding the SOAP Encoding. To know more about the syntax of these elements please read here.

Thursday, February 24, 2011

SOAP Processing Model

    In this article we try and take a look at the SOAP Processing Model. Pre-knowledge of SOAP is a must and can be obtained here. The importance of SOAP lies in its ability to be extremely flexible and extensible. These features are provided by the SOAP Processing Model. The SOAP Processing model is the lifecycle of a single SOAP message in isolation from any other SOAP message. It does not maintain any state; perform any correlation or co-ordination between messages.

Initial Sender – The message originator
Ultimate Receiver – The intended recipient
Intermediaries – Processing blocks that operate on the soap message before it reaches the ultimate receiver.

The extensibility and flexibility in SOAP is provided because of the presence of intermediaries which in an unobtrusive manner allow SOAP messages to be processed. The intermediaries work by intercepting messages, performing their function, and forwarding the altered message to the ultimate receiver. In an implementation, intermediaries are like a listener. They intercept the message and process it and then pass it on.

Before we actually look at features like how to identify an intermediary and how to process, let us try to understand why and where does an intermediary come in the picture. Take the example that a SOAP message is being sent from Client A to Server B. Client A's company has a standard disclaimer which is appended to the header in every message. Instead of every client implementing the disclaimer addition, the company has a gateway which intercepts any SOAP message and adds to its header code in the form of disclaimer. Ex.

 <company:Disclaimer>All intended recipients … </company:Disclaimer>  

Such an interceptor could be called as an intermediary. Other common examples of intermediaries would be a logging intermediary, an encryption intermediary, a caching intermediary. Often these intermediaries may want some special input. This input can be provided in the form of targeted header blocks. To target a header block to an intermediary, SOAP provides us with an attribute called soap:actor (in SOAP 1.2 it's called soap:role). This attribute take the value of an URI which is understood by the SOAP intermediary. Ex.

 <soap:Header role=”” mustUnderstand=”1”>  

In the above example, we have added a SOAP header that can help the intermediary to decide whether the disclaimer should be added or not. To make sure that only our intermediary processes the block we have added a role attribute which tells all the intermediaries whether they are supposed to process the header block or not. Also we have added another attribute soap:mustUnderstand. This takes the value of 1 or 0 and tells if the processing of this block is mandatory for the intended intermediary (i.e. the intermediary with whom the role/actor attribute matches). There are two types of intermediaries

  1. Forwarding intermediaries
  2. Active intermediaries
I will not be going into the details of these because knowledge of intermediaries types is not of much importance to most developers except those working on SOAP implementation tollkits (i.e. creating something like Axis). The SOAP processing model however is of great importance because it lays the foundation for an extensible framework which is the base for most web service implementations like Axis and JAX-WS. The basic knowledge of the horizontal extensibility of SOAP due to the presence of intermediaries is a very important concept. There are a few other details regarding SOAP roles which are available here.

Sunday, February 20, 2011

SOAP Encoding

This article is intended for users who understand the syntax of SOAP and want to know more about the power of SOAP. For people who want to know more read here.

The real power of SOAP stems from some of the capability discussed before. Let us try to look at one of them here- "The SOAP encoding mechanism".

Let us first understand the meaning and utility encoding. We understand and appreciate that the power of SOAP comes from its ability to transfer messages in XML format. Encoding is the process of converting any user specific data into XML format. This data could be any of the following:

  1. A remote procedure call (RPC) to a special function/procedure at the remote computer.
  2. A request/order that is valid in the business sense and the remote computer is capable of understanding.
  3. Java objects that are to be transferred to the other end.
  4. A physical document (ex. A mail message or text document) that has to be transferred.
To bring in flexibility in the approach it is very essential that we have a standard way of doing things. We have a standard way of "encoding" the data so that either computer can easily understand the data. This is where the SOAP Encoding comes into picture. The SOAP Encoding allows us to transfer messages of any type within the SOAP envelope. There are two types of encoding

  1. SOAP encoding.
  2. Literal encoding.
SOAP encoding is a set of rules defined in the SOAP specification that tell us how to convert any data into XML format. It follows the concept of SOAP Data Model, which views all data as Object graphs and provides a way to "encode" this graph into XML. Some of the salient features provided by them are:

  1. All data is viewed as nodes which have some value.
  2. The nodes could be connected to other nodes via directional edges called labels.
  3. A node could have incoming-edge, outgoing-edge or both.
  4. A simple value edge with a labeled inbound edge will be serialized into single XML element with label as element name and value as element's text content.
  5. When serializing a node into an XML element, an xsi:type can be added to specify the type of this node.
  6. A compound value node with labeled outbound edges, a data structure, will be serialized into a single XML element with child elements. One outbound edge will be serialized into one child element with element's name equal to edge's label.

Example of a Data Model:

class Product{
     String desc;
     String type;
     String sku;
     double price;
A java class
A graph notation

The above can be represented in XML format as according to the rules defined in SOAP spec as below:

<type xsi:type="xs:string">type of prod</type>
<desc xsi:type="xs:string">desc of product</desc>
<price xsi:type="xs:double">100.00</price>
<sku xsi:type="xs:string">xyz</sku>

This form of encoding has certain disadvantages:

  1. There is no way to tell if the encoding is valid or not (since we can't perform any validation on the message)
  2. The presence of xsi:type is not recommended by WS-I Basic Profile 1.0
  3. SOAP encoding is not supported by WS-I Basic Profile 1.0

"Literal" means a XML document fragment that can be validated against its XML Schema. The biggest advantage of the literal encoding is the possibility to "validate" a XML message at every stage of the message. Literal supports 2 messaging modes:

  1. Document/literal
  2. Document wrapped/literal
  3. RPC/literal
Document/Literal – In the Document/Literal SOAP messaging mode, the Body element of a SOAP message contains an XML document fragment i.e. a well formed XML element that contains arbitrary data and belongs to an XML schema and namespace separate from the SOAP message's XML schema and namespace.

    The term "arbitrary data" signifies that it does not pertain to any standardized (e.g. w3c,ws-i) namespace. It could/should however have some business significance, something that makes logical sense to the requester and servicer. The second thing to note in the Document/Literal encoding is that the SOAP Body can have more than one child elements.

<price xsi:type="xs:double">100.00</price>
<sku xsi:type="xs:string">xyz</sku>
<price xsi:type="xs:double">200.00</price>
<sku xsi:type="xs:string">abc</sku>
<price xsi:type="xs:double">100.00</price>
<sku xsi:type="xs:string">xyz</sku>
<price xsi:type="xs:double">200.00</price>
<sku xsi:type="xs:string">abc</sku>
Document wrapped/literal

Document Wrapped/Literal – This differs from the Document Literal in only one feature namely that it can contain only one child element. If there are to be multiple elements the SOAP encoding style takes care of "wrapping" it. It uses the name of the operation/method to create a parent element for the "Document".

RPC/literal – The RPC/literal style of encoding is used to expose the traditional components as web services. Such components do not explicitly exchange XML data but have methods with parameters and return values. Unlike the above encoding style which may contain any arbitrary data, the SOAP specification fixes some rules for the RPC/literal.

  1. The name of the method to be invoked will be the child element of the SOAP:Body element.
  2. The name of the method appended with "Response" will be the child element of SOAP:Body for the response.
  3. The name of the method parameters will be the child element of the method name in order that they appear.
  4. The response of the method will contain a child called "return".
The biggest difference between the RPC/literal and RPC/encoded however is the use of xsi:type tags which are used with encoding. Also under literal encoding it is possible and advised to have a XSD available to validate the XML request.

Though all the above encoding styles can be used, the one that is most recommended is the Document/Literal with only on child element of SOAP:Body. This provides the complete flexibility with XML messaging and also provides validation mechanisms like XSD. One more very important thing to understand is that these encoding styles make a lot of difference to any API that implements the SOAP specification. For an end-user, there is very little difference between these encoding styles other than to predict the sample request/response for any operation. However if we specify any of the above encoding styles to the API it will tackle the request correspondingly and treat it as per the rules defined above.

SOAP – The Indispensable

In the articles about SOAP, I try not to re-invent the wheel. For syntax of SOAP messages and other "freely and easily available" information I will refer to standard links. I try to explain the real nuances of SOAP messaging which makes it such a simple yet powerful tool.

What makes SOAP indispensable?

Let us try to look at some of the features provided by SOAP specifications that make it a nirvana for almost all web service needs.

  1. It provides a mechanism for defining the unit of communication. When we transfer SOAP we have a single unit of measurement in the form of a SOAP envelope. This "holder" allows the recipient and sender both to know when the message ends and when the next message starts. [via. The SOAP Envelope]
  2. It provides a mechanism for error handling that can allow us to identify the source and cause of error and allows for diagnostic information to be exchanged between the participants. [via. The SOAP fault]
  3. An extensibility mechanism, so that there is no lock-in to a protocol. This in my opinion is the real crown jewel with SOAP which makes it such a unique and indispensible asset. It satisfies two major needs of extensibility i.e. orthogonal extension and de-centralized extensions. [via. SOAP Headers]
  4. Mechanism to bind to any network including (but not limited to) HTTP and support for Remote Procedure Calls (RPC's) and mapping for Documents. [via. SOAP encoding]
To know more about the SOAP envelope syntax refer here.


Tuesday, February 15, 2011

Evolution of web services

        In the last decade there has been more work on web services than on any other open-source effort. The main reason for the same is the fact that apart from having massive support from open-source communities' web services also enjoys un-paralleled support from industry stalwarts like IBM, Microsoft and Sun. This article attempts at having a glance at the evolution of different components involved in web services. We first have a look at the 3 most important components of any web service the Network, the XML Messaging Layer and the IDL.

    Network – There are a number of concerns like security and reliability which are essential for any web service system to succeed. When web services was still at its nascent stage the most preferred way to communicate between web services in a reliable way was JMS. And when people wanted high levels of security they adopted SSL/TLS methodologies of communication. Though there was no inherent disadvantage with using these existing facilities, they severely restricted the flexibility that was expected in a web service environment. JMS networks are not popular across the web while SSL/TLS limit the capability to have selective encryption of messages. As web services evolved, other standards for security and reliability have been developed which can be put on top of the network (in the XML Messaging Layer) allowing us to use HTTP as the default network for web services. A few of them are listed here. "SAML", "User Name Token Profile", "WS-Security", "XACML", "XKMS" and the "Liberty Project" are the well known alternatives for security and "WS-Reliability" is a recommended alternative for reliable messaging.

    XML Messaging – The evolution of XML Protocols started with the First Generation XML Protocols efforts – WDDX (Web Distributed Data Exchange) and XML-RPC (please note the XML part of the acronym). These protocols had limitations of generic extensibility and support for only DTD. These deficits were overcome in SOAP 1.1 specification which was spearheaded by Microsoft and IBM who jointly published it. This is the most popular industry standard even today and is recommended in WSI BASIC Profile 1.1. The latest developments in the field of XML Messaging are SOAP 1.2 and ReST. While SOAP 1.2 improves on the features provided by SOAP 1.1, ReST is a simple and easy way to do XML Messaging. We will discuss these in later articles.

    Service Description – IDL's (Interface Description Language) as a concept have existed since 1994 when IDL's were created for CORBA. The first standard IDL work that was created for Web Services was WSDL 1.1. This specification was the result of a joint effort by Microsoft and IBM and aims at providing a standard way to describe (in XML) network services as a set of endpoints operating on XML messages. Though the industry still largely uses WSDL 1.1, a newer version of IDL (WSDL 2.0) is now available with enhanced features as compared to WSDL 1.1. I will discuss both WSDL 1.1 and WSDL 2.0 in the later sessions.

    Implementations – Since the inception of the Web Services stack in 2001, there have been a number of popular open-source implementation efforts that have tried to implement all or some of the features specified in the Stack. The first ever project was the Apache SOAP project created by IBM and donated to Apache Group in 2001 making it open source. This was followed by the Axis 1.x and JAX-RPC. The JAX-RPC was an implementation by java/Sun to do web services using Java 1.4. The recent years have seen efforts by a number of groups like Spring, Spring-WS, Axis 2, Metro (Glassfish), JAX-WS (Sun's JavaEE5 compliant) etc. In the course of time we will discuss some of the major implementations that are available.


Web services stack de-mystified – Case study

    In my previous article I touched upon the topic of WS-Stack. Here I try to go into details of the stack, trying to de-mystify the complexity that is associated with any web service implementation of the stack. For the case of discussion let us consider a Case Study –

Project: A Stock Ticker Service. – This service is provided by a Stock broker to all his clients who can check the price of any stock in real time using web services.

Requirements: Input of the Stock Ticker Service will be a 4 digit stock code. Output will be the price in Rs.


    With this basic information under the belt let us start to build the representation of such a service. The actual "service" implementation would be a complex method that derives the price based on lots of parameters but for simplicity let us keep the method simple.

public float getStockTicker(String stockCode){
    return 100.50;
    return 0.00;

The above method as discussed in the requirements takes an input of a string stock code and returns the price of the stock. Now if we were to create a sample message for the same using SOAP the message would look like.

<env:Envelope xmlns: env="" >
    <st:getStockTicker xmlns:st="http://stockticker.example/sample" >

And the response to the above would look like the below:

<env:Envelope xmlns: env="" >
    <st:getStockTickerResponse xmlns:st="http://stockticker.example/sample" >

Without going too much into the details of the SOAP let us briefly look at the highlights of SOAP.

SOAP is an XML protocol which contains an Envelope in a namespace defined by "" (henceforth denoted as SOAP: ). The Envelope contains 2 child elements The SOAP:Header and SOAP:Body. The header element contains information dealing with extensibility data while the Body contains information pertaining to the request/response. More details about SOAP would be discussed in the further articles. In the meantime you can read more about SOAP here. The main advantage of SOAP is that it allows us to define a standard structure for the XML message that is being passed. For example when we see the above message we know that the contents of the SOAP:Body tag are of use to the function that we have written.

Now once we know the details of the request and response we need to send it to all the clients who want to use it. For such a small request/response sending a sample request/response and some documentation is enough but if the sample request is much more complicated then we need a standard way to describe the request/response and also the location of the service. This standard way is provided by WSDL. Have a look at the sample WSDL created for the above example.

<wsdl:definitions name="StockQuote" targetNamspace="http://stockticker.example/sample/wsdl" 
  xmlns:wsdl="" xmlns:sample="http://stockticker.example/sample" 
  <wsdl:types> <!-- defines the xml schema for the required input and response -->
    <xsd:schema xmlns:xsd="" 
      <xsd:complexType name="getStockTicker"> <!-- request schema definition -->
          <xsd:element name="stockCode" type="xsd:string" />

      <xsd:complexType name="getStockTickerResponse"> <!-- response schema definition -->
          <xsd:element name="price" type="xsd:float" />

  <!-- message defines the request and response for an operation. -->
  <wsdl:message name="getStockTicker"  >
    <wsdl:part name="request" element="sample:getStockTicker" />

  <wsdl:message name="getStockTickerResponse"  >
    <wsdl:part name="response" element="sample:getStockTickerResponse" />

  <!-- port Type is a collection of operations. This is like an interface definition. 
           The operations that are exposed in a web service are given out here-->
  <wsdl:portType name="StockTickerPortType" >
    <wsdl:operation name="getStockTicker">
      <wsdl:input message="tns:getStockTicker"/>
      <wsdl:output  message="tns:getStockTickerResponse"/>

  <!-- The above information tells us what are the different services 
         that are exposed and what are the request response params -->
  <!-- The next part describes HOW to access the request / response and where to access them -->

  <wsdl:binding name="StockTickerBinding" type="tns:StockTickerPortType">
    <soap:binding style="document" transport="" />
    <wsdl:operation name="getStockTicker">
      <soap:operationsoapAction="" />
      <wsdl:input message="tns:getStockTicker">
        <soap:body use="literal" parts="request" />
      <wsdl:output  message="tns:getStockTickerResponse">
      <soap:body use="literal" parts="response" />

  <!-- In the above mapping we describe that we want the operation getStockTicker to use SOAP binding. 
       The request and response content format i.e. the contents of the SOAP body are also defined.-->

  <wsdl:service name="StockTickerService">
    <wsdl:port name="StockTickerPort" binding="tns:StockTickerBinding">
      <soap:address location="http://stockticker.example/service/getStockTicker" />

  <!-- The wsdl service is used to provide the actual endpoint 
      of the service at which it would be available -->

The comments for the WSDL are provided inline. The basic job of the WSDL is divided into two parts. In the first part the WSDL defined the input and output parameters and also describes the operations that are exposed. In the second part the WSDL describes how the operation can be invoked (what scheme of XML messaging and which network protocol to use) and also the location at which it is available. Now if we are able to provide this sample WSDL to any client. They can understand from the WSDL how to create a sample request and call the service. To do the same the client needs to parse the WSDL, create the SOAP message from Objects , Connect to the server , wait for response , convert response into objects. This entire process is done by any implementation API (ex. Axis, JAX-WS or Spring-WS etc..). The UDDI and BPL are advanced concepts that would be discussed in details later.