geronimo-scm mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From gno...@apache.org
Subject svn commit: r601048 [5/5] - in /geronimo/specs/trunk: ./ geronimo-jsp_2.1_spec/src/main/resources/javax/servlet/jsp/resources/ geronimo-saaj_1.1_spec/ geronimo-saaj_1.3_spec/ geronimo-saaj_1.3_spec/src/main/java/javax/xml/soap/
Date Tue, 04 Dec 2007 19:25:48 GMT
Modified: geronimo/specs/trunk/geronimo-saaj_1.3_spec/src/main/java/javax/xml/soap/SOAPMessage.java
URL: http://svn.apache.org/viewvc/geronimo/specs/trunk/geronimo-saaj_1.3_spec/src/main/java/javax/xml/soap/SOAPMessage.java?rev=601048&r1=600870&r2=601048&view=diff
==============================================================================
--- geronimo/specs/trunk/geronimo-saaj_1.3_spec/src/main/java/javax/xml/soap/SOAPMessage.java (original)
+++ geronimo/specs/trunk/geronimo-saaj_1.3_spec/src/main/java/javax/xml/soap/SOAPMessage.java Tue Dec  4 11:25:44 2007
@@ -1,22 +1,21 @@
 /*
  * Licensed to the Apache Software Foundation (ASF) under one
- * or more contributor license agreements.  See the NOTICE file
+ * or more contributor license agreements. See the NOTICE file
  * distributed with this work for additional information
- * regarding copyright ownership.  The ASF licenses this file
+ * regarding copyright ownership. The ASF licenses this file
  * to you under the Apache License, Version 2.0 (the
  * "License"); you may not use this file except in compliance
- * with the License.  You may obtain a copy of the License at
+ * with the License. You may obtain a copy of the License at
  *
- *  http://www.apache.org/licenses/LICENSE-2.0
+ * http://www.apache.org/licenses/LICENSE-2.0
  *
  * Unless required by applicable law or agreed to in writing,
  * software distributed under the License is distributed on an
  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- * KIND, either express or implied.  See the License for the
+ * KIND, either express or implied. See the License for the
  * specific language governing permissions and limitations
  * under the License.
  */
-
 package javax.xml.soap;
 
 import javax.activation.DataHandler;
@@ -25,180 +24,153 @@
 import java.util.Iterator;
 
 /**
- * <P>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.</P>
- *
- * <P>A <CODE>SOAPMessage</CODE> object consists of a SOAP part
- * and optionally one or more attachment parts. The SOAP part for
- * a <CODE>SOAPMessage</CODE> object is a <CODE>SOAPPart</CODE>
- * 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
+ * <P>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.</P>
+ * <p/>
+ * <P>A <CODE>SOAPMessage</CODE> object consists of a SOAP part and optionally one or more
+ * attachment parts. The SOAP part for a <CODE>SOAPMessage</CODE> object is a <CODE>SOAPPart</CODE>
+ * 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.</P>
- *
- * <P>A new <CODE>SOAPMessage</CODE> object contains the following
- * by default:</P>
- *
- * <UL>
- *  <LI>A <CODE>SOAPPart</CODE> object</LI>
- *
- *  <LI>A <CODE>SOAPEnvelope</CODE> object</LI>
- *
- *  <LI>A <CODE>SOAPBody</CODE> object</LI>
- *
- *  <LI>A <CODE>SOAPHeader</CODE> object</LI>
- * </UL>
- * The SOAP part of a message can be retrieved by calling the
- * method <CODE>SOAPMessage.getSOAPPart()</CODE>. The <CODE>
- * SOAPEnvelope</CODE> object is retrieved from the <CODE>
- * SOAPPart</CODE> object, and the <CODE>SOAPEnvelope</CODE>
- * object is used to retrieve the <CODE>SOAPBody</CODE> and <CODE>
- * SOAPHeader</CODE> objects.
- * <PRE>
- * SOAPPart sp = message.getSOAPPart();
- * SOAPEnvelope se = sp.getEnvelope();
- * SOAPBody sb = se.getBody();
- * SOAPHeader sh = se.getHeader();
- * </PRE>
- *
- * <P>In addition to the mandatory <CODE>SOAPPart</CODE> object, a
- * <CODE>SOAPMessage</CODE> object may contain zero or more <CODE>
- * AttachmentPart</CODE> objects, each of which contains
- * application-specific data. The <CODE>SOAPMessage</CODE>
- * interface provides methods for creating <CODE>
- * AttachmentPart</CODE> objects and also for adding them to a
- * <CODE>SOAPMessage</CODE> object. A party that has received a
- * <CODE>SOAPMessage</CODE> object can examine its contents by
+ * <p/>
+ * <P>A new <CODE>SOAPMessage</CODE> object contains the following by default:</P>
+ * <p/>
+ * <UL> <LI>A <CODE>SOAPPart</CODE> object</LI>
+ * <p/>
+ * <LI>A <CODE>SOAPEnvelope</CODE> object</LI>
+ * <p/>
+ * <LI>A <CODE>SOAPBody</CODE> object</LI>
+ * <p/>
+ * <LI>A <CODE>SOAPHeader</CODE> object</LI> </UL> The SOAP part of a message can be retrieved by
+ * calling the method <CODE>SOAPMessage.getSOAPPart()</CODE>. The <CODE> SOAPEnvelope</CODE> object
+ * is retrieved from the <CODE> SOAPPart</CODE> object, and the <CODE>SOAPEnvelope</CODE> object is
+ * used to retrieve the <CODE>SOAPBody</CODE> and <CODE> SOAPHeader</CODE> objects. <PRE> SOAPPart
+ * sp = message.getSOAPPart(); SOAPEnvelope se = sp.getEnvelope(); SOAPBody sb = se.getBody();
+ * SOAPHeader sh = se.getHeader(); </PRE>
+ * <p/>
+ * <P>In addition to the mandatory <CODE>SOAPPart</CODE> object, a <CODE>SOAPMessage</CODE> object
+ * may contain zero or more <CODE> AttachmentPart</CODE> objects, each of which contains
+ * application-specific data. The <CODE>SOAPMessage</CODE> interface provides methods for creating
+ * <CODE> AttachmentPart</CODE> objects and also for adding them to a <CODE>SOAPMessage</CODE>
+ * object. A party that has received a <CODE>SOAPMessage</CODE> object can examine its contents by
  * retrieving individual attachment parts.</P>
+ * <p/>
+ * <P>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 <CODE> AttachmentPart</CODE> object.</P>
+ * <p/>
+ * <P>A <CODE>MessageFactory</CODE> object creates new <CODE> SOAPMessage</CODE> objects. If the
+ * <CODE>MessageFactory</CODE> object was initialized with a messaging Profile, it produces
+ * <CODE>SOAPMessage</CODE> objects that conform to that Profile. For example, a
+ * <CODE>SOAPMessage</CODE> object created by a <CODE>MessageFactory</CODE> object initialized with
+ * the ebXML Profile will have the appropriate ebXML headers.</P>
  *
- * <P>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 <CODE>
- * AttachmentPart</CODE> object.</P>
- *
- * <P>A <CODE>MessageFactory</CODE> object creates new <CODE>
- * SOAPMessage</CODE> objects. If the <CODE>MessageFactory</CODE>
- * object was initialized with a messaging Profile, it produces
- * <CODE>SOAPMessage</CODE> objects that conform to that Profile.
- * For example, a <CODE>SOAPMessage</CODE> object created by a
- * <CODE>MessageFactory</CODE> object initialized with the ebXML
- * Profile will have the appropriate ebXML headers.</P>
  * @see MessageFactory MessageFactory
  * @see AttachmentPart AttachmentPart
  */
 public abstract class SOAPMessage {
 
-    public SOAPMessage() {}
+    public SOAPMessage() {
+    }
 
     /**
-     * Retrieves a description of this <CODE>SOAPMessage</CODE>
-     * object's content.
-     * @return  a <CODE>String</CODE> describing the content of this
-     *     message or <CODE>null</CODE> if no description has been
-     *     set
-     * @see #setContentDescription(java.lang.String) setContentDescription(java.lang.String)
+     * Retrieves a description of this <CODE>SOAPMessage</CODE> object's content.
+     *
+     * @return a <CODE>String</CODE> describing the content of this message or <CODE>null</CODE> if
+     *         no description has been set
+     * @see #setContentDescription(String) setContentDescription(java.lang.String)
      */
     public abstract String getContentDescription();
 
     /**
-     * Sets the description of this <CODE>SOAPMessage</CODE>
-     * object's content with the given description.
-     * @param  description a <CODE>String</CODE>
-     *     describing the content of this message
+     * Sets the description of this <CODE>SOAPMessage</CODE> object's content with the given
+     * description.
+     *
+     * @param description a <CODE>String</CODE> describing the content of this message
      * @see #getContentDescription() getContentDescription()
      */
     public abstract void setContentDescription(String description);
 
     /**
      * Gets the SOAP part of this <CODE>SOAPMessage</CODE> object.
+     * <p/>
+     * <p/>
+     * <P>If a <CODE>SOAPMessage</CODE> object contains one or more attachments, the SOAP Part must
+     * be the first MIME body part in the message.</P>
      *
-     *
-     *   <P>If a <CODE>SOAPMessage</CODE> object contains one or
-     *   more attachments, the SOAP Part must be the first MIME body
-     *   part in the message.</P>
-     * @return the <CODE>SOAPPart</CODE> object for this <CODE>
-     *     SOAPMessage</CODE> object
+     * @return the <CODE>SOAPPart</CODE> object for this <CODE> SOAPMessage</CODE> object
      */
     public abstract SOAPPart getSOAPPart();
 
     /**
-     * Removes all <CODE>AttachmentPart</CODE> objects that have
-     *   been added to this <CODE>SOAPMessage</CODE> object.
-     *
-     *   <P>This method does not touch the SOAP part.</P>
+     * Removes all <CODE>AttachmentPart</CODE> objects that have been added to this
+     * <CODE>SOAPMessage</CODE> object.
+     * <p/>
+     * <P>This method does not touch the SOAP part.</P>
      */
     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 <CODE>AttachmentPart</CODE> objects
-     *     that are part of this <CODE>SOAPMessage</CODE>
-     *     object
+     * Gets a count of the number of attachments in this message. This count does not include the
+     * SOAP part.
+     *
+     * @return the number of <CODE>AttachmentPart</CODE> objects that are part of this
+     *         <CODE>SOAPMessage</CODE> object
      */
     public abstract int countAttachments();
 
     /**
-     * Retrieves all the <CODE>AttachmentPart</CODE> objects
-     * that are part of this <CODE>SOAPMessage</CODE> object.
-     * @return  an iterator over all the attachments in this
-     *     message
+     * Retrieves all the <CODE>AttachmentPart</CODE> objects that are part of this
+     * <CODE>SOAPMessage</CODE> object.
+     *
+     * @return an iterator over all the attachments in this message
      */
     public abstract Iterator getAttachments();
 
     /**
-     * Retrieves all the <CODE>AttachmentPart</CODE> 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 <CODE>MimeHeaders</CODE>
-     *     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
+     * Retrieves all the <CODE>AttachmentPart</CODE> 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 <CODE>MimeHeaders</CODE> 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);
 
     /**
-     * Adds the given <CODE>AttachmentPart</CODE> object to this
-     * <CODE>SOAPMessage</CODE> object. An <CODE>
-     * AttachmentPart</CODE> object must be created before it can be
-     * added to a message.
-     * @param  attachmentpart an <CODE>
-     *     AttachmentPart</CODE> object that is to become part of
-     *     this <CODE>SOAPMessage</CODE> object
-     * @throws java.lang.IllegalArgumentException
+     * Adds the given <CODE>AttachmentPart</CODE> object to this <CODE>SOAPMessage</CODE> object. An
+     * <CODE> AttachmentPart</CODE> object must be created before it can be added to a message.
+     *
+     * @param attachmentpart an <CODE> AttachmentPart</CODE> object that is to become part of this
+     *                       <CODE>SOAPMessage</CODE> object
+     * @throws IllegalArgumentException
+     *
      */
     public abstract void addAttachmentPart(AttachmentPart attachmentpart);
 
     /**
-     * Creates a new empty <CODE>AttachmentPart</CODE> object.
-     * Note that the method <CODE>addAttachmentPart</CODE> must be
-     * called with this new <CODE>AttachmentPart</CODE> object as
-     * the parameter in order for it to become an attachment to this
+     * Creates a new empty <CODE>AttachmentPart</CODE> object. Note that the method
+     * <CODE>addAttachmentPart</CODE> must be called with this new <CODE>AttachmentPart</CODE>
+     * object as the parameter in order for it to become an attachment to this
      * <CODE>SOAPMessage</CODE> object.
-     * @return  a new <CODE>AttachmentPart</CODE> object that can be
-     *     populated and added to this <CODE>SOAPMessage</CODE>
-     *     object
+     *
+     * @return a new <CODE>AttachmentPart</CODE> object that can be populated and added to this
+     *         <CODE>SOAPMessage</CODE> object
      */
     public abstract AttachmentPart createAttachmentPart();
 
     /**
-     * Creates an <CODE>AttachmentPart</CODE> object and
-     * populates it using the given <CODE>DataHandler</CODE>
-     * object.
-     * @param   datahandler  the <CODE>
-     *     javax.activation.DataHandler</CODE> object that will
-     *     generate the content for this <CODE>SOAPMessage</CODE>
-     *     object
-     * @return a new <CODE>AttachmentPart</CODE> object that
-     *     contains data generated by the given <CODE>
-     *     DataHandler</CODE> object
-     * @throws java.lang.IllegalArgumentException if
-     *     there was a problem with the specified <CODE>
-     *     DataHandler</CODE> object
+     * Creates an <CODE>AttachmentPart</CODE> object and populates it using the given
+     * <CODE>DataHandler</CODE> object.
+     *
+     * @param datahandler the <CODE> javax.activation.DataHandler</CODE> object that will generate
+     *                    the content for this <CODE>SOAPMessage</CODE> object
+     * @return a new <CODE>AttachmentPart</CODE> object that contains data generated by the given
+     *         <CODE> DataHandler</CODE> object
+     * @throws IllegalArgumentException
+     *          if there was a problem with the specified <CODE> DataHandler</CODE> object
      * @see DataHandler DataHandler
      * @see javax.activation.DataContentHandler DataContentHandler
      */
@@ -212,30 +184,25 @@
     }
 
     /**
-     * Returns all the transport-specific MIME headers for this
-     * <CODE>SOAPMessage</CODE> object in a transport-independent
-     * fashion.
-     * @return a <CODE>MimeHeaders</CODE> object containing the
-     *     <CODE>MimeHeader</CODE> objects
+     * Returns all the transport-specific MIME headers for this <CODE>SOAPMessage</CODE> object in a
+     * transport-independent fashion.
+     *
+     * @return a <CODE>MimeHeaders</CODE> object containing the <CODE>MimeHeader</CODE> objects
      */
     public abstract MimeHeaders getMimeHeaders();
 
     /**
-     * Creates an <CODE>AttachmentPart</CODE> object and
-     * populates it with the specified data of the specified content
-     * type.
-     * @param   content  an <CODE>Object</CODE>
-     *     containing the content for this <CODE>SOAPMessage</CODE>
-     *     object
-     * @param   contentType a <CODE>String</CODE>
-     *     object giving the type of content; examples are
-     *     "text/xml", "text/plain", and "image/jpeg"
-     * @return a new <CODE>AttachmentPart</CODE> object that
-     *     contains the given data
-     * @throws java.lang.IllegalArgumentException if the contentType does not match the type of the content
-     *     object, or if there was no <CODE>
-     *     DataContentHandler</CODE> object for the given content
-     *     object
+     * Creates an <CODE>AttachmentPart</CODE> object and populates it with the specified data of the
+     * specified content type.
+     *
+     * @param content     an <CODE>Object</CODE> containing the content for this
+     *                    <CODE>SOAPMessage</CODE> object
+     * @param contentType a <CODE>String</CODE> object giving the type of content; examples are
+     *                    "text/xml", "text/plain", and "image/jpeg"
+     * @return a new <CODE>AttachmentPart</CODE> object that contains the given data
+     * @throws IllegalArgumentException
+     *          if the contentType does not match the type of the content object, or if there was no
+     *          <CODE> DataContentHandler</CODE> object for the given content object
      * @see DataHandler DataHandler
      * @see javax.activation.DataContentHandler DataContentHandler
      */
@@ -250,127 +217,116 @@
     }
 
     /**
-     * Updates this <CODE>SOAPMessage</CODE> object with all the
-     *   changes that have been made to it. This method is called
-     *   automatically when a message is sent or written to by the
-     *   methods <CODE>ProviderConnection.send</CODE>, <CODE>
-     *   SOAPConnection.call</CODE>, or <CODE>
-     *   SOAPMessage.writeTo</CODE>. However, if changes are made to
-     *   a message that was received or to one that has already been
-     *   sent, the method <CODE>saveChanges</CODE> needs to be
-     *   called explicitly in order to save the changes. The method
-     *   <CODE>saveChanges</CODE> 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 <CODE>saveChanges</CODE> has been
-     *   called.
-     *
-     *   <P>In addition, this method marks the point at which the
-     *   data from all constituent <CODE>AttachmentPart</CODE>
-     *   objects are pulled into the message.</P>
-     * @throws  SOAPException if there
-     *     was a problem saving changes to this message.
+     * Updates this <CODE>SOAPMessage</CODE> object with all the changes that have been made to it.
+     * This method is called automatically when a message is sent or written to by the methods
+     * <CODE>ProviderConnection.send</CODE>, <CODE> SOAPConnection.call</CODE>, or <CODE>
+     * SOAPMessage.writeTo</CODE>. However, if changes are made to a message that was received or to
+     * one that has already been sent, the method <CODE>saveChanges</CODE> needs to be called
+     * explicitly in order to save the changes. The method <CODE>saveChanges</CODE> 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 <CODE>saveChanges</CODE> has been called.
+     * <p/>
+     * <P>In addition, this method marks the point at which the data from all constituent
+     * <CODE>AttachmentPart</CODE> objects are pulled into the message.</P>
+     *
+     * @throws SOAPException if there was a problem saving changes to this message.
      */
     public abstract void saveChanges() throws SOAPException;
 
     /**
-     * Indicates whether this <CODE>SOAPMessage</CODE> object
-     * has had the method <CODE>saveChanges</CODE> called on
-     * it.
-     * @return <CODE>true</CODE> if <CODE>saveChanges</CODE> has
-     *     been called on this message at least once; <CODE>
-     *     false</CODE> otherwise.
+     * Indicates whether this <CODE>SOAPMessage</CODE> object has had the method
+     * <CODE>saveChanges</CODE> called on it.
+     *
+     * @return <CODE>true</CODE> if <CODE>saveChanges</CODE> has been called on this message at
+     *         least once; <CODE> false</CODE> otherwise.
      */
     public abstract boolean saveRequired();
 
     /**
-     * Writes this <CODE>SOAPMessage</CODE> object to the given
-     *   output stream. The externalization format is as defined by
-     *   the SOAP 1.1 with Attachments specification.
-     *
-     *   <P>If there are no attachments, just an XML stream is
-     *   written out. For those messages that have attachments,
-     *   <CODE>writeTo</CODE> writes a MIME-encoded byte stream.</P>
-     * @param   out the <CODE>OutputStream</CODE>
-     *     object to which this <CODE>SOAPMessage</CODE> object will
-     *     be written
-     * @throws  SOAPException  if there was a problem in
-     *     externalizing this SOAP message
-     * @throws  IOException  if an I/O error
-     *     occurs
+     * Writes this <CODE>SOAPMessage</CODE> object to the given output stream. The externalization
+     * format is as defined by the SOAP 1.1 with Attachments specification.
+     * <p/>
+     * <P>If there are no attachments, just an XML stream is written out. For those messages that
+     * have attachments, <CODE>writeTo</CODE> writes a MIME-encoded byte stream.</P>
+     *
+     * @param out the <CODE>OutputStream</CODE> object to which this <CODE>SOAPMessage</CODE> object
+     *            will be written
+     * @throws SOAPException if there was a problem in externalizing this SOAP message
+     * @throws IOException   if an I/O error occurs
      */
     public abstract void writeTo(OutputStream out)
-        throws SOAPException, IOException;
+            throws SOAPException, IOException;
 
     /**
      * Gets the SOAP Body contained in this <code>SOAPMessage</code> object.
      *
-     * @return the <code>SOAPBody</code> object contained by this
-     *              <code>SOAPMessage</code> object
-     * @throws SOAPException if the SOAP Body does not exist or cannot be
-     *              retrieved
+     * @return the <code>SOAPBody</code> object contained by this <code>SOAPMessage</code> object
+     * @throws SOAPException if the SOAP Body does not exist or cannot be retrieved
      */
     public SOAPBody getSOAPBody() throws SOAPException {
-        throw new UnsupportedOperationException("getSOAPBody must be overridden in subclasses of SOAPMessage");        
+        throw new UnsupportedOperationException(
+                "getSOAPBody must be overridden in subclasses of SOAPMessage");
     }
 
     /**
      * Gets the SOAP Header contained in this <code>SOAPMessage</code> object.
      *
-     * @return the <code>SOAPHeader</code> object contained by this
-     *              <code>SOAPMessage</code> object
-     * @throws SOAPException  if the SOAP Header does not exist or cannot be
-     *              retrieved
+     * @return the <code>SOAPHeader</code> object contained by this <code>SOAPMessage</code> object
+     * @throws SOAPException if the SOAP Header does not exist or cannot be retrieved
      */
     public SOAPHeader getSOAPHeader() throws SOAPException {
-        throw new UnsupportedOperationException("getSOAPHeader must be overridden in subclasses of SOAPMessage");        
+        throw new UnsupportedOperationException(
+                "getSOAPHeader must be overridden in subclasses of SOAPMessage");
     }
 
     /**
-     * Associates the specified value with the specified property. If there was
-     * already a value associated with this property, the old value is replaced.
-     * <p>
+     * Associates the specified value with the specified property. If there was already a value
+     * associated with this property, the old value is replaced.
+     * <p/>
      * The valid property names include <code>WRITE_XML_DECLARATION</code> and
-     * <code>CHARACTER_SET_ENCODING</code>. 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.
-     * <p>
-     * Setting the property <code>WRITE_XML_DECLARATION</code> to
-     * <code>"true"</code> will cause an XML Declaration to be written out at
-     * the start of the SOAP message. The default value of "false" suppresses
-     * this declaration.
-     * <p>
-     * The property <code>CHARACTER_SET_ENCODING</code> defaults to the value
-     * <code>"utf-8"</code> which causes the SOAP message to be encoded using
-     * UTF-8. Setting <code>CHARACTER_SET_ENCODING</code> to
-     * <code>"utf-16"</code> causes the SOAP message to be encoded using UTF-16.
-     * <p>
-     * 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
+     * <code>CHARACTER_SET_ENCODING</code>. 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.
+     * <p/>
+     * Setting the property <code>WRITE_XML_DECLARATION</code> to <code>"true"</code> will cause an
+     * XML Declaration to be written out at the start of the SOAP message. The default value of
+     * "false" suppresses this declaration.
+     * <p/>
+     * The property <code>CHARACTER_SET_ENCODING</code> defaults to the value <code>"utf-8"</code>
+     * which causes the SOAP message to be encoded using UTF-8. Setting
+     * <code>CHARACTER_SET_ENCODING</code> to <code>"utf-16"</code> causes the SOAP message to be
+     * encoded using UTF-16.
+     * <p/>
+     * 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
      * @throws SOAPException if the property name is not recognized
      */
     public void setProperty(String property, Object value)
-            throws SOAPException  {
-        throw new UnsupportedOperationException("setProperty must be overridden in subclasses of SOAPMessage");        
+            throws SOAPException {
+        throw new UnsupportedOperationException(
+                "setProperty must be overridden in subclasses of SOAPMessage");
     }
 
     /**
      * Retrieves value of the specified property.
      *
      * @param property the name of the property to retrieve
-     * @return the value of the property or <code>null</code> if no such
-     *              property exists
-     * @throws SOAPException  if the property name is not recognized
+     * @return the value of the property or <code>null</code> if no such property exists
+     * @throws SOAPException if the property name is not recognized
      */
     public Object getProperty(String property) throws SOAPException {
-        throw new UnsupportedOperationException("getProperty must be overridden in subclasses of SOAPMessage");        
+        throw new UnsupportedOperationException(
+                "getProperty must be overridden in subclasses of SOAPMessage");
     }
+
+    public abstract AttachmentPart getAttachment(SOAPElement soapelement)
+            throws SOAPException;
+
+    public abstract void removeAttachments(MimeHeaders mimeheaders);
 
     /** Specifies the character type encoding for the SOAP Message. */
     public static final String CHARACTER_SET_ENCODING

Modified: geronimo/specs/trunk/geronimo-saaj_1.3_spec/src/main/java/javax/xml/soap/SOAPPart.java
URL: http://svn.apache.org/viewvc/geronimo/specs/trunk/geronimo-saaj_1.3_spec/src/main/java/javax/xml/soap/SOAPPart.java?rev=601048&r1=600870&r2=601048&view=diff
==============================================================================
--- geronimo/specs/trunk/geronimo-saaj_1.3_spec/src/main/java/javax/xml/soap/SOAPPart.java (original)
+++ geronimo/specs/trunk/geronimo-saaj_1.3_spec/src/main/java/javax/xml/soap/SOAPPart.java Tue Dec  4 11:25:44 2007
@@ -1,85 +1,71 @@
 /*
  * Licensed to the Apache Software Foundation (ASF) under one
- * or more contributor license agreements.  See the NOTICE file
+ * or more contributor license agreements. See the NOTICE file
  * distributed with this work for additional information
- * regarding copyright ownership.  The ASF licenses this file
+ * regarding copyright ownership. The ASF licenses this file
  * to you under the Apache License, Version 2.0 (the
  * "License"); you may not use this file except in compliance
- * with the License.  You may obtain a copy of the License at
+ * with the License. You may obtain a copy of the License at
  *
- *  http://www.apache.org/licenses/LICENSE-2.0
+ * http://www.apache.org/licenses/LICENSE-2.0
  *
  * Unless required by applicable law or agreed to in writing,
  * software distributed under the License is distributed on an
  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- * KIND, either express or implied.  See the License for the
+ * KIND, either express or implied. See the License for the
  * specific language governing permissions and limitations
  * under the License.
  */
-
 package javax.xml.soap;
 
 import javax.xml.transform.Source;
 import java.util.Iterator;
 
 /**
- * <P>The container for the SOAP-specific portion of a <CODE>
- * SOAPMessage</CODE> object. All messages are required to have a
- * SOAP part, so when a <CODE>SOAPMessage</CODE> object is
- * created, it will automatically have a <CODE>SOAPPart</CODE>
- * object.</P>
- *
- * <P>A <CODE>SOAPPart</CODE> object is a MIME part and has the
- * MIME headers Content-Id, Content-Location, and Content-Type.
- * Because the value of Content-Type must be "text/xml", a <CODE>
- * SOAPPart</CODE> object automatically has a MIME header of
- * Content-Type with its value set to "text/xml". The value must
- * be "text/xml" because content in the SOAP part of a message
- * must be in XML format. Content that is not of type "text/xml"
- * must be in an <CODE>AttachmentPart</CODE> object rather than in
- * the <CODE>SOAPPart</CODE> object.</P>
- *
- * <P>When a message is sent, its SOAP part must have the MIME
- * header Content-Type set to "text/xml". Or, from the other
- * perspective, the SOAP part of any message that is received must
- * have the MIME header Content-Type with a value of
- * "text/xml".</P>
- *
- * <P>A client can access the <CODE>SOAPPart</CODE> object of a
- * <CODE>SOAPMessage</CODE> object by calling the method <CODE>
- * SOAPMessage.getSOAPPart</CODE>. The following line of code, in
- * which <CODE>message</CODE> is a <CODE>SOAPMessage</CODE>
- * object, retrieves the SOAP part of a message.</P>
- * <PRE>
- * SOAPPart soapPart = message.getSOAPPart();
- * </PRE>
- *
- * <P>A <CODE>SOAPPart</CODE> object contains a <CODE>
- * SOAPEnvelope</CODE> object, which in turn contains a <CODE>
- * SOAPBody</CODE> object and a <CODE>SOAPHeader</CODE> object.
- * The <CODE>SOAPPart</CODE> method <CODE>getEnvelope</CODE> can
- * be used to retrieve the <CODE>SOAPEnvelope</CODE> object.</P>
+ * <P>The container for the SOAP-specific portion of a <CODE> SOAPMessage</CODE> object. All
+ * messages are required to have a SOAP part, so when a <CODE>SOAPMessage</CODE> object is created,
+ * it will automatically have a <CODE>SOAPPart</CODE> object.</P>
+ * <p/>
+ * <P>A <CODE>SOAPPart</CODE> object is a MIME part and has the MIME headers Content-Id,
+ * Content-Location, and Content-Type. Because the value of Content-Type must be "text/xml", a
+ * <CODE> SOAPPart</CODE> object automatically has a MIME header of Content-Type with its value set
+ * to "text/xml". The value must be "text/xml" because content in the SOAP part of a message must be
+ * in XML format. Content that is not of type "text/xml" must be in an <CODE>AttachmentPart</CODE>
+ * object rather than in the <CODE>SOAPPart</CODE> object.</P>
+ * <p/>
+ * <P>When a message is sent, its SOAP part must have the MIME header Content-Type set to
+ * "text/xml". Or, from the other perspective, the SOAP part of any message that is received must
+ * have the MIME header Content-Type with a value of "text/xml".</P>
+ * <p/>
+ * <P>A client can access the <CODE>SOAPPart</CODE> object of a <CODE>SOAPMessage</CODE> object by
+ * calling the method <CODE> SOAPMessage.getSOAPPart</CODE>. The following line of code, in which
+ * <CODE>message</CODE> is a <CODE>SOAPMessage</CODE> object, retrieves the SOAP part of a
+ * message.</P> <PRE> SOAPPart soapPart = message.getSOAPPart(); </PRE>
+ * <p/>
+ * <P>A <CODE>SOAPPart</CODE> object contains a <CODE> SOAPEnvelope</CODE> object, which in turn
+ * contains a <CODE> SOAPBody</CODE> object and a <CODE>SOAPHeader</CODE> object. The
+ * <CODE>SOAPPart</CODE> method <CODE>getEnvelope</CODE> can be used to retrieve the
+ * <CODE>SOAPEnvelope</CODE> object.</P>
  */
-public abstract class SOAPPart implements org.w3c.dom.Document {
+public abstract class SOAPPart implements javax.xml.soap.Node, org.w3c.dom.Document {
 
-    public SOAPPart() {}
+    public SOAPPart() {
+    }
 
     /**
-     * Gets the <CODE>SOAPEnvelope</CODE> object associated with
-     * this <CODE>SOAPPart</CODE> object. Once the SOAP envelope is
-     * obtained, it can be used to get its contents.
-     * @return the <CODE>SOAPEnvelope</CODE> object for this <CODE>
-     *     SOAPPart</CODE> object
-     * @throws  SOAPException if there is a SOAP error
+     * Gets the <CODE>SOAPEnvelope</CODE> object associated with this <CODE>SOAPPart</CODE> object.
+     * Once the SOAP envelope is obtained, it can be used to get its contents.
+     *
+     * @return the <CODE>SOAPEnvelope</CODE> object for this <CODE> SOAPPart</CODE> object
+     * @throws SOAPException if there is a SOAP error
      */
     public abstract SOAPEnvelope getEnvelope() throws SOAPException;
 
     /**
-     * Retrieves the value of the MIME header whose name is
-     * "Content-Id".
-     * @return  a <CODE>String</CODE> giving the value of the MIME
-     *     header named "Content-Id"
-     * @see #setContentId(java.lang.String) setContentId(java.lang.String)
+     * Retrieves the value of the MIME header whose name is "Content-Id".
+     *
+     * @return a <CODE>String</CODE> giving the value of the MIME header named "Content-Id"
+     * @see #setContentId(String) setContentId(java.lang.String)
      */
     public String getContentId() {
 
@@ -93,11 +79,11 @@
     }
 
     /**
-     * Retrieves the value of the MIME header whose name is
-     * "Content-Location".
-     * @return a <CODE>String</CODE> giving the value of the MIME
-     *     header whose name is "Content-Location"
-     * @see #setContentLocation(java.lang.String) setContentLocation(java.lang.String)
+     * Retrieves the value of the MIME header whose name is "Content-Location".
+     *
+     * @return a <CODE>String</CODE> giving the value of the MIME header whose name is
+     *         "Content-Location"
+     * @see #setContentLocation(String) setContentLocation(java.lang.String)
      */
     public String getContentLocation() {
 
@@ -111,12 +97,11 @@
     }
 
     /**
-     * Sets the value of the MIME header named "Content-Id" to
-     * the given <CODE>String</CODE>.
-     * @param  contentId  a <CODE>String</CODE> giving
-     *     the value of the MIME header "Content-Id"
-     * @throws java.lang.IllegalArgumentException if
-     *     there is a problem in setting the content id
+     * Sets the value of the MIME header named "Content-Id" to the given <CODE>String</CODE>.
+     *
+     * @param contentId a <CODE>String</CODE> giving the value of the MIME header "Content-Id"
+     * @throws IllegalArgumentException
+     *          if there is a problem in setting the content id
      * @see #getContentId() getContentId()
      */
     public void setContentId(String contentId) {
@@ -124,13 +109,12 @@
     }
 
     /**
-     * Sets the value of the MIME header "Content-Location" to
-     * the given <CODE>String</CODE>.
-     * @param  contentLocation a <CODE>String</CODE>
-     *     giving the value of the MIME header
-     *     "Content-Location"
-     * @throws java.lang.IllegalArgumentException if
-     *     there is a problem in setting the content location.
+     * Sets the value of the MIME header "Content-Location" to the given <CODE>String</CODE>.
+     *
+     * @param contentLocation a <CODE>String</CODE> giving the value of the MIME header
+     *                        "Content-Location"
+     * @throws IllegalArgumentException
+     *          if there is a problem in setting the content location.
      * @see #getContentLocation() getContentLocation()
      */
     public void setContentLocation(String contentLocation) {
@@ -139,126 +123,107 @@
 
     /**
      * Removes all MIME headers that match the given name.
-     * @param  header  a <CODE>String</CODE> giving
-     *     the name of the MIME header(s) to be removed
+     *
+     * @param header a <CODE>String</CODE> giving the name of the MIME header(s) to be removed
      */
     public abstract void removeMimeHeader(String header);
 
-    /**
-     * Removes all the <CODE>MimeHeader</CODE> objects for this
-     * <CODE>SOAPEnvelope</CODE> object.
-     */
+    /** Removes all the <CODE>MimeHeader</CODE> objects for this <CODE>SOAPEnvelope</CODE> object. */
     public abstract void removeAllMimeHeaders();
 
     /**
-     * Gets all the values of the <CODE>MimeHeader</CODE> object
-     * in this <CODE>SOAPPart</CODE> object that is identified by
-     * the given <CODE>String</CODE>.
-     * @param   name  the name of the header; example:
-     *     "Content-Type"
-     * @return a <CODE>String</CODE> array giving all the values for
-     *     the specified header
-     * @see #setMimeHeader(java.lang.String, java.lang.String) setMimeHeader(java.lang.String, java.lang.String)
+     * Gets all the values of the <CODE>MimeHeader</CODE> object in this <CODE>SOAPPart</CODE>
+     * object that is identified by the given <CODE>String</CODE>.
+     *
+     * @param name the name of the header; example: "Content-Type"
+     * @return a <CODE>String</CODE> array giving all the values for the specified header
+     * @see #setMimeHeader(String, String) setMimeHeader(java.lang.String,
+     *      java.lang.String)
      */
     public abstract String[] getMimeHeader(String name);
 
     /**
-     * Changes the first header entry that matches the given
-     *   header name so that its value is the given value, adding a
-     *   new header with the given name and value if no existing
-     *   header is a match. If there is a match, this method clears
-     *   all existing values for the first header that matches and
-     *   sets the given value instead. If more than one header has
-     *   the given name, this method removes all of the matching
-     *   headers after the first one.
-     *
-     *   <P>Note that RFC822 headers can contain only US-ASCII
-     *   characters.</P>
-     * @param  name a <CODE>String</CODE> giving the
-     *     header name for which to search
-     * @param  value a <CODE>String</CODE> giving the
-     *     value to be set. This value will be substituted for the
-     *     current value(s) of the first header that is a match if
-     *     there is one. If there is no match, this value will be
-     *     the value for a new <CODE>MimeHeader</CODE> object.
-     * @throws java.lang.IllegalArgumentException if
-     *     there was a problem with the specified mime header name
-     *     or value
-     * @throws java.lang.IllegalArgumentException if there was a problem with the specified mime header name or value
-     * @see #getMimeHeader(java.lang.String) getMimeHeader(java.lang.String)
+     * Changes the first header entry that matches the given header name so that its value is the
+     * given value, adding a new header with the given name and value if no existing header is a
+     * match. If there is a match, this method clears all existing values for the first header that
+     * matches and sets the given value instead. If more than one header has the given name, this
+     * method removes all of the matching headers after the first one.
+     * <p/>
+     * <P>Note that RFC822 headers can contain only US-ASCII characters.</P>
+     *
+     * @param name  a <CODE>String</CODE> giving the header name for which to search
+     * @param value a <CODE>String</CODE> giving the value to be set. This value will be substituted
+     *              for the current value(s) of the first header that is a match if there is one. If
+     *              there is no match, this value will be the value for a new
+     *              <CODE>MimeHeader</CODE> object.
+     * @throws IllegalArgumentException
+     *          if there was a problem with the specified mime header name or value
+     * @throws IllegalArgumentException
+     *          if there was a problem with the specified mime header name or value
+     * @see #getMimeHeader(String) getMimeHeader(java.lang.String)
      */
     public abstract void setMimeHeader(String name, String value);
 
     /**
-     *  Creates a <CODE>MimeHeader</CODE> object with the specified
-     *   name and value and adds it to this <CODE>SOAPPart</CODE>
-     *   object. If a <CODE>MimeHeader</CODE> with the specified
-     *   name already exists, this method adds the specified value
-     *   to the already existing value(s).
-     *
-     *   <P>Note that RFC822 headers can contain only US-ASCII
-     *   characters.</P>
-     *
-     * @param  name a <CODE>String</CODE> giving the
-     *     header name
-     * @param  value a <CODE>String</CODE> giving the
-     *     value to be set or added
-     * @throws java.lang.IllegalArgumentException if
-     * there was a problem with the specified mime header name
-     *     or value
+     * Creates a <CODE>MimeHeader</CODE> object with the specified name and value and adds it to
+     * this <CODE>SOAPPart</CODE> object. If a <CODE>MimeHeader</CODE> with the specified name
+     * already exists, this method adds the specified value to the already existing value(s).
+     * <p/>
+     * <P>Note that RFC822 headers can contain only US-ASCII characters.</P>
+     *
+     * @param name  a <CODE>String</CODE> giving the header name
+     * @param value a <CODE>String</CODE> giving the value to be set or added
+     * @throws IllegalArgumentException
+     *          if there was a problem with the specified mime header name or value
      */
     public abstract void addMimeHeader(String name, String value);
 
     /**
-     * Retrieves all the headers for this <CODE>SOAPPart</CODE>
-     * object as an iterator over the <CODE>MimeHeader</CODE>
-     * objects.
-     * @return an <CODE>Iterator</CODE> object with all of the Mime
-     *     headers for this <CODE>SOAPPart</CODE> object
+     * Retrieves all the headers for this <CODE>SOAPPart</CODE> object as an iterator over the
+     * <CODE>MimeHeader</CODE> objects.
+     *
+     * @return an <CODE>Iterator</CODE> object with all of the Mime headers for this
+     *         <CODE>SOAPPart</CODE> object
      */
     public abstract Iterator getAllMimeHeaders();
 
     /**
-     * Retrieves all <CODE>MimeHeader</CODE> objects that match
-     * a name in the given array.
-     * @param   names a <CODE>String</CODE> array with
-     *     the name(s) of the MIME headers to be returned
-     * @return all of the MIME headers that match one of the names
-     *     in the given array, returned as an <CODE>Iterator</CODE>
-     *     object
+     * Retrieves all <CODE>MimeHeader</CODE> objects that match a name in the given array.
+     *
+     * @param names a <CODE>String</CODE> array with the name(s) of the MIME headers to be returned
+     * @return all of the MIME headers that match one of the names in the given array, returned as
+     *         an <CODE>Iterator</CODE> object
      */
     public abstract Iterator getMatchingMimeHeaders(String names[]);
 
     /**
-     * Retrieves all <CODE>MimeHeader</CODE> objects whose name
-     * does not match a name in the given array.
-     * @param   names a <CODE>String</CODE> array with
-     *     the name(s) of the MIME headers not to be returned
-     * @return all of the MIME headers in this <CODE>SOAPPart</CODE>
-     *     object except those that match one of the names in the
-     *     given array. The nonmatching MIME headers are returned as
-     *     an <CODE>Iterator</CODE> object.
+     * Retrieves all <CODE>MimeHeader</CODE> objects whose name does not match a name in the given
+     * array.
+     *
+     * @param names a <CODE>String</CODE> array with the name(s) of the MIME headers not to be
+     *              returned
+     * @return all of the MIME headers in this <CODE>SOAPPart</CODE> object except those that match
+     *         one of the names in the given array. The nonmatching MIME headers are returned as an
+     *         <CODE>Iterator</CODE> object.
      */
     public abstract Iterator getNonMatchingMimeHeaders(String names[]);
 
     /**
-     * Sets the content of the <CODE>SOAPEnvelope</CODE> object
-     * with the data from the given <CODE>Source</CODE> object.
-     * @param   source javax.xml.transform.Source</CODE> object with the data to
-     *     be set
-     * @throws  SOAPException if there is a problem in
-     *     setting the source
+     * Sets the content of the <CODE>SOAPEnvelope</CODE> object with the data from the given
+     * <CODE>Source</CODE> object.
+     *
+     * @param source javax.xml.transform.Source</CODE> object with the data to be set
+     * @throws SOAPException if there is a problem in setting the source
      * @see #getContent() getContent()
      */
     public abstract void setContent(Source source) throws SOAPException;
 
     /**
-     * Returns the content of the SOAPEnvelope as a JAXP <CODE>
-     * Source</CODE> object.
-     * @return the content as a <CODE>
-     *     javax.xml.transform.Source</CODE> object
-     * @throws  SOAPException  if the implementation cannot
-     *     convert the specified <CODE>Source</CODE> object
+     * Returns the content of the SOAPEnvelope as a JAXP <CODE> Source</CODE> object.
+     *
+     * @return the content as a <CODE> javax.xml.transform.Source</CODE> object
+     * @throws SOAPException if the implementation cannot convert the specified <CODE>Source</CODE>
+     *                       object
      * @see #setContent(javax.xml.transform.Source) setContent(javax.xml.transform.Source)
      */
     public abstract Source getContent() throws SOAPException;

Modified: geronimo/specs/trunk/geronimo-saaj_1.3_spec/src/main/java/javax/xml/soap/Text.java
URL: http://svn.apache.org/viewvc/geronimo/specs/trunk/geronimo-saaj_1.3_spec/src/main/java/javax/xml/soap/Text.java?rev=601048&r1=600870&r2=601048&view=diff
==============================================================================
--- geronimo/specs/trunk/geronimo-saaj_1.3_spec/src/main/java/javax/xml/soap/Text.java (original)
+++ geronimo/specs/trunk/geronimo-saaj_1.3_spec/src/main/java/javax/xml/soap/Text.java Tue Dec  4 11:25:44 2007
@@ -1,36 +1,34 @@
 /*
  * Licensed to the Apache Software Foundation (ASF) under one
- * or more contributor license agreements.  See the NOTICE file
+ * or more contributor license agreements. See the NOTICE file
  * distributed with this work for additional information
- * regarding copyright ownership.  The ASF licenses this file
+ * regarding copyright ownership. The ASF licenses this file
  * to you under the Apache License, Version 2.0 (the
  * "License"); you may not use this file except in compliance
- * with the License.  You may obtain a copy of the License at
+ * with the License. You may obtain a copy of the License at
  *
- *  http://www.apache.org/licenses/LICENSE-2.0
+ * http://www.apache.org/licenses/LICENSE-2.0
  *
  * Unless required by applicable law or agreed to in writing,
  * software distributed under the License is distributed on an
  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- * KIND, either express or implied.  See the License for the
+ * KIND, either express or implied. See the License for the
  * specific language governing permissions and limitations
  * under the License.
  */
-
 package javax.xml.soap;
 
 /**
- * A representation of a node whose value is text. A <CODE>
- *   Text</CODE> object may represent text that is content or text
- *   that is a comment.
+ * A representation of a node whose value is text. A <CODE> Text</CODE> object may represent text
+ * that is content or text that is a comment.
  */
 public interface Text extends Node, org.w3c.dom.Text {
 
     /**
-     * Retrieves whether this <CODE>Text</CODE> object
-     * represents a comment.
-     * @return  <CODE>true</CODE> if this <CODE>Text</CODE> object is
-     *     a comment; <CODE>false</CODE> otherwise
+     * Retrieves whether this <CODE>Text</CODE> object represents a comment.
+     *
+     * @return <CODE>true</CODE> if this <CODE>Text</CODE> object is a comment; <CODE>false</CODE>
+     *         otherwise
      */
     public abstract boolean isComment();
 }

Modified: geronimo/specs/trunk/pom.xml
URL: http://svn.apache.org/viewvc/geronimo/specs/trunk/pom.xml?rev=601048&r1=601047&r2=601048&view=diff
==============================================================================
--- geronimo/specs/trunk/pom.xml (original)
+++ geronimo/specs/trunk/pom.xml Tue Dec  4 11:25:44 2007
@@ -148,7 +148,7 @@
         <module>geronimo-jms_1.1_spec</module>
         <module>geronimo-jta_1.1_spec</module>
         <module>geronimo-servlet_2.5_spec</module>
-        <module>geronimo-saaj_1.1_spec</module>
+        <module>geronimo-saaj_1.3_spec</module>
         <module>geronimo-stax-api_1.0_spec</module>
     </modules>
 



Mime
View raw message