--- old/src/java.xml.ws/share/classes/javax/xml/soap/SOAPMessage.java 2015-04-21 17:20:16.208098476 +0400 +++ new/src/java.xml.ws/share/classes/javax/xml/soap/SOAPMessage.java 2015-04-21 17:20:16.116098476 +0400 @@ -36,24 +36,24 @@ * 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 + * A {@code SOAPMessage} object consists of a SOAP part and optionally + * one or more attachment parts. The SOAP part for a {@code SOAPMessage} + * object is a {@code 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 new {@code SOAPMessage} object contains the following by default: *

- * 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. + * The SOAP part of a message can be retrieved by calling the method {@code SOAPMessage.getSOAPPart()}. + * The {@code SOAPEnvelope} object is retrieved from the {@code SOAPPart} + * object, and the {@code SOAPEnvelope} object is used to retrieve the + * {@code SOAPBody} and {@code SOAPHeader} objects. * * 
  *     SOAPPart sp = message.getSOAPPart();
@@ -63,32 +63,32 @@
  *
* *

- * 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 + * In addition to the mandatory {@code SOAPPart} object, a {@code SOAPMessage} + * object may contain zero or more {@code AttachmentPart} objects, each + * of which contains application-specific data. The {@code SOAPMessage} + * interface provides methods for creating {@code AttachmentPart} + * objects and also for adding them to a {@code SOAPMessage} object. A + * party that has received a {@code 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. + * {@code AttachmentPart} object. *

- * A MessageFactory object may create SOAPMessage + * A {@code MessageFactory} object may create {@code 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 + * application of SAAJ. For instance, a {@code MessageFactory} object + * may produce {@code SOAPMessage} objects that conform to a particular + * Profile such as ebXML. In this case a {@code MessageFactory} object + * might produce {@code 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 + * implementations simply throw an {@code 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 @@ -126,41 +126,40 @@ "javax.xml.soap.write-xml-declaration"; /** - * Sets the description of this SOAPMessage object's + * Sets the description of this {@code SOAPMessage} object's * content with the given description. * - * @param description a String describing the content of this + * @param description a {@code String} describing the content of this * message * @see #getContentDescription */ public abstract void setContentDescription(String description); /** - * Retrieves a description of this SOAPMessage object's + * Retrieves a description of this {@code SOAPMessage} object's * content. * - * @return a String describing the content of this - * message or null if no description has been set + * @return a {@code String} describing the content of this + * message or {@code null} if no description has been set * @see #setContentDescription */ public abstract String getContentDescription(); /** - * Gets the SOAP part of this SOAPMessage object. + * Gets the SOAP part of this {@code SOAPMessage} object. *

- * SOAPMessage object contains one or more attachments, the + * {@code 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 + * @return the {@code SOAPPart} object for this {@code SOAPMessage} * object */ public abstract SOAPPart getSOAPPart(); /** - * Gets the SOAP Body contained in this SOAPMessage object. - *

+ * Gets the SOAP Body contained in this {@code SOAPMessage} object. * - * @return the SOAPBody object contained by this SOAPMessage + * @return the {@code SOAPBody} object contained by this {@code SOAPMessage} * object * @exception SOAPException * if the SOAP Body does not exist or cannot be retrieved @@ -171,23 +170,21 @@ } /** - * 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 1.6, SAAJ 1.2 - */ + * Gets the SOAP Header contained in this {@code SOAPMessage} object. + * + * @return the {@code SOAPHeader} object contained + * by this {@code SOAPMessage} object + * @exception SOAPException + * if the SOAP Header does not exist or cannot be retrieved + * @since 1.6, 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. + * Removes all {@code AttachmentPart} objects that have been added + * to this {@code SOAPMessage} object. *

* This method does not touch the SOAP part. */ @@ -197,26 +194,26 @@ * 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 + * @return the number of {@code AttachmentPart} objects that are + * part of this {@code SOAPMessage} object */ public abstract int countAttachments(); /** - * Retrieves all the AttachmentPart objects that are part of - * this SOAPMessage object. + * Retrieves all the {@code AttachmentPart} objects that are part of + * this {@code SOAPMessage} object. * * @return an iterator over all the attachments in this message */ public abstract Iterator getAttachments(); /** - * Retrieves all the AttachmentPart objects that have header + * Retrieves all the {@code 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 + * a {@code 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 @@ -224,12 +221,12 @@ public abstract Iterator getAttachments(MimeHeaders headers); /** - * Removes all the AttachmentPart objects that have header + * Removes all the {@code 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 + * a {@code MimeHeaders} object containing the MIME * headers for which to search * @since 1.6, SAAJ 1.3 */ @@ -237,25 +234,26 @@ /** - * 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 + * Returns an {@code AttachmentPart} object that is associated with an + * attachment that is referenced by this {@code SOAPElement} or + * {@code null} if no such attachment exists. References can be made + * via an {@code href} attribute as described in + * SOAP Messages with Attachments, + * or via a single {@code 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 + * type ref:swaRef. + * These two mechanisms must be supported. + * The support for references via {@code href} attribute also implies that * this method should also be supported on an element that is an * xop:Include element ( - * {@link XOP}). + * 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. + * @param element The {@code SOAPElement} containing the reference to an Attachment + * @return the referenced {@code AttachmentPart} or null if no such + * {@code AttachmentPart} exists or no reference can be + * found in this {@code SOAPElement}. * @throws SOAPException if there is an error in the attempt to access the * attachment * @@ -265,40 +263,40 @@ /** - * Adds the given AttachmentPart object to this SOAPMessage - * object. An AttachmentPart object must be created before + * Adds the given {@code AttachmentPart} object to this {@code SOAPMessage} + * object. An {@code 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 + * an {@code AttachmentPart} object that is to become part + * of this {@code 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. + * Creates a new empty {@code AttachmentPart} object. Note that the + * method {@code addAttachmentPart} must be called with this new + * {@code AttachmentPart} object as the parameter in order for it to + * become an attachment to this {@code SOAPMessage} object. * - * @return a new AttachmentPart object that can be populated - * and added to this SOAPMessage object + * @return a new {@code AttachmentPart} object that can be populated + * and added to this {@code SOAPMessage} object */ public abstract AttachmentPart createAttachmentPart(); /** - * Creates an AttachmentPart object and populates it using - * the given DataHandler object. + * Creates an {@code AttachmentPart} object and populates it using + * the given {@code DataHandler} object. * * @param dataHandler - * the javax.activation.DataHandler object that - * will generate the content for this SOAPMessage + * the {@code javax.activation.DataHandler} object that + * will generate the content for this {@code SOAPMessage} * object - * @return a new AttachmentPart object that contains data - * generated by the given DataHandler object + * @return a new {@code AttachmentPart} object that contains data + * generated by the given {@code DataHandler} object * @exception IllegalArgumentException - * if there was a problem with the specified DataHandler + * if there was a problem with the specified {@code DataHandler} * object * @see javax.activation.DataHandler * @see javax.activation.DataContentHandler @@ -310,32 +308,32 @@ } /** - * Returns all the transport-specific MIME headers for this SOAPMessage + * Returns all the transport-specific MIME headers for this {@code SOAPMessage} * object in a transport-independent fashion. * - * @return a MimeHeaders object containing the MimeHeader + * @return a {@code MimeHeaders} object containing the {@code MimeHeader} * objects */ public abstract MimeHeaders getMimeHeaders(); /** - * Creates an AttachmentPart object and populates it with + * Creates an {@code 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. + * {@code Object} should correspond to the value given for the + * {@code Content-Type}. * * @param content - * an Object containing the content for the - * AttachmentPart object to be created + * an {@code Object} containing the content for the + * {@code AttachmentPart} object to be created * @param contentType - * a String object giving the type of content; + * a {@code String} object giving the type of content; * examples are "text/xml", "text/plain", and "image/jpeg" - * @return a new AttachmentPart object that contains the + * @return a new {@code 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 + * {@code DataContentHandler} object for the given * content object * @see javax.activation.DataHandler * @see javax.activation.DataContentHandler @@ -349,50 +347,49 @@ } /** - * Updates this SOAPMessage object with all the changes that + * Updates this {@code 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 + * already been sent, the method {@code saveChanges} needs to be + * called explicitly in order to save the changes. The method {@code 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. + * valid values only after {@code saveChanges} has been called. *

* In addition, this method marks the point at which the data from all - * constituent AttachmentPart objects are pulled into the + * constituent {@code AttachmentPart} objects are pulled into the * message. - *

* - * @exception SOAPException if there was a problem saving - * changes to this 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. + * Indicates whether this {@code SOAPMessage} object needs to have + * the method {@code saveChanges} called on it. * - * @return true if saveChanges needs to be - * called; false otherwise. + * @return {@code true} if {@code saveChanges} needs to be + * called; {@code false} otherwise. */ public abstract boolean saveRequired(); /** - * Writes this SOAPMessage object to the given output + * Writes this {@code 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 + * those messages that have attachments, {@code 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 + * the {@code OutputStream} object to which this {@code SOAPMessage} * object will be written * @exception IOException * if an I/O error occurs @@ -414,13 +411,13 @@ * 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" + * Setting the property {@code WRITE_XML_DECLARATION} to {@code "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" + * The property {@code CHARACTER_SET_ENCODING} defaults to the value + * {@code "utf-8"} which causes the SOAP message to be encoded using + * UTF-8. Setting {@code CHARACTER_SET_ENCODING} to {@code "utf-16"} * causes the SOAP message to be encoded using UTF-16. *

* Some implementations may allow encodings in addition to UTF-8 and @@ -445,7 +442,7 @@ * * @param property * the name of the property to retrieve - * @return the value associated with the named property or null + * @return the value associated with the named property or {@code null} * if no such property exists. * @exception SOAPException * if the property name is not recognized.