New look of WSO2 WSAS SOAP Message Tracer

Soap Tracer may not be a strange tool if you are familiar with WSO2 Web Services application server (WSAS). However, you will notice a new look and improved graphical representation of SOAP messages in Soap Tracer shipped with WSAS 3.0.
You will experience the difference with the newly released WSAS-3.0-beta1

- Download and unzip the binary distribution
- Log in to management console with user name and password, admin/admin
- Select Soap Message Tracer in the left menu
- Change the status to ON
- Invoke a service (Simply run tryit with the default HelloService)
- Go back to Soap Message Tracer and see the request and soap messages

How to add a custom SOAP header to the request using AXIOM

Suppose you want to add the following SOAP header block to your web service request message.
<myNS:header xmlns:myNS="http://ws.org">
This is a custom soap header
</myNS:header >

There are different approaches to add user defined headers to the request soap messages. Lets see how it could be done using AXIOM in simpler way.
In this example we are going to invoke Axi2 default version service with adding a custom soap header in to the request.

Pre-requisites
Download and install Apache Axis2
Install Apache Tcpmon

Step 1

Start Axis2 server by running AXIS2_HOME/bin/axis2server.bat{sh}
Go to http://localhost:8080. You will see that the default version service is deployed there.

Step 2

Now, we need to generate client stubs. Go to AXIS2_HOME/bin and run wsdl2java.bat{sh} with the following parameters.
WSDL2Java -uri http://localhost:8080/axis2/services/Version?wsdl -o out -uw

The client stubs will be generated in a directory called "out".

Now, write a client importing the generated stub classes as follows(You can easily create a project in Eclipse using the generated Build.xml)

import java.rmi.RemoteException;
import org.apache.axiom.om.OMAbstractFactory;
import org.apache.axiom.om.OMElement;
import org.apache.axiom.om.OMFactory;
import org.apache.axiom.om.OMNamespace;
import org.apache.axis2.AxisFault;
import sample.axisversion.ExceptionException0;
import sample.axisversion.VersionStub;


public class CustomSoapHeaderClient {

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

String url = "http://localhost:8090/axis2/services/Version";
VersionStub stub = new VersionStub(url);

OMFactory omFactory =OMAbstractFactory.getOMFactory();
OMNamespace omNamespace = omFactory.createOMNamespace("http://ws.org", "myNS");
OMElement header = omFactory.createOMElement("header", omNamespace);
header.setText("This is a custom soap header");
stub._getServiceClient().addHeader(header);

try {
System.out.println(stub.getVersion());
} catch (RemoteException e) {
e.printStackTrace();
} catch (ExceptionException0 e) {
e.printStackTrace();
}
}


}

Note the highlighted code which creates the custom soap header.

Step 3

We can visualize the soap request using Tcpmon. Therefore open tcpmon and configure listen port in 8090 and target port 8080.
Compile and run the above client. You will see the following message in request pane of Tcpmon.

<?xml version='1.0' encoding='UTF-8'?>
<soapenv:Envelope xmlns:soapenv="http://www.w3.org/2003/05/soap-envelope">
<soapenv:Header>
<myNS:header xmlns:myNS="http://ws.org">This is a custom soap header</myNS:header>

Short notes on SOAP messaging

SOAP is the fundamental messaging framework for web services. It is the first piece of thing you should learn and understand when starting to deal with web services. I think most of the readers of this blog possess a good understanding of the concepts and techniques of SOAP. However, this blog is not restricted to folks who are working with SOA and web services. QA testers and non-web service specific developers are also a part of target audience.
I thought to describe a set of commonly used terms in SOA and web services in fairly simple and non-technical user oriented manner so that most novice users get benefit from it.

SOAP defines a standard message format based on XML. It provides a mechanism to bind messages to different network protocols. It also defines a processing model to serialize/de-serialize messages.

Structure of a soap message

<Envelope>
<Header>
<headerBlock1/>
</Header>
<Body>
<payload/>
</Body>
</Envelope>

SOAP message consists of 3 basic elements.
Soap Envelope

Body

Header

SOAP envelope should have one mandatory body element which contains the message payload.
One soap message can have zero or more header elements. The SOAP header is an extension that provides a way for information to be passed within a SOAP message that is not
part of the business message payload. Soap headers include information that controls QOS (quality of service) such as Security and reliable messaging.

Soap nodes are intended to receive or send soap messages in the message transmission path. If a node transmits a message it is known as a SOAP Sender. If it receives a message, then it is a SOAP Receiver. If a node does both transmitting and receiving of soap messages, then it is called a SOAP Intermediary.

The Soap sender which builds the message initially is said to be initial SOAP sender. The final target of the message is Ultimate Soap receiver. It is expected to process the payload of soap message.

There is an important attribute you may have seen in soap header elements. it is the "mustUnderstand" attribute. If this attribute is set to true, the target node should process the SOAP header block. If this attribute is false or not available, then target SOAP node can ignore processing the block.

SOAP fault is a model to handle exceptions when an error occurs in processing a soap message.
Soap fault is included in the body element of soap message.
Soap fault should have a mandatory fault code element. There are five fault codes defined in SOAP 1.1 specification.

VersionMismatch: message does not comply with the SOAP version
Sender: message was incorrectly generated when receiving node processing it
Receiver: Receiving node cannot process the message
MustUnderstand: The targeted node cannot understand the soap header
DataEncodingUnknown: The target node cannot understand the data encoding mechanism of the message

SOAP bindings allow a SOAP message to be transmitted over different transport protocols such as HTTP and SMTP.
In a web service interaction, the request and response SOAP messages can be sent via two different transports.

If you can understand the commonly used terms I explained above, you should be able to follow and explore more with the detailed reading materials published on various places.

Stay tuned. I will post a set of commonly used terms of WSDL soon.