...

This article takes you through the some of basic concepts involved in SAAJ Messaging. The goal of this tutorial is to give a brief overview about the terminology involved with SOAP (or SAAJ) messages.

We will also develop a basic SAAJ client that accesses a deployed web service by sending SOAP messages. By using SAAJ we will working at XML level of messages which means that we need to create SOAP request messages and parse the SOAP response messages for results.

To run this tutorial, as a minimum you will be required to have installed the following prerequisite software.

• Sun JDK 5.0+ (J2SE 1.5)
• Apache Geronimo 2.x
• Eclipse IDE for Java EE Developers - Europa release
• Geronimo Eclipse Plug-in 2.x

The steps that we follow in due course of the tutorial are:

...

What is SAAJ?

SAAJ stands for SOAP with Attachments API for Java. SAAJ messages follow the SOAP standards, which prescribe the format for messages. With SAAJ API one can create XML messages that conform to SOAP 1.1 or 1.2 specification by simple making Java API calls.

SAAJ Messages and Connections

Messages

The two main types of SOAP messages are those that have attachments and those that do not.Messages sent using the SAAJ API are called request-response messages

...

The following outline shows the very high-level structure of a SOAP message.

• SOAP message
  • SOAP part
    • SOAP envelope
      • SOAP header (optional)
      • SOAP body
  • Attachment Part
    • MIME Headers
    • Content

...

Connections

All SOAP messages are sent and received over a connection. With the SAAJ API, the connection is represented by a SOAPConnection object, which goes from the sender directly to its destination. They are sent over a SOAPConnection object with the call method, which sends a message (a request) and then blocks until it receives the reply (a response).

Develpoing a SAAJ Client

...

The SAAJ client that we are going to develop is targeted towards the web service that we deployed in the Developing a JAX-WS POJO Web Service. Although this model will work any web service if we change the request message according to the WSDL file of deployed service.

...

Creating a Dynamic Web Project

• Create a Dynamic Web Project
  • Select File->New->Project (or Ctrl+N)
    
    
  • In the popup window, select Web->Dynamic Web Project category (or type dynamic in Wizards' input field so it's left alone) and click Next
    
    Image Added
    
    
  • Type jaxws-saaj-converterclient as the Project Name and click Next twice.
    
    Image Added
    
    
  • Modify the Group Id to org.apache.geronimo.samples.jaxws.saaj and the Artifact Id to jaxws-saaj-converterclient.
    
    Image Added
    
    
  • Click Finish

Adding code to send and receive SOAP messages

• Right Click the jaxws-saaj-converterclient, and Select New->JSP
  
  
• Name the jsp as index.jsp and click Finish
  
  Image Added
  
  
• Add the following code to the index.jsp

...

• Right click again and add a Servlet named ConverterHandler
  
  Image Added
  
  
• Add the following code to ConverterHandler.java

...

• Let us have a brief look at the code that we added in ConverterHandler.java
  • createSOAPMessage() - Here we will create a new SOAP message from MessageFactory instance and set the SOAP body of message according to the request and format needed by WSDL file.
    SOAP request message that is returned by createSOAPMessage for operation ("dollarToRupees") and argument ("23") looks like this: SOAP Request Message <?xml version="1.0" encoding="UTF-8"?> <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"> <soapenv:Body> <ns1:dollarToRupees xmlns:ns1="urn:http://jaxws.samples.geronimo.apache.org"> <arg0>23</arg0> </ns1:dollarToRupees> </soapenv:Body> </soapenv:Envelope>
  • returnResult() - This function processes the SOAP response message sent by the Web service and returns the result. This function uses call method over a SOAP Connection to send the request and receive the response.
    SOAP response message that is returned by Web Service for the above SOAP Request message looks like this: SOAP Response Message <?xml version="1.0" encoding="UTF-8"?> <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"> <soapenv:Header/> <soapenv:Body> <dlwmin:dollarToRupeesResponse xmlns:dlwmin="http://jaxws.samples.geronimo.apache.org"> <axis2ns1:return>933.34</axis2ns1:return> </dlwmin:dollarToRupeesResponse> </soapenv:Body> </soapenv:Envelope>
  • Here the SOAP Response is parsed by using the functions present in SAAJ API. Also observe that call is a blocking call which means that it will continue waiting until it receives a response.

This concludes the development section of our web based client.

Deploying and Testing the Web Client

Deploy

• Right click on the Apache Geronimo Server Runtime present in the servers view and select Add and Remove Projects
  
  
• Add jaxws-saaj-converterclient to configured projects list and then click Finish
  
  Image Added
  
  
• Wait for some time till the server status changes to Synchronized

Testing

• Right click the index.jsp present under WebContent directory of our project and select Run As->Run On Server
  
  
• In the popup, check the check box Always use this server when running the project and then click Finish
  
  
• Now Eclipse will try to open the jsp in a web browser which shows you a form to enter amount in Dollars.
  
  
• Enter any amount and press submit, the jsp should display the result that is returned by the web service.
  
  Image Added
  
  

This completes our development and deployment of a basic SAAJ client that works at XML level by sending SOAP request messages to the deployed Web Service.