WebLogic Pro - Solve SOA Integration Problems with SAAJ

Solve SOA Integration Problems with SAAJ
The SAAJ API proves its mettle in the SOA and integration space
by Anbarasu Krishnaswamy

October 13, 2004

As service-oriented architecture (SOA) and service-oriented integration (SOI) see widespread adoption, one need has become obvious: businesses need to integrate systems and allow consumers to access services using a standards-based approach. SOA is an architecture paradigm where reusable business logic is exposed as a collection of services with standards-based, well-defined interfaces and accessed in a loosely coupled fashion. SOA has gained popularity in solving enterprise integration problems because of vendor support of the Web services standards and the relative ease of integrating disparate systems using this standards-based software.

Java-based middleware and enterprise application integration (EAI) products have been available for a while now, and many companies use this technology in some form or another. Although services are being developed and provided on the Java platform, there is also a subtle need to consume services from Java-based applications. SOAP with Attachments API for Java (SAAJ) helps the consumption of services by offering a standard API to access services.

Several Java-based APIs are available to access services. Some of these include SAAJ, Java API for XML-based RPC (JAX-RPC), and the Web Services Invocation Framework (WSIF). SAAJ provides APIs to build service consumers as well as providers. Let's take a look at how to use SAAJ to develop consumers of Web services in SOA. We will demonstrate a WebLogic Integration composite process that orchestrates a service to get zip code by city, a service to get the temperature for the zip code, and a sample SAAJ client that consumes that service.

What is SAAJ?
SAAJ is an API specification to implement XML-based messaging using the SOAP protocol in loosely coupled software systems. As the name suggests, it supports SOAP messages with attachments.

Many of you have heard about Java API for XML Messaging (JAXM) and may be wondering what happened to it. The idea behind JAXM 1.0 was to enable developers to write business applications that support messaging standards based on SOAP by providing messaging and SOAP APIs. As JAXM evolved to version 1.1, the SOAP APIs (javax.xml.soap) were separated into SAAJ 1.1 specifications and JAXM 1.1, which contains only messaging-based APIs (javax.xml.messaging). The current version of SAAJ is 1.2. WebLogic Server 8.1 SP2 supports SAAJ 1.1 specifications.

SAAJ 1.2 API primarily has the javax.xml.soap package, which provides abstraction for SOAP messages with Multipurpose Internet Mail Extensions (MIME) attachments. This API provides methods to create point-to-point connections to end points, to create and manipulate SOAP messages and attachments, and to receive and manipulate SOAP faults.

Although you have several technology choices when developing enterprise applications, some are better suited for specific problems. It is important to choose the right tool.

What are some reasons for choosing SAAJ? It is naturally suited for document-based Web services that are either synchronous or asynchronous. It is also simple to use, it helps you integrate with any Web service from the Java world, and it extends natural support for document-style Web service communication. It also supports XML messaging over a standards-based interface and is, itself, widely supported by vendors.

Writing Clients
Listing 1 shows a simple consumer, written using SAAJ, that accesses a synchronous WebLogic integration process to get the temperature at a given city. The complete project can be downloaded from www.WebLogicPro.com. Let's discuss the steps required to complete the project.

First of all, create a SOAP connection. The SAAJ client can establish a point-to-point synchronous connection by creating a SOAPConnection using the SOAP Connection Factory. This connection provides methods to synchronously invoke a service. Next, create a new instance of message factory using MessageFactory.newInstance(). Then create a SOAPMessage using the message factory createMessage() method. This creates a message with no content.

SOAPMessage may have a SOAPPart to contain the XML SOAP message and an AttachPart for binary/text attachments. Get the SOAPPart by calling the getSOAPPart() method on the message. Create the attachment part using the createAttachPart() method of the message. The attachment can be set using the setContent() method of the AttachPart. The first argument is the attachment and the second argument is the content type.

Now, set the content of the SOAPPart using the setContent() method that takes a Source object. This example shows setting the content from a String using StringReader and StreamSource objects, but the source could be anything. For example, if you are reading your input from a file, you can use a FileInputStream to set the content.

Save the changes to the message by calling the saveChanges() method on the SOAPMessage. Changes will also be saved automatically when the connection "call" method is invoked, which is the next step. This "call" method takes as argument (accepts) the message and also the end point. Any synchronous response from the service will be returned in the SOAPMessage return parameter. If the service is an asynchronous service, the client should ignore the SOAPMessage returned.

Finally, check for any faults returned by the service. Close the connection by calling the close() method. Any SOAP-level exceptions will be thrown as SOAPException.

SOAP Fault Handling
The SOAP specification defines a standard way to convey exceptions back to the consumer using SOAP Fault. Although the structure of SOAP Fault varies significantly between SOAP 1.1 and SOAP 1.2, each of these versions does have some common elements. More information on SOAP Fault can be found at www.w3.org/TR/2003/REC-soap12-part1-20030624/#soapfault.

SAAJ provides APIs to find out if a SOAP fault occurred and if so, provides ways to access the fault elements like fault code, fault string, fault actor, and fault detail. SOAPBody has these methods:

hasFault()—returns true if a SOAP Fault is returned
getFault()—returns the SOAPFault object.

SOAPFault has these methods to manipulate the fault object:

getFaultCode()—returns the fault code in the SOAP fault
getFaultString()—returns the fault string
getFaultActor()—returns the fault actor to indicate who caused the fault to happen
getDetail()—returns the fault detail element.

Listing 1 shows an example of where the fault elements are logged when there is a fault.

WebLogic Integration Process
Figure 1 shows the Get Temperature composite process. This process orchestrates the following services to get the temperature in a given city and state:

Accepts a city and state in a location XML document
Gets a list of zip codes and states of all the cities with the given name using the U.S. Zip Web service (www.xmethods.net)
Uses a transformation service to get the zip code of the city in the specific state provided
Invokes the weather-temperature service to get the temperature for the zip code (www.xmethods.net)
Transforms the result into the location output document and returns it
Handles any exceptions gracefully.

Listing 2 shows how this service is invoked using the method shown in Listing 1. The process end point URL is passed to the invokeService() method along with the input XML document string.

SAAJ could be a very useful API in the SOA and integration space. Some of the applications of SAAJ include service testing frameworks and service invocation libraries. We have shown how to write consumers using SAAJ and created a sample client to access a WebLogic Integration Get Temperature composite process. Apply this example to your own projects and get SAAJ working for you.

About the Author
Anbarasu Krishnaswamy has been working for BEA Professional Services for more than five years. He has extensive experience in WebLogic Platform and Tuxedo products in addition to Java, C/C++, and OOAD. His interests include SOA, Web services, and EAI. He has published many articles on Web services and WebLogic Integration. He can be reached at anbarasu@bea.com.