Skip navigation links

Jakarta EE Platform API v9.1.0

Package jakarta.xml.soap

Provides the API for creating and building SOAP messages.

See: Description

Package jakarta.xml.soap Description

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:

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 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:
Skip navigation links

Jakarta EE Platform API v9.1.0

Copyright © 2018,2020 Eclipse Foundation.
Use is subject to license terms.