Tutorials : Using SOAP with Java :

by Samudra Gupta

Using SOAP with Java –part1

Hello welcome to the first part of my 3 series articles on developing SOAP based applications using Java. This series is not a detailed description of SOAP protocol but just a quick-start tutorial to demonstrate how we can use Java and SOAP together. In the fist part I will cover the basic anatomy of SOAP, the installation of Apache SOAP 2.2 and configuration issues with Jakarta Tomcat 3.2.1 and develop, deploy and execute a very basic SOAP application. In part 2 of the series, I will develop a more complex Java bean based SOAP service and in part 3, I will give you an idea about other complex aspects of SOAP. Right then, lets begin.

Anatomy of SOAP

Simple Object Access Protocol or SOAP is basically designed to provide a very simple and lightweight mechanism to exchange structured information in a decentralised and distributed environment. It is in essence a model for encoding data in a standardised XML format to be used in a variety of situations such as Messaging and Remote Procedure Calls (RPC). The SOAP consists of three essential parts:

• Envelope: This is the top level XML element or the root element in a XML encoded SOAP message. Envelope contains or may necessarily contain the following information such as: the recipient of the message, the content of the message and the processing instruction of the message.
• Encoding rules: The encoding rules specify the way that the application defined data-type instances will be exchanged.
• RPC: The Remote Procedure Call or RPC representations define a convention for representing the Remote Procedure Calls and the Responses to them.

In order to understand the three parts of the SOAP message let us consider an example SOAP message:

POST /StockQuote HTTP/1.1
Host: www.stockquoteserver.com
Content-Type: text/xml; charset="utf-8"Content-Length: nnnn
SOAPAction:"Some-URI" 

<SOAP-ENV:Envelope xmlns:SOAP-
ENV="http://schemas.xmlsoap.org/soap/envelope/" 
 SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
   <SOAP-ENV:Body>
    <m:GetLastTradePrice xmlns:m="Some-URI">
        <symbol>DIS</symbol>       
    </m:GetLastTradePrice>
   </SOAP-ENV:Body >
</SOAP-ENV:Envelope>

The above example shows a typical SOAP message in a HTTP request binding. The Envelope element is namespace qualified (SOAP-ENV) in order to separate it from any other application specific identifiers. This element also contains the information about the namespace encoding. The immediate child element of the Envelope in this example is the Body Element. This element MUST be present in a SOAP message and holds the information about the name of the Remote Procedure (GetLastTraderPrice) to be invoked and also it encodes the parameters required by the Remote Procedure. In this particular message the Remote Procedure requires the name of the company (DIS) of which to retrieve the last trade price. Optionally, the Body element contains information about any error occurred during the RPC and encoded in a Fault element. The Fault element contains the error/status information with a SOAP message and if present can appear only once as a child element of the Body element.

In complex cases of SOAP messages, the Envelope element may contain another child element named Header .If this element is present in a SOAP Envelope then it must be the immediate child of the Envelope element. The Header element can typically hold information regarding authentication, transaction management etc. But in our particular example, we would not be using this header information. Similarly, a SOAP Response Document will have a similar structure.

HTTP/1.1 200 OK
Content-Type: text/xml; charset="utf-8"Content-Length: nnnn
<SOAP-ENV:Envelope  xmlns:SOAP-
ENV="http://schemas.xmlsoap.org/soap/envelope/"
  SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/ >
    <SOAP-ENV:Body>
       <m:GetLastTradePriceResponse xmlns:m="Some-URI">
           <Price>34.5</Price>
       </m:GetLastTradePriceResponse>   
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

The Envelope element contains the Body element, which in turn contains the requested information, or a fault string, should there be any fault generated during the service call.

Setting up the environment

After you have downloaded the binary distribution of the SOAP version 2.2, unpack it in some folder within your system. Although SOAP can work with any Servlet/JSP container, we will choose Jakarta tomcat 3.2.1 for our model. Once you have the tomcat set up in your system,

• Go to the /lib directory of your soap installation and copy the soap.jar file to the /lib directory of the tomcat installation.
• Get xerces.jar file and place it in the /lib directory of the tomcat installation. Now here is a point. Tomcat already comes with a parser.jar and jaxp.jar. So there will be a potential conflict with the newly installed xerces.jar. To avoid this:
• Edit the tomcat.bat file and go to the section where the classpath is being set. Put he classpath of xerces.jar in front of them so that xerces.jar gets loaded first in the classpath.
• Place the soap.war file from the lib directory of the SOAP binary distribution and place it in the /webapps directory of the tomcat. Once you restart tomcat, this soap.war file will be expanded.
• Now restart tomcat.

Also in order that you can use the command line utility to deploy and manage the services and also run the SOAP client that we will develop, the system CLASSPATH environment variable must include the following .jar files:

• soap.jar
• activation.jar
• mail.jar
• xerces.jar

How to Add Java Applets to Your Site

New on the Java Boutique:

New Article:
Struts in Action
The newest book excerpt from "Struts in Action" covers validators, bundles and configuration files.
... [more articles]

New Tutorial:
Converting XML documents to Java objects with Castor XML
If you're working with XML documents, and your focus is more on the contents of the documents, and not so much on the XML structure, then Castor XML may be what you're looking for. This month Keld Hansen focuses on the conversion capabilities of Casto XML.
... [more Tutorials]

Elsewhere on internet.com:

WebDeveloper Java
Lots of Java information on webdeveloper.com

WDVL Java
Thorough Java resource at the Web Developer's Virtual Library.

ScriptSearch Java
Hundreds of free Java code files to download.