SOAP with Attachments API for Java interface

WAS v8.5 > WebSphere applications > Web services > Web services > SOAP
SOAP with Attachments API for Java interface

The SOAP with Attachments API for Java (SAAJ) interface is used for SOAP messaging that provides a standard way to send XML documents over the Internet from a Java programming model. SAAJ is used to manipulate the SOAP message to the appropriate context as it traverses through the runtime environment.

Best practice: IBM WebSphere Application Server supports the JAX-WS programming model and JAX-RPC. JAX-WS is the next generation web services programming model extending the foundation provided by JAX-RPC. Using the strategic JAX-WS programming model, development of web services and clients is simplified through support of a standards-based annotations model. Although JAX-RPC and applications are still supported, take advantage of the easy-to-implement JAX-WS programming model to develop new web services applications and clients. best-practices
The Java API for XML-Based RPC (JAX-RPC) programming model supports SAAJ 1.2 to manipulate the XML.
The JAX-WS programming model supports SAAJ 1.2 and 1.3. SAAJ 1.3 includes support for SOAP 1.2 messages.
The differences in the SAAJ 1.2 and SAAJ 1.3 specification can be reviewed in the topic "Differences in SAAJ versions."
How are messages used in web services?
Web services use XML technology to exchange messages. These messages conform to XML schema. When developing web services applications, there are limited XML APIs to work with, for example, Document Object Model (DOM). It is more efficient to manipulate the Java objects and have the serialization and deserialization completed during run time.
Web services uses SOAP messages to represent remote procedure calls between the client and the server.
Typically, the SOAP message is deserialized into a series of Java value-type business objects that represent the parameters and return values. In addition, the Java programming model provides APIs that support applications and handlers to manipulate the SOAP message directly. Because there are a limited number of XML schema types that are supported by the programming models, the specification provides the SAAJ data model as an extension to manipulate the message.
To manipulate the XML schema types, you need to map the XML schema types to Java types with a custom data binder.
The SAAJ interface
The SAAJ-related classes are located in the javax.xml.soap package. SAAJ builds on the interfaces and abstract classes and many of the classes begin by invoking factory methods to create a factory such as SOAPConnectionFactory and SOAPFactory.
If Java security is enabled, and permissions to read the jaxm.properties file is not granted, when a SOAPFactory instance is created through a call to javax.xml.soap.SOAPFactory.newInstance(), or a MessageFactory instance is created through a call to MessageFactory.newInstance(), a SecurityException exception occurs, and the following exception is written to the system log:
Permission:

      /opt/IBM/WebSphere/AppServer/java/jre/lib/jaxm.properties : access denied 
(java.io.FilePermission /opt/IBM/WebSphere/AppServer/java/jre/lib/jaxm.properties
read)

Code:

     com.ibm.ws.wsfvt.test.binding.addr1.binder.AddressBinder  
in  {file:/opt/IBM/WebSphere/AppServer/profiles/AppSrv01/installedApps/
ahp6405Node01Cell/DataBinding.ear/address1.war/WEB-INF/lib
/addressbinder1.jar}

Stack Trace:

java.security.AccessControlException: access denied (java.io.FilePermission
/opt/IBM/WebSphere/AppServer/java/jre/lib/jaxm.properties read)
.
The SOAPFactory ignores the exception, and continues on to the next means of determining which implementation to load. Therefore, we can ignore the log entry for this security exception.
Because this product uses the SOAPFactory to support other web services technologies, such as WS-Addressing (WS-A) , WS-Atomic Transaction (WS-AT), and WS-Notification, we can ignore this SecurityException in any web services application where Java security is enabled.
The most commonly used classes are:

SOAPMessage: Contains the message, both the XML and non-XML parts
SOAPHeader: Represents the SOAP header XML element
SOAPBody: Represents the SOAP body XML element
SOAPElement: Represents the other elements in the SOAP message

Other parts of the SAAJ interface include:

MessageContext: Contains a SOAP message and related properties
AttachmentPart: Represents a binary attachment
SOAPPart: Represents the XML part of the message
SOAPEnvelope: Represents the SOAP envelope XML element
SOAPFault: Represents the SOAP fault XML element

The primary interface in the SAAJ model is javax.xml.soap.SOAPElement, also referred to as SOAPElement. Using this model, applications can process an SAAJ model that uses pre-existing DOM code. It is also easier to convert pre-existing DOM objects to SAAJ objects.
Messages created using the SAAJ interface follow SOAP standards. A SOAP message is represented in the SAAJ model as a javax.xml.soap.SOAPMessage object. The XML content of the message is represented by a javax.xml.soap.SOAPPart object. Each SOAP part has a SOAP envelope. This envelope is represented by the SAAJ javax.xml.SOAPEnvelope object. The SOAP specification defines various elements residing in the SOAP envelope; SAAJ defines objects for the various elements in the SOAP envelope.
The SOAP message can also contain non-XML data that is called attachments. These attachments are represented by SAAJ AttachmentPart objects that are accessible from the SOAPMessage object.
A number of reasons exist as to why handlers and applications use the generic SOAPElement API instead of a tightly bound mapping:

The web service might be a conduit to another web service. In this case, the SOAP message is only forwarded.
The web service might manipulate the message using a different data model, for example a Service Data Object (SDO). It is easier to convert the message from a SAAJ DOM to a different data model.
A handler, for example, a digital signature validation handler, might want to manipulate the message generically.

You might need to go a step further to map your XML schema types, because the SOAPElement interface is not always the best alternative for legacy systems. In this case you might want to use a generic programming model, such as SDO, which is more appropriate for data-centric applications.
The XML schema can be configured to include a custom data binding that pairs the SDO or data object with the Java object. For example, the run time renders an incoming SOAP message into a SOAPElement interface and passes it to the customer data binder for more processing. If the incoming message contains an SDO, the run time recognizes the data object code, queries its type mapping to locate a custom binder, and builds the SOAPElement interface that represents the SDO code. The SOAPElement is passed to the SDOCustomBinder.
See information on custom data binders to learn more about the process of developing applications with SOAPElement, SDO and custom binders.
Starting in WAS v8, the SOAPMessage.getSOAPHeader and getSOAPBody methods now throw a SOAPException if there is no corresponding element in the message. A System property is provided to revert the behavior to return null rather than throw an exception. The property is defined in com.ibm.websphere.webservices.soap.IBMSOAPMessage.ENABLE_LEGACY_GETSOAP_BEHAVIOR as a String value of com.ibm.websphere.webservices.soap.enable.legacy.get.behavior. The default value of the property is null which is interpreted as false. To revert the behavior to return a null, set the property to the String value true. The previous behavior of returning null is not compliant with the specification.

Related concepts:

SOAP
Differences in SOAP versions
Custom data binders for JAX-RPC applications
Differences in SAAJ versions

Reference:

Web services specifications and APIs

+
Search Tips | Advanced Search