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.

  1. Sun JDK 6.0+ (J2SE 1.6)
  2. Eclipse IDE for Java EE Developers, which is platform specific
  3. Apache Geronimo Eclipse Plugin 2.1.x
  4. Apache Geronimo Server 2.1.x

    Geronimo version 2.1.x, Java 1.5 runtime, and Eclipse Ganymede are used is used in this tutorial but other versions can be used instead (e.g., Geronimo version 2.2, Java 1.6, Eclipse Europa)

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


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

Outline of SOAP message

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


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

Web Service Deployed

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

Adding code to send and receive SOAP messages

index.jspsolid <%@ page language="java" contentType="text/html; charset=ISO-8859-1" pageEncoding="ISO-8859-1"%> <html> <head> <title>Converter</title> <meta content="text/html; CHARSET=iso-8859-1" http-equiv="Content-Type"> </head> <body> <center> <h3>This from invokes a Web Service.</h3> <br> Please type an amount and click submit to see the result. <br> <form action="index.jsp">Amount: <input type="text" name="amount"> <input type="submit" value="Submit"></form> <br> <jsp:include page="ConverterHandler"></jsp:include></center> </body> </html> ConverterHandler.javasolid package abc; import java.io.IOException; import java.io.PrintWriter; import java.util.Iterator; import javax.servlet.ServletException; import javax.servlet.http.HttpServletRequest; import javax.servlet.http.HttpServletResponse; import javax.xml.soap.MessageFactory; import javax.xml.soap.SOAPBody; import javax.xml.soap.SOAPConnection; import javax.xml.soap.SOAPConnectionFactory; import javax.xml.soap.SOAPElement; import javax.xml.soap.SOAPEnvelope; import javax.xml.soap.SOAPException; import javax.xml.soap.SOAPMessage; import javax.xml.soap.SOAPPart; import org.w3c.dom.Node; public class ConverterHandler extends javax.servlet.http.HttpServlet implements javax.servlet.Servlet { static final long serialVersionUID = 1L; public ConverterHandler() { super(); } protected void doGet(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException { String dollars = request.getParameter("amount"); if (dollars != null && dollars.trim().length() > 0) { String rupees = null, euros = null; try { rupees = returnResult(createSOAPMessage("dollarToRupees", dollars)); euros = returnResult(createSOAPMessage("rupeesToEuro", rupees)); } catch (SOAPException e) { // TODO Auto-generated catch block e.printStackTrace(); } PrintWriter out = response.getWriter(); out.println("<br><br><br>"); out.println(dollars + " Dollars equals to " + rupees + " Rupees"); out.println("<br>"); out.println(rupees + " Rupees equals to " + euros + " Euros"); } } protected void doPost(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException { doGet(request, response); } public SOAPMessage createSOAPMessage(String operation, String arg) throws SOAPException { String urn = "http://jaxws.samples.geronimo.apache.org"; MessageFactory messageFactory; SOAPMessage message = null; messageFactory = MessageFactory.newInstance(); message = messageFactory.createMessage(); SOAPPart soapPart = message.getSOAPPart(); SOAPEnvelope envelope = soapPart.getEnvelope(); SOAPBody body = envelope.getBody(); SOAPElement bodyElement = body.addChildElement(envelope.createName( operation, "ns1", "urn:" + urn)); bodyElement.addChildElement("arg0").addTextNode(arg); message.saveChanges(); return message; } public String returnResult(SOAPMessage message) throws SOAPException { String destination = "http://localhost:8080/jaxws-converter/converter"; SOAPConnectionFactory soapConnFactory = SOAPConnectionFactory .newInstance(); SOAPConnection connection = soapConnFactory.createConnection(); SOAPMessage reply = connection.call(message, destination); SOAPPart soapPart = reply.getSOAPPart(); SOAPEnvelope envelope = soapPart.getEnvelope(); SOAPBody body = envelope.getBody(); Iterator iter = body.getChildElements(); Node resultOuter = ((Node) iter.next()).getFirstChild(); Node result = resultOuter.getFirstChild(); connection.close(); return result.getNodeValue(); } }

This concludes the development section of our web based client.

Deploying and Testing the Web Client



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.