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
SOAPPart of a
SOAPMessage is also a DOM Level
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
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:
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
ServiceLoaderclass, to attempt to locate and load an implementation of the service using the default loading mechanism.
- Finally, if all the steps above fail,
SAAJMetaFactoryinstance is used to locate specific implementation (for
SOAPFactory) or platform default implementation is used (
SAAJMetaFactoryis used, its lookup procedure to get actual instance is performed.
Interface Summary Interface Description DetailA container for
DetailEntryThe content for a
Detailobject, giving details for a
NameA representation of an XML name. NodeA representation of a node (element) in an XML document. SOAPBodyAn object that represents the contents of the SOAP body element in a SOAP message. SOAPBodyElementA
SOAPBodyElementobject represents the contents in a
SOAPConstantsThe definition of constants pertaining to the SOAP protocol. SOAPElementAn object representing an element of a SOAP message that is allowed but not specifically prescribed by a SOAP specification. SOAPEnvelopeThe container for the SOAPHeader and SOAPBody portions of a
SOAPFaultAn element in the
SOAPBodyobject that contains error and/or status information.
SOAPFaultElementA representation of the contents in a
SOAPHeaderA representation of the SOAP header element. SOAPHeaderElementAn object representing the contents in the SOAP header part of the SOAP envelope. TextA representation of a node whose value is text.
Class Summary Class Description AttachmentPartA single attachment to a
MessageFactoryA factory for creating
MimeHeaderAn object that stores a MIME header name and its value. MimeHeadersA container for
MimeHeaderobjects, which represent the MIME headers present in a MIME part of a message.
SAAJMetaFactoryThe access point for the implementation classes of the factories defined in the SAAJ API. SAAJResultActs as a holder for the results of a JAXP transformation or a JAXB marshalling, in the form of a SAAJ tree. SOAPConnectionA point-to-point connection that a client can use for sending messages directly to a remote party (represented by a URL, for instance). SOAPConnectionFactoryA factory for creating
SOAPFactoryis a factory for creating various objects that exist in the SOAP XML tree.
SOAPMessageThe root class for all SOAP messages. SOAPPartThe container for the SOAP-specific portion of a
Exception Summary Exception Description SOAPExceptionAn exception that signals that a SOAP exception has occurred.