Adding a Document to the SOAP Body
136
SOAP
WITH
A
TTACHMENTS
API
FOR
J
AVA
Adding a Document to the SOAP Body
In addition to setting the content of the entire SOAP message to that of a
DOM-
Source
object, you can add a DOM document directly to the body of the mes-
sage.
This
capability
means
that
you
do
not
have
to
create
a
javax.xml.transform.Source
object. After you parse the document, you can
add it directly to the message body:
SOAPBody body = message.getSOAPBody();
SOAPBodyElement docElement = body.addDocument(document);
Manipulating Message Content Using
SAAJ or DOM APIs
Because SAAJ nodes and elements implement the DOM
Node
and
Element
interfaces, you have many options for adding or changing message content:
· Use only DOM APIs.
· Use only SAAJ APIs.
· Use SAAJ APIs and then switch to using DOM APIs.
· Use DOM APIs and then switch to using SAAJ APIs.
The first three of these cause no problems. After you have created a message,
whether or not you have imported its content from another document, you can
start adding or changing nodes using either SAAJ or DOM APIs.
But if you use DOM APIs and then switch to using SAAJ APIs to manipulate the
document, any references to objects within the tree that were obtained using
DOM APIs are no longer valid. If you must use SAAJ APIs after using DOM
APIs, you should set all your DOM typed references to null, because they can
become invalid. For more information about the exact cases in which references
become invalid, see the SAAJ API documentation.
The basic rule is that you can continue manipulating the message content using
SAAJ APIs as long as you want to, but after you start manipulating it using
DOM, you should no longer use SAAJ APIs.
