javax.xml.soap.SOAPMessage Maven / Gradle / Ivy
/*
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
*
* Copyright (c) 2004-2012 Oracle and/or its affiliates. All rights reserved.
*
* The contents of this file are subject to the terms of either the GNU
* General Public License Version 2 only ("GPL") or the Common Development
* and Distribution License("CDDL") (collectively, the "License"). You
* may not use this file except in compliance with the License. You can
* obtain a copy of the License at
* http://glassfish.java.net/public/CDDL+GPL_1_1.html
* or packager/legal/LICENSE.txt. See the License for the specific
* language governing permissions and limitations under the License.
*
* When distributing the software, include this License Header Notice in each
* file and include the License file at packager/legal/LICENSE.txt.
*
* GPL Classpath Exception:
* Oracle designates this particular file as subject to the "Classpath"
* exception as provided by Oracle in the GPL Version 2 section of the License
* file that accompanied this code.
*
* Modifications:
* If applicable, add the following below the License Header, with the fields
* enclosed by brackets [] replaced by your own identifying information:
* "Portions Copyright [year] [name of copyright owner]"
*
* Contributor(s):
* If you wish your version of this file to be governed by only the CDDL or
* only the GPL Version 2, indicate your decision by adding "[Contributor]
* elects to include this software in this distribution under the [CDDL or GPL
* Version 2] license." If you don't indicate a single choice of license, a
* recipient has the option to distribute your version of this file under
* either the CDDL, the GPL Version 2 or to extend the choice of license to
* its licensees as provided above. However, if you add GPL Version 2 code
* and therefore, elected the GPL Version 2 license, then the option applies
* only if the new code is made subject to such option by the copyright
* holder.
*/
package javax.xml.soap;
import java.io.OutputStream;
import java.io.IOException;
import java.util.Iterator;
import javax.activation.DataHandler;
/**
* The root class for all SOAP messages. As transmitted on the "wire", a SOAP
* message is an XML document or a MIME message whose first body part is an
* XML/SOAP document.
*
* A SOAPMessage object consists of a SOAP part and optionally
* one or more attachment parts. The SOAP part for a SOAPMessage
* object is a SOAPPart object, which contains information used
* for message routing and identification, and which can contain
* application-specific content. All data in the SOAP Part of a message must be
* in XML format.
*
* A new SOAPMessage object contains the following by default:
*
* - A
SOAPPart object
* - A
SOAPEnvelope object
* - A
SOAPBody object
* - A
SOAPHeader object
*
* The SOAP part of a message can be retrieved by calling the method SOAPMessage.getSOAPPart().
* The SOAPEnvelope object is retrieved from the SOAPPart
* object, and the SOAPEnvelope object is used to retrieve the
* SOAPBody and SOAPHeader objects.
*
*
* SOAPPart sp = message.getSOAPPart();
* SOAPEnvelope se = sp.getEnvelope();
* SOAPBody sb = se.getBody();
* SOAPHeader sh = se.getHeader();
*
*
*
* In addition to the mandatory SOAPPart object, a SOAPMessage
* object may contain zero or more AttachmentPart objects, each
* of which contains application-specific data. The SOAPMessage
* interface provides methods for creating AttachmentPart
* objects and also for adding them to a SOAPMessage object. A
* party that has received a SOAPMessage object can examine its
* contents by retrieving individual attachment parts.
*
* Unlike the rest of a SOAP message, an attachment is not required to be in
* XML format and can therefore be anything from simple text to an image file.
* Consequently, any message content that is not in XML format must be in an
* AttachmentPart object.
*
* A MessageFactory object may create SOAPMessage
* objects with behavior that is specialized to a particular implementation or
* application of SAAJ. For instance, a MessageFactory object
* may produce SOAPMessage objects that conform to a particular
* Profile such as ebXML. In this case a MessageFactory object
* might produce SOAPMessage objects that are initialized with
* ebXML headers.
*
* In order to ensure backward source compatibility, methods that are added to
* this class after version 1.1 of the SAAJ specification are all concrete
* instead of abstract and they all have default implementations. Unless
* otherwise noted in the JavaDocs for those methods the default
* implementations simply throw an UnsupportedOperationException
* and the SAAJ implementation code must override them with methods that
* provide the specified behavior. Legacy client code does not have this
* restriction, however, so long as there is no claim made that it conforms to
* some later version of the specification than it was originally written for.
* A legacy class that extends the SOAPMessage class can be compiled and/or run
* against succeeding versions of the SAAJ API without modification. If such a
* class was correctly implemented then it will continue to behave correctly
* relative to the version of the specification against which it was written.
*
* @see MessageFactory
* @see AttachmentPart
*/
public abstract class SOAPMessage {
/**
* Specifies the character type encoding for the SOAP Message. Valid values
* include "utf-8" and "utf-16". See vendor documentation for additional
* supported values. The default is "utf-8".
*
* @see SOAPMessage#setProperty(String, Object) SOAPMessage.setProperty
* @since SAAJ 1.2
*/
public static final String CHARACTER_SET_ENCODING =
"javax.xml.soap.character-set-encoding";
/**
* Specifies whether the SOAP Message will contain an XML declaration when
* it is sent. The only valid values are "true" and "false". The default is
* "false".
*
* @see SOAPMessage#setProperty(String, Object) SOAPMessage.setProperty
* @since SAAJ 1.2
*/
public static final String WRITE_XML_DECLARATION =
"javax.xml.soap.write-xml-declaration";
/**
* Sets the description of this SOAPMessage object's
* content with the given description.
*
* @param description a String describing the content of this
* message
* @see #getContentDescription
*/
public abstract void setContentDescription(String description);
/**
* Retrieves a description of this SOAPMessage object's
* content.
*
* @return a String describing the content of this
* message or null if no description has been set
* @see #setContentDescription
*/
public abstract String getContentDescription();
/**
* Gets the SOAP part of this SOAPMessage object.
*
* SOAPMessage object contains one or more attachments, the
* SOAP Part must be the first MIME body part in the message.
*
* @return the SOAPPart object for this SOAPMessage
* object
*/
public abstract SOAPPart getSOAPPart();
/**
* Gets the SOAP Body contained in this SOAPMessage object.
*
*
* @return the SOAPBody object contained by this SOAPMessage
* object
* @exception SOAPException
* if the SOAP Body does not exist or cannot be retrieved
* @since SAAJ 1.2
*/
public SOAPBody getSOAPBody() throws SOAPException {
throw new UnsupportedOperationException("getSOAPBody must be overridden by all subclasses of SOAPMessage");
}
/**
* Gets the SOAP Header contained in this SOAPMessage
* object.
*
*
* @return the SOAPHeader object contained by this SOAPMessage
* object
* @exception SOAPException
* if the SOAP Header does not exist or cannot be retrieved
* @since SAAJ 1.2
*/
public SOAPHeader getSOAPHeader() throws SOAPException {
throw new UnsupportedOperationException("getSOAPHeader must be overridden by all subclasses of SOAPMessage");
}
/**
* Removes all AttachmentPart objects that have been added
* to this SOAPMessage object.
*
* This method does not touch the SOAP part.
*/
public abstract void removeAllAttachments();
/**
* Gets a count of the number of attachments in this message. This count
* does not include the SOAP part.
*
* @return the number of AttachmentPart objects that are
* part of this SOAPMessage object
*/
public abstract int countAttachments();
/**
* Retrieves all the AttachmentPart objects that are part of
* this SOAPMessage object.
*
* @return an iterator over all the attachments in this message
*/
public abstract Iterator getAttachments();
/**
* Retrieves all the AttachmentPart objects that have header
* entries that match the specified headers. Note that a returned
* attachment could have headers in addition to those specified.
*
* @param headers
* a MimeHeaders object containing the MIME
* headers for which to search
* @return an iterator over all attachments that have a header that matches
* one of the given headers
*/
public abstract Iterator getAttachments(MimeHeaders headers);
/**
* Removes all the AttachmentPart objects that have header
* entries that match the specified headers. Note that the removed
* attachment could have headers in addition to those specified.
*
* @param headers
* a MimeHeaders object containing the MIME
* headers for which to search
* @since SAAJ 1.3
*/
public abstract void removeAttachments(MimeHeaders headers);
/**
* Returns an AttachmentPart object that is associated with an
* attachment that is referenced by this SOAPElement or
* null if no such attachment exists. References can be made
* via an href attribute as described in
* {@link SOAP Messages with Attachments},
* or via a single Text child node containing a URI as
* described in the WS-I Attachments Profile 1.0 for elements of schema
* type {@link ref:swaRef}. These two mechanisms must be supported.
* The support for references via href attribute also implies that
* this method should also be supported on an element that is an
* xop:Include element (
* {@link XOP}).
* other reference mechanisms may be supported by individual
* implementations of this standard. Contact your vendor for details.
*
* @param element The SOAPElement containing the reference to an Attachment
* @return the referenced AttachmentPart or null if no such
* AttachmentPart exists or no reference can be
* found in this SOAPElement.
* @throws SOAPException if there is an error in the attempt to access the
* attachment
*
* @since SAAJ 1.3
*/
public abstract AttachmentPart getAttachment(SOAPElement element) throws SOAPException;
/**
* Adds the given AttachmentPart object to this SOAPMessage
* object. An AttachmentPart object must be created before
* it can be added to a message.
*
* @param AttachmentPart
* an AttachmentPart object that is to become part
* of this SOAPMessage object
* @exception IllegalArgumentException
*/
public abstract void addAttachmentPart(AttachmentPart AttachmentPart);
/**
* Creates a new empty AttachmentPart object. Note that the
* method addAttachmentPart must be called with this new
* AttachmentPart object as the parameter in order for it to
* become an attachment to this SOAPMessage object.
*
* @return a new AttachmentPart object that can be populated
* and added to this SOAPMessage object
*/
public abstract AttachmentPart createAttachmentPart();
/**
* Creates an AttachmentPart object and populates it using
* the given DataHandler object.
*
* @param dataHandler
* the javax.activation.DataHandler object that
* will generate the content for this SOAPMessage
* object
* @return a new AttachmentPart object that contains data
* generated by the given DataHandler object
* @exception IllegalArgumentException
* if there was a problem with the specified DataHandler
* object
* @see javax.activation.DataHandler
* @see javax.activation.DataContentHandler
*/
public AttachmentPart createAttachmentPart(DataHandler dataHandler) {
AttachmentPart attachment = createAttachmentPart();
attachment.setDataHandler(dataHandler);
return attachment;
}
/**
* Returns all the transport-specific MIME headers for this SOAPMessage
* object in a transport-independent fashion.
*
* @return a MimeHeaders object containing the MimeHeader
* objects
*/
public abstract MimeHeaders getMimeHeaders();
/**
* Creates an AttachmentPart object and populates it with
* the specified data of the specified content type. The type of the
* Object should correspond to the value given for the
* Content-Type.
*
* @param content
* an Object containing the content for the
* AttachmentPart object to be created
* @param contentType
* a String object giving the type of content;
* examples are "text/xml", "text/plain", and "image/jpeg"
* @return a new AttachmentPart object that contains the
* given data
* @exception IllegalArgumentException
* may be thrown if the contentType does not match the type
* of the content object, or if there was no
* DataContentHandler object for the given
* content object
* @see javax.activation.DataHandler
* @see javax.activation.DataContentHandler
*/
public AttachmentPart createAttachmentPart(
Object content,
String contentType) {
AttachmentPart attachment = createAttachmentPart();
attachment.setContent(content, contentType);
return attachment;
}
/**
* Updates this SOAPMessage object with all the changes that
* have been made to it. This method is called automatically when
* {@link SOAPMessage#writeTo(OutputStream)} is called. However, if
* changes are made to a message that was received or to one that has
* already been sent, the method saveChanges needs to be
* called explicitly in order to save the changes. The method saveChanges
* also generates any changes that can be read back (for example, a
* MessageId in profiles that support a message id). All MIME headers in a
* message that is created for sending purposes are guaranteed to have
* valid values only after saveChanges has been called.
*
* In addition, this method marks the point at which the data from all
* constituent AttachmentPart objects are pulled into the
* message.
*
*
* @exception SOAPException if there was a problem saving
* changes to this message.
*/
public abstract void saveChanges() throws SOAPException;
/**
* Indicates whether this SOAPMessage object needs to have
* the method saveChanges called on it.
*
* @return true if saveChanges needs to be
* called; false otherwise.
*/
public abstract boolean saveRequired();
/**
* Writes this SOAPMessage object to the given output
* stream. The externalization format is as defined by the SOAP 1.1 with
* Attachments specification.
*
* If there are no attachments, just an XML stream is written out. For
* those messages that have attachments, writeTo writes a
* MIME-encoded byte stream.
*
* Note that this method does not write the transport-specific MIME Headers
* of the Message
*
* @param out
* the OutputStream object to which this SOAPMessage
* object will be written
* @exception IOException
* if an I/O error occurs
* @exception SOAPException
* if there was a problem in externalizing this SOAP message
*/
public abstract void writeTo(OutputStream out)
throws SOAPException, IOException;
/**
* Associates the specified value with the specified property. If there was
* already a value associated with this property, the old value is
* replaced.
*
* The valid property names include
* {@link SOAPMessage#WRITE_XML_DECLARATION} and
* {@link SOAPMessage#CHARACTER_SET_ENCODING}. All of these standard SAAJ
* properties are prefixed by "javax.xml.soap". Vendors may also add
* implementation specific properties. These properties must be prefixed
* with package names that are unique to the vendor.
*
* Setting the property WRITE_XML_DECLARATION to "true"
* will cause an XML Declaration to be written out at the start of the SOAP
* message. The default value of "false" suppresses this declaration.
*
* The property CHARACTER_SET_ENCODING defaults to the value
* "utf-8" which causes the SOAP message to be encoded using
* UTF-8. Setting CHARACTER_SET_ENCODING to "utf-16"
* causes the SOAP message to be encoded using UTF-16.
*
* Some implementations may allow encodings in addition to UTF-8 and
* UTF-16. Refer to your vendor's documentation for details.
*
* @param property
* the property with which the specified value is to be
* associated.
* @param value
* the value to be associated with the specified property
* @exception SOAPException
* if the property name is not recognized.
* @since SAAJ 1.2
*/
public void setProperty(String property, Object value)
throws SOAPException {
throw new UnsupportedOperationException("setProperty must be overridden by all subclasses of SOAPMessage");
}
/**
* Retrieves value of the specified property.
*
* @param property
* the name of the property to retrieve
* @return the value associated with the named property or null
* if no such property exists.
* @exception SOAPException
* if the property name is not recognized.
* @since SAAJ 1.2
*/
public Object getProperty(String property) throws SOAPException {
throw new UnsupportedOperationException("getProperty must be overridden by all subclasses of SOAPMessage");
}
}