Jakarta SOAP with Attachments API 3.0.0 · jakarta.xml.soap

Provides the API for creating and building SOAP messages. This package is defined in the Jakarta SOAP with Attachments specification.

The API in the jakarta.xml.soap package allows you to do the following:

create a point-to-point connection to a specified endpoint
create a SOAP message
create an XML fragment
add content to the header of a SOAP message
add content to the body of a SOAP message
create attachment parts and add content to them
access/add/modify parts of a SOAP message
create/add/modify SOAP fault information
extract content from a SOAP message
send a SOAP request-response message

References in this document to SAAJ refer to the Jakarta SOAP with Attachments API unless otherwise noted.
References in this document to JAXB refer to the Jakarta XML Binding unless otherwise noted.

In addition the APIs in the jakarta.xml.soap package extend their counterparts in the org.w3c.dom package. This means that the SOAPPart of a SOAPMessage is also a DOM Level 2 Document, and can be manipulated as such by applications, tools and libraries that use DOM (see http://www.w3.org/DOM/ for more information). It is important to note that, while it is possible to use DOM APIs to add ordinary DOM nodes to a SAAJ tree, the SAAJ APIs are still required to return SAAJ types when examining or manipulating the tree. In order to accomplish this the SAAJ APIs (specifically jakarta.xml.soap.SOAPElement#getChildElements()) are allowed to silently replace objects that are incorrectly typed relative to SAAJ requirements with equivalent objects of the required type. These replacements must never cause the logical structure of the tree to change, so from the perspective of the DOM APIs the tree will remain unchanged. However, the physical composition of the tree will have changed so that references to the nodes that were replaced will refer to nodes that are no longer a part of the tree. The SAAJ APIs are not allowed to make these replacements if they are not required so the replacement objects will never subsequently be silently replaced by future calls to the SAAJ API.

What this means in practical terms is that an application that starts to use SAAJ APIs on a tree after manipulating it using DOM APIs must assume that the tree has been translated into an all SAAJ tree and that any references to objects within the tree that were obtained using DOM APIs are no longer valid. Switching from SAAJ APIs to DOM APIs is not allowed to cause invalid references and neither is using SAAJ APIs exclusively. It is only switching from using DOM APIs on a particular SAAJ tree to using SAAJ APIs that causes the risk of invalid references.

Discovery of SAAJ implementation

There are several factories defined in the SAAJ API to discover and load specific implementation:

First three define newInstance() method which uses a common lookup procedure to determine the implementation class:

Checks if a system property with the same name as the factory class is set (e.g. jakarta.xml.soap.SOAPFactory). If such property exists then its value is assumed to be the fully qualified name of the implementation class. This phase of the look up enables per-JVM override of the SAAJ implementation.
Use the service-provider loading facilities, defined by the java.util.ServiceLoader class, to attempt to locate and load an implementation of the service using the default loading mechanism.
Finally, if all the steps above fail, jakarta.xml.soap.SAAJMetaFactory instance is used to locate specific implementation (for jakarta.xml.soap.MessageFactory and jakarta.xml.soap.SOAPFactory) or platform default implementation is used (jakarta.xml.soap.SOAPConnectionFactory). Whenever jakarta.xml.soap.SAAJMetaFactory is used, its lookup procedure to get actual instance is performed.

Interface Summary

Modifier and Type	Interface and Description
public interface	Detail A container for `DetailEntry` objects.
public interface	DetailEntry The content for a `Detail` object, giving details for a `SOAPFault` object.
public interface	Name A representation of an XML name.
public interface	Node A representation of a node (element) in an XML document.
public interface	SOAPBody An object that represents the contents of the SOAP body element in a SOAP message.
public interface	SOAPBodyElement A `SOAPBodyElement` object represents the contents in a `SOAPBody` object.
public interface	SOAPConstants The definition of constants pertaining to the SOAP protocol.
public interface	SOAPElement An object representing an element of a SOAP message that is allowed but not specifically prescribed by a SOAP specification.
public interface	SOAPEnvelope The container for the SOAPHeader and SOAPBody portions of a `SOAPPart` object.
public interface	SOAPFault An element in the `SOAPBody` object that contains error and/or status information.
public interface	SOAPFaultElement A representation of the contents in a `SOAPFault` object.
public interface	SOAPHeader A representation of the SOAP header element.
public interface	SOAPHeaderElement An object representing the contents in the SOAP header part of the SOAP envelope.
public interface	Text A representation of a node whose value is text.

Class Summary

Modifier and Type	Class and Description
public abstract class	AttachmentPart A single attachment to a `SOAPMessage` object.
pack-priv class	FactoryFinder
public abstract class	MessageFactory A factory for creating `SOAPMessage` objects.
public class	MimeHeader An object that stores a MIME header name and its value.
public class	MimeHeaders A container for `MimeHeader` objects, which represent the MIME headers present in a MIME part of a message.
public abstract class	SAAJMetaFactory The access point for the implementation classes of the factories defined in the SAAJ API.
public class	SAAJResult Acts as a holder for the results of a JAXP transformation or a JAXB marshalling, in the form of a SAAJ tree.
pack-priv class	ServiceLoaderUtil Shared ServiceLoader/FactoryFinder Utils shared among SAAJ, JAXB and JAXWS Class duplicated to all those projects.
public abstract class	SOAPConnection A point-to-point connection that a client can use for sending messages directly to a remote party (represented by a URL, for instance).
public abstract class	SOAPConnectionFactory A factory for creating `SOAPConnection` objects.
public class	SOAPException An exception that signals that a SOAP exception has occurred.
public abstract class	SOAPFactory `SOAPFactory` is a factory for creating various objects that exist in the SOAP XML tree.
public abstract class	SOAPMessage The root class for all SOAP messages.
public abstract class	SOAPPart The container for the SOAP-specific portion of a `SOAPMessage` object.

Package jakarta.xml.soap

Discovery of SAAJ implementation

Interface Summary

Class Summary