Focus SOAP

SOAP, Payload, RPC, WS, JAXB, SOAP 11, 12, what are all these? How are these used in webservice?  Do you have these question in your mind as well?

I recently read a wonderful book titled "Java Webservices Up & Running" by "Martin Kalin" which explains the internal working of SOAP in detail. I thought of sharing my learning in my own words.

What is SOAP?

SOAP - A XML

In any client/server architecture data needs to be passed in some form. Here it is an xml which is nothing about SOAP.

                                           Components of SOAP Message 

SOAP - An Infrastructure [Transport Neutral]

SOAP can be transported through SMTP, MQ, etc. However HTTP remains most popular SOAP transport protocol.

SOAP - A Contract [WSDL]

SOAP provides a contract/agreement in the form of WSDL [webservice description language], where the service, operations, transport, location, etc are described.

In order to implement a working SOAP model you might be assuming that we have to be well versed with Networking, XML [Service call, XML construction/Parsing, etc]  but that is not the case as there are utilities [available in almost all languages] which makes things simpler. 

Java Support for Webservice - [JaxWS]:

Starting Java 1.5 comes bundled with JAX-WS, which provides utility to generate stub, request, response & dependent class from the wsdl, service.  First version of JAX-WS was called JAX-RPC, whose support is limited to RPC style.

Two styles of SOAP Web services:

RPC [Remote Procedure call] - It supports only simple types like String, Integer, etc.

Document - Can support Complex types. The WSDL type section defines the schema of complex types. By default the style is Document.

RPC Style

Server Side Implementation:

1. Service 

Note: The style is explicitly declared as RPC

2. Publish the Service

In general the service are deployed to J2EE server like tomcat, but to keep things simple the above service will be published in a standalone mode [using Endpoint]

3. WSDL

Up on execution java EndpointPublisher, the service starts and the WSDL can be viewed upon hitting the url http://localhost:9090/calc?wsdl

Takeaway sections from WSDL

types          Defines all complex types involved in the service.
                    Here it will be empty, as RPC is meant for simple types

portType    Defines the service signature, equivalent to java interface
                    i.e., method [operation] name, arguments [input] & return [output]

binding      Can be considered as implementation of above interface [portType]. 
                    This also declares transport,  soap style.  Here the transport – http, & style is RPC

service       Holds the URL where service is available

Client side Implementation:

1. Generate client classes from WSDL

WS import utility will generate required client classes from WSDL. Earlier this utility was called as WSDL-to-Java, now it is renamed to wsimport.

    wsimport -p rpcclient -keep http://localhost:9090/calc?wsdl

where:

p    -     package [files will be generated under this package]
keep -  Retain the Source code of client class

This generates the required stub under rpcclient folder 

2. Client

Where CalcServiceService & CalcService are the wsimport generated classes. The service.getCalcServicePort() returns port [ie.,interface] from which we can make the necessary operation

Upon executing the client, Java CalcClient

Result:                                    output 75.0

Here we deal only with Java objects, however behind the screen it’s all SOAP xml. Jax-Ws takes care of binding java & xml using JAXB [Java API for XML Binding].

Below is the SOAP Request/Response of the above service/client captured using tcpmon. The soap webservice can be invoked directly with soap request with any soap supported tool like soap ui, etc.

Document Style

Server Side Implementation:

1. Service - Remove Style from Service [By default the style is document] 

2. Wsgen utility generates the java types required by publisher to generate WSDL [can be ignored in ede's like eclipse]

       wsgen -cp . learning.websrvc.soap.service.doc.calc.CalcService

3. Publish the DOC service [same like RPC]

4. WSDL View 

Up on execution java EndpointPublisher, the service starts and the WSDL can be viewed upon hitting the url http://localhost:9090/calc?wsdl

One of the key difference between RPC & DOC wsdl is the type section

Here it defines all complex types involved. The complex types can be directly embedded in wsdl or the schema can be imported in to the type section.  

Client Side Implementation: [The same as RPC]

1. Generate client classes from wsdl 

        wsimport -p docclient -keep http://localhost:9090/calc?wsdl

2. Client

Document style is not limited to simple types, this can support complex types as well. WSDL type section holds all complex types involved in service. 

Here Document client looks similar to RPC style i.e., parameterized invocation. This type of client is called Wrapped Client - where the req/response is wrapped to look like parameterized call. There is another type called UnWrapped/BARE client – where the request/response are exposed as it is as single object. These two types differs only on the client side, the soap req/resp does not have any change nor the server side. Wrapped is by default and is commonly used.

UnWrapped/Bare Client

1. Explicitly declare the Wrapper False, in a file name "custombinding.xml", and pass this to wsimport

    wsimport -p rpcclient -keep http://localhost:9090/calc?wsdl –b custombinding.xml

2. Client

Here you can see, the request & response is exposed as it is in SOAP in to a single object Add & AddResponse respectively.

Handlers:

Just like filters in servlet we have handlers in SOAP, which can intercept request, response at both client & service side. Handlers are classified into two types 

1. SOAP Hander -     Has access to SOAP Envelope [Header + Body]

2. Logical Handler - Has access only to the payload [Body]

Handler chain can be configured in the order it needs to get invoked on every in/out. I have seen usecase where the authentication, logging are done at the handlers level. Incase of any failure the handlers can throw Exception [An exception class with getFaultMessage() ]

There are more to it. But I will wrap up here. I believe this will be useful piece of info for you as well. Please don’t forget to leave your feedback, suggestion, improvement comments. 

Thank you!