stan/jdk-24
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

8077332: tidy warnings from javax/xml

Browse Source 
Some HTML markup fix (jaxws part)

Reviewed-by: joehw, lancea
This commit is contained in:
Alexander Stepanov 2015-04-22 15:26:20 +04:00
parent 7cbdcf978d
commit 078abb2617
31 changed files with 994 additions and 1058 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

58
jaxws/src/java.activation/share/classes/javax/activation/MailcapCommandMap.java
View File

@ -45,14 +45,13 @@ import com.sun.activation.registries.LogSupport;
* system for mailcap file entries. When requests are made
* to search for commands in the MailcapCommandMap, it searches
* mailcap files in the following order:
* <p>
* <ol>
* <li> Programatically added entries to the MailcapCommandMap instance.
* <li> The file <code>.mailcap</code> in the user's home directory.
* <li> The file &lt;<i>java.home</i>&gt;<code>/lib/mailcap</code>.
* <li> The file or resources named <code>META-INF/mailcap</code>.
* <li> The file or resource named <code>META-INF/mailcap.default</code>
* (usually found only in the <code>activation.jar</code> file).
* <li> The file {@code .mailcap} in the user's home directory.
* <li> The file {@literal <}<i>java.home</i>{@literal >}{@code /lib/mailcap}.
* <li> The file or resources named {@code META-INF/mailcap}.
* <li> The file or resource named {@code META-INF/mailcap.default}
* (usually found only in the {@code activation.jar} file).
* </ol>
* <p>
* <b>Mailcap file format:</b><p>
@ -70,46 +69,43 @@ import com.sun.activation.registries.LogSupport;
*
* When a mailcap file is
* parsed, the MailcapCommandMap recognizes certain parameter signatures,
* specifically those parameter names that begin with <code>x-java-</code>.
* specifically those parameter names that begin with {@code x-java-}.
* The MailcapCommandMap uses this signature to find
* command entries for inclusion into its registries.
* Parameter names with the form <code>x-java-&lt;name></code>
* Parameter names with the form {@code x-java-<name>}
* are read by the MailcapCommandMap as identifying a command
* with the name <i>name</i>. When the <i>name</i> is <code>
* content-handler</code> the MailcapCommandMap recognizes the class
* with the name <i>name</i>. When the <i>name</i> is {@code
* content-handler} the MailcapCommandMap recognizes the class
* signified by this parameter as a <i>DataContentHandler</i>.
* All other commands are handled generically regardless of command
* name. The command implementation is specified by a fully qualified
* class name of a JavaBean(tm) component. For example; a command for viewing
* some data can be specified as: <code>x-java-view=com.foo.ViewBean</code>.<p>
* some data can be specified as: {@code x-java-view=com.foo.ViewBean}.<p>
*
* When the command name is <code>fallback-entry</code>, the value of
* the command may be <code>true</code> or <code>false</code>. An
* When the command name is {@code fallback-entry}, the value of
* the command may be {@code true} or {@code false}. An
* entry for a MIME type that includes a parameter of
* <code>x-java-fallback-entry=true</code> defines fallback commands
* {@code x-java-fallback-entry=true} defines fallback commands
* for that MIME type that will only be used if no non-fallback entry
* can be found. For example, an entry of the form <code>text/*; ;
* x-java-fallback-entry=true; x-java-view=com.sun.TextViewer</code>
* can be found. For example, an entry of the form {@code text/*; ;
* x-java-fallback-entry=true; x-java-view=com.sun.TextViewer}
* specifies a view command to be used for any text MIME type. This
* view command would only be used if a non-fallback view command for
* the MIME type could not be found.<p>
*
* MailcapCommandMap aware mailcap files have the
* following general form:<p>
* <code>
* # Comments begin with a '#' and continue to the end of the line.<br>
* &lt;mime type>; ; &lt;parameter list><br>
* # Where a parameter list consists of one or more parameters,<br>
* # where parameters look like: x-java-view=com.sun.TextViewer<br>
* # and a parameter list looks like: <br>
* following general form:
* <pre>{@code
* # Comments begin with a '#' and continue to the end of the line.
* <mime type>; ; <parameter list>
* # Where a parameter list consists of one or more parameters,
* # where parameters look like: x-java-view=com.sun.TextViewer
* # and a parameter list looks like:
* text/plain; ; x-java-view=com.sun.TextViewer; x-java-edit=com.sun.TextEdit
* <br>
* # Note that mailcap entries that do not contain 'x-java' parameters<br>
* # and comply to RFC 1524 are simply ignored:<br>
* image/gif; /usr/dt/bin/sdtimage %s<br>
*
* </code>
* <p>
* # Note that mailcap entries that do not contain 'x-java' parameters
* # and comply to RFC 1524 are simply ignored:
* image/gif; /usr/dt/bin/sdtimage %s
* }</pre>
*
* @author Bart Calder
* @author Bill Shannon
@ -451,7 +447,7 @@ public class MailcapCommandMap extends CommandMap {
}
/**
* Get the command corresponding to <code>cmdName</code> for the MIME type.
* Get the command corresponding to {@code cmdName} for the MIME type.
*
* @param mimeType the MIME type
* @param cmdName the command name

33
jaxws/src/java.activation/share/classes/javax/activation/MimetypesFileTypeMap.java
View File

@ -33,33 +33,32 @@ import com.sun.activation.registries.LogSupport;
/**
* This class extends FileTypeMap and provides data typing of files
* via their file extension. It uses the <code>.mime.types</code> format. <p>
* via their file extension. It uses the {@code .mime.types} format. <p>
*
* <b>MIME types file search order:</b><p>
* The MimetypesFileTypeMap looks in various places in the user's
* system for MIME types file entries. When requests are made
* to search for MIME types in the MimetypesFileTypeMap, it searches
* MIME types files in the following order:
* <p>
* <ol>
* <li> Programmatically added entries to the MimetypesFileTypeMap instance.
* <li> The file <code>.mime.types</code> in the user's home directory.
* <li> The file &lt;<i>java.home</i>&gt;<code>/lib/mime.types</code>.
* <li> The file or resources named <code>META-INF/mime.types</code>.
* <li> The file or resource named <code>META-INF/mimetypes.default</code>
* (usually found only in the <code>activation.jar</code> file).
* <li> The file {@code .mime.types} in the user's home directory.
* <li> The file {@literal <}<i>java.home</i>{@literal >}{@code /lib/mime.types}.
* <li> The file or resources named {@code META-INF/mime.types}.
* <li> The file or resource named {@code META-INF/mimetypes.default}
* (usually found only in the {@code activation.jar} file).
* </ol>
* <p>
* <b>MIME types file format:</b><p>
* <b>MIME types file format:</b>
*
* <code>
* # comments begin with a '#'<br>
* # the format is &lt;mime type> &lt;space separated file extensions><br>
* # for example:<br>
* text/plain txt text TXT<br>
* # this would map file.txt, file.text, and file.TXT to<br>
* # the mime type "text/plain"<br>
* </code>
* <pre>{@code
* # comments begin with a '#'
* # the format is <mime type> <space separated file extensions>
* # for example:
* text/plain txt text TXT
* # this would map file.txt, file.text, and file.TXT to
* # the mime type "text/plain"
* }</pre>
*
* @author Bart Calder
* @author Bill Shannon
@ -277,7 +276,7 @@ public class MimetypesFileTypeMap extends FileTypeMap {
/**
* Return the MIME type of the file object.
* The implementation in this class calls
* <code>getContentType(f.getName())</code>.
* {@code getContentType(f.getName())}.
*
* @param f the file
* @return the file's MIME type

1
jaxws/src/java.annotations.common/share/classes/javax/annotation/PostConstruct.java
View File

@ -39,7 +39,6 @@ import static java.lang.annotation.RetentionPolicy.*;
* method can be annotated with this annotation. The method on which the
* PostConstruct annotation is applied MUST fulfill all of the following
* criteria:
* <p>
* <ul>
* <li>The method MUST NOT have any parameters except in the case of
* interceptors in which case it takes an InvocationContext object as

1
jaxws/src/java.annotations.common/share/classes/javax/annotation/PreDestroy.java
View File

@ -38,7 +38,6 @@ import static java.lang.annotation.RetentionPolicy.*;
* except the application client container in Java EE 5. The method on which
* the PreDestroy annotation is applied MUST fulfill all of the following
* criteria:
* <p>
* <ul>
* <li>The method MUST NOT have any parameters except in the case of
* interceptors in which case it takes an InvocationContext object as

69
jaxws/src/java.xml.bind/share/classes/javax/xml/bind/DatatypeConverterInterface.java
View File

@ -38,19 +38,16 @@ package javax.xml.bind;
* functionality. Calling this api repeatedly will have no effect - the
* DatatypeConverter instance passed into the first invocation is the one that
* will be used from then on.
* </p>
*
* <p>
* This interface defines the parse and print methods. There is one
* parse and print method for each XML schema datatype specified in the
* the default binding Table 5-1 in the JAXB specification.
* </p>
*
* <p>
* The parse and print methods defined here are invoked by the static parse
* and print methods defined in the {@link DatatypeConverter DatatypeConverter}
* class.
* </p>
*
* <p>
* A parse method for a XML schema datatype must be capable of converting any
@ -60,21 +57,23 @@ package javax.xml.bind;
* If an error is encountered during conversion, then an IllegalArgumentException
* or a subclass of IllegalArgumentException must be thrown by the method.
*
* </p>
*
* <p>
* A print method for a XML schema datatype can output any lexical
* representation that is valid with respect to the XML schema datatype.
* If an error is encountered during conversion, then an IllegalArgumentException,
* or a subclass of IllegalArgumentException must be thrown by the method.
* </p>
*
* <p>
* The prefix xsd: is used to refer to XML schema datatypes
* <a href="http://www.w3.org/TR/xmlschema-2/"> XML Schema Part2: Datatypes
* specification.</a>
*
* <p>
* @author <ul><li>Sekhar Vajjhala, Sun Microsystems, Inc.</li><li>Joe Fialli, Sun Microsystems Inc.</li><li>Kohsuke Kawaguchi, Sun Microsystems, Inc.</li><li>Ryan Shoemaker,Sun Microsystems Inc.</li></ul>
* @author <ul>
* <li>Sekhar Vajjhala, Sun Microsystems, Inc.</li>
* <li>Joe Fialli, Sun Microsystems Inc.</li>
* <li>Kohsuke Kawaguchi, Sun Microsystems, Inc.</li>
* <li>Ryan Shoemaker,Sun Microsystems Inc.</li>
* </ul>
* @see DatatypeConverter
* @see ParseConversionEvent
* @see PrintConversionEvent
@ -83,7 +82,6 @@ package javax.xml.bind;
public interface DatatypeConverterInterface {
/**
* <p>
* Convert the string argument into a string.
* @param lexicalXSDString
* A lexical representation of the XML Schema datatype xsd:string
@ -93,91 +91,83 @@ public interface DatatypeConverterInterface {
public String parseString( String lexicalXSDString );
/**
* <p>
* Convert the string argument into a BigInteger value.
* @param lexicalXSDInteger
* A string containing a lexical representation of
* xsd:integer.
* @return
* A BigInteger value represented by the string argument.
* @throws NumberFormatException <code>lexicalXSDInteger</code> is not a valid string representation of a {@link java.math.BigInteger} value.
* @throws NumberFormatException {@code lexicalXSDInteger} is not a valid string representation of a {@link java.math.BigInteger} value.
*/
public java.math.BigInteger parseInteger( String lexicalXSDInteger );
/**
* <p>
* Convert the string argument into an int value.
* @param lexicalXSDInt
* A string containing a lexical representation of
* xsd:int.
* @return
* An int value represented byte the string argument.
* @throws NumberFormatException <code>lexicalXSDInt</code> is not a valid string representation of an <code>int</code> value.
* @throws NumberFormatException {@code lexicalXSDInt} is not a valid string representation of an {@code int} value.
*/
public int parseInt( String lexicalXSDInt );
/**
* <p>
* Converts the string argument into a long value.
* @param lexicalXSDLong
* A string containing lexical representation of
* xsd:long.
* @return
* A long value represented by the string argument.
* @throws NumberFormatException <code>lexicalXSDLong</code> is not a valid string representation of a <code>long</code> value.
* @throws NumberFormatException {@code lexicalXSDLong} is not a valid string representation of a {@code long} value.
*/
public long parseLong( String lexicalXSDLong );
/**
* <p>
* Converts the string argument into a short value.
* @param lexicalXSDShort
* A string containing lexical representation of
* xsd:short.
* @return
* A short value represented by the string argument.
* @throws NumberFormatException <code>lexicalXSDShort</code> is not a valid string representation of a <code>short</code> value.
* @throws NumberFormatException {@code lexicalXSDShort} is not a valid string representation of a {@code short} value.
*/
public short parseShort( String lexicalXSDShort );
/**
* <p>
* Converts the string argument into a BigDecimal value.
* @param lexicalXSDDecimal
* A string containing lexical representation of
* xsd:decimal.
* @return
* A BigDecimal value represented by the string argument.
* @throws NumberFormatException <code>lexicalXSDDecimal</code> is not a valid string representation of {@link java.math.BigDecimal}.
* @throws NumberFormatException {@code lexicalXSDDecimal} is not a valid string representation of {@link java.math.BigDecimal}.
*/
public java.math.BigDecimal parseDecimal( String lexicalXSDDecimal );
/**
* <p>
* Converts the string argument into a float value.
* @param lexicalXSDFloat
* A string containing lexical representation of
* xsd:float.
* @return
* A float value represented by the string argument.
* @throws NumberFormatException <code>lexicalXSDFloat</code> is not a valid string representation of a <code>float</code> value.
* @throws NumberFormatException {@code lexicalXSDFloat} is not a valid string representation of a {@code float} value.
*/
public float parseFloat( String lexicalXSDFloat );
/**
* <p>
* Converts the string argument into a double value.
* @param lexicalXSDDouble
* A string containing lexical representation of
* xsd:double.
* @return
* A double value represented by the string argument.
* @throws NumberFormatException <code>lexicalXSDDouble</code> is not a valid string representation of a <code>double</code> value.
* @throws NumberFormatException {@code lexicalXSDDouble} is not a valid string representation of a {@code double} value.
*/
public double parseDouble( String lexicalXSDDouble );
/**
* <p>
* Converts the string argument into a boolean value.
* @param lexicalXSDBoolean
* A string containing lexical representation of
@ -189,20 +179,18 @@ public interface DatatypeConverterInterface {
public boolean parseBoolean( String lexicalXSDBoolean );
/**
* <p>
* Converts the string argument into a byte value.
* @param lexicalXSDByte
* A string containing lexical representation of
* xsd:byte.
* @return
* A byte value represented by the string argument.
* @throws NumberFormatException <code>lexicalXSDByte</code> does not contain a parseable byte.
* @throws NumberFormatException {@code lexicalXSDByte} does not contain a parseable byte.
* @throws IllegalArgumentException if string parameter does not conform to lexical value space defined in XML Schema Part 2: Datatypes for xsd:byte.
*/
public byte parseByte( String lexicalXSDByte );
/**
* <p>
* Converts the string argument into a QName value.
*
* <p>
@ -222,7 +210,6 @@ public interface DatatypeConverterInterface {
javax.xml.namespace.NamespaceContext nsc);
/**
* <p>
* Converts the string argument into a Calendar value.
* @param lexicalXSDDateTime
* A string containing lexical representation of
@ -234,7 +221,6 @@ public interface DatatypeConverterInterface {
public java.util.Calendar parseDateTime( String lexicalXSDDateTime );
/**
* <p>
* Converts the string argument into an array of bytes.
* @param lexicalXSDBase64Binary
* A string containing lexical representation
@ -246,7 +232,6 @@ public interface DatatypeConverterInterface {
public byte[] parseBase64Binary( String lexicalXSDBase64Binary );
/**
* <p>
* Converts the string argument into an array of bytes.
* @param lexicalXSDHexBinary
* A string containing lexical representation of
@ -258,7 +243,6 @@ public interface DatatypeConverterInterface {
public byte[] parseHexBinary( String lexicalXSDHexBinary );
/**
* <p>
* Converts the string argument into a long value.
* @param lexicalXSDUnsignedInt
* A string containing lexical representation
@ -270,7 +254,6 @@ public interface DatatypeConverterInterface {
public long parseUnsignedInt( String lexicalXSDUnsignedInt );
/**
* <p>
* Converts the string argument into an int value.
* @param lexicalXSDUnsignedShort
* A string containing lexical
@ -282,7 +265,6 @@ public interface DatatypeConverterInterface {
public int parseUnsignedShort( String lexicalXSDUnsignedShort );
/**
* <p>
* Converts the string argument into a Calendar value.
* @param lexicalXSDTime
* A string containing lexical representation of
@ -294,7 +276,6 @@ public interface DatatypeConverterInterface {
public java.util.Calendar parseTime( String lexicalXSDTime );
/**
* <p>
* Converts the string argument into a Calendar value.
* @param lexicalXSDDate
* A string containing lexical representation of
@ -306,7 +287,6 @@ public interface DatatypeConverterInterface {
public java.util.Calendar parseDate( String lexicalXSDDate );
/**
* <p>
* Return a string containing the lexical representation of the
* simple type.
* @param lexicalXSDAnySimpleType
@ -319,7 +299,6 @@ public interface DatatypeConverterInterface {
public String parseAnySimpleType( String lexicalXSDAnySimpleType );
/**
* <p>
* Converts the string argument into a string.
* @param val
* A string value.
@ -329,7 +308,6 @@ public interface DatatypeConverterInterface {
public String printString( String val );
/**
* <p>
* Converts a BigInteger value into a string.
* @param val
* A BigInteger value
@ -340,7 +318,6 @@ public interface DatatypeConverterInterface {
public String printInteger( java.math.BigInteger val );
/**
* <p>
* Converts an int value into a string.
* @param val
* An int value
@ -351,7 +328,6 @@ public interface DatatypeConverterInterface {
/**
* <p>
* Converts a long value into a string.
* @param val
* A long value
@ -361,7 +337,6 @@ public interface DatatypeConverterInterface {
public String printLong( long val );
/**
* <p>
* Converts a short value into a string.
* @param val
* A short value
@ -371,7 +346,6 @@ public interface DatatypeConverterInterface {
public String printShort( short val );
/**
* <p>
* Converts a BigDecimal value into a string.
* @param val
* A BigDecimal value
@ -382,7 +356,6 @@ public interface DatatypeConverterInterface {
public String printDecimal( java.math.BigDecimal val );
/**
* <p>
* Converts a float value into a string.
* @param val
* A float value
@ -392,7 +365,6 @@ public interface DatatypeConverterInterface {
public String printFloat( float val );
/**
* <p>
* Converts a double value into a string.
* @param val
* A double value
@ -402,7 +374,6 @@ public interface DatatypeConverterInterface {
public String printDouble( double val );
/**
* <p>
* Converts a boolean value into a string.
* @param val
* A boolean value
@ -412,7 +383,6 @@ public interface DatatypeConverterInterface {
public String printBoolean( boolean val );
/**
* <p>
* Converts a byte value into a string.
* @param val
* A byte value
@ -422,7 +392,6 @@ public interface DatatypeConverterInterface {
public String printByte( byte val );
/**
* <p>
* Converts a QName instance into a string.
* @param val
* A QName value
@ -437,7 +406,6 @@ public interface DatatypeConverterInterface {
javax.xml.namespace.NamespaceContext nsc );
/**
* <p>
* Converts a Calendar value into a string.
* @param val
* A Calendar value
@ -448,7 +416,6 @@ public interface DatatypeConverterInterface {
public String printDateTime( java.util.Calendar val );
/**
* <p>
* Converts an array of bytes into a string.
* @param val
* an array of bytes
@ -459,7 +426,6 @@ public interface DatatypeConverterInterface {
public String printBase64Binary( byte[] val );
/**
* <p>
* Converts an array of bytes into a string.
* @param val
* an array of bytes
@ -470,7 +436,6 @@ public interface DatatypeConverterInterface {
public String printHexBinary( byte[] val );
/**
* <p>
* Converts a long value into a string.
* @param val
* A long value
@ -480,7 +445,6 @@ public interface DatatypeConverterInterface {
public String printUnsignedInt( long val );
/**
* <p>
* Converts an int value into a string.
* @param val
* An int value
@ -490,7 +454,6 @@ public interface DatatypeConverterInterface {
public String printUnsignedShort( int val );
/**
* <p>
* Converts a Calendar value into a string.
* @param val
* A Calendar value
@ -501,7 +464,6 @@ public interface DatatypeConverterInterface {
public String printTime( java.util.Calendar val );
/**
* <p>
* Converts a Calendar value into a string.
* @param val
* A Calendar value
@ -512,7 +474,6 @@ public interface DatatypeConverterInterface {
public String printDate( java.util.Calendar val );
/**
* <p>
* Converts a string value into a string.
* @param val
* A string value

1
jaxws/src/java.xml.bind/share/classes/javax/xml/bind/JAXBPermission.java
View File

@ -40,7 +40,6 @@ import java.security.BasicPermission;
* The following table lists all the possible {@code JAXBPermission} target names,
* and for each provides a description of what the permission allows
* and a discussion of the risks of granting code the permission.
* <P>
*
* <table border=1 cellpadding=5 summary="Permission target name, what the permission allows, and associated risks">
* <tr>

13
jaxws/src/java.xml.bind/share/classes/javax/xml/bind/annotation/XmlElement.java
View File

@ -36,7 +36,7 @@ import static java.lang.annotation.RetentionPolicy.*;
/**
* Maps a JavaBean property to a XML element derived from property name.
*
* <p> <b>Usage</b> </p>
* <p> <b>Usage</b>
* <p>
* <tt>@XmlElement</tt> annotation can be used with the following program
* elements:
@ -44,8 +44,6 @@ import static java.lang.annotation.RetentionPolicy.*;
* <li> a JavaBean property </li>
* <li> non static, non transient field </li>
* <li> within {@link XmlElements}
* <p>
*
* </ul>
*
* The usage is subject to the following constraints:
@ -79,7 +77,7 @@ import static java.lang.annotation.RetentionPolicy.*;
* <pre>
* //Example: Code fragment
* public class USPrice {
* &#64;XmlElement(name="itemprice")
* {@literal @}XmlElement(name="itemprice")
* public java.math.BigDecimal price;
* }
* {@code
@ -95,10 +93,9 @@ import static java.lang.annotation.RetentionPolicy.*;
*
* <b> Example 2: </b> Map a field to a nillable element.
* <pre>
*
* //Example: Code fragment
* public class USPrice {
* &#64;XmlElement(nillable=true)
* {@literal @}XmlElement(nillable=true)
* public java.math.BigDecimal price;
* }
* {@code
@ -113,10 +110,9 @@ import static java.lang.annotation.RetentionPolicy.*;
* <p>
* <b> Example 3: </b> Map a field to a nillable, required element.
* <pre>
*
* //Example: Code fragment
* public class USPrice {
* &#64;XmlElement(nillable=true, required=true)
* {@literal @}XmlElement(nillable=true, required=true)
* public java.math.BigDecimal price;
* }
* {@code
@ -134,7 +130,6 @@ import static java.lang.annotation.RetentionPolicy.*;
* <p>
* See Example 6 in @{@link XmlType}.
*
* <p>
* @author Sekhar Vajjhala, Sun Microsystems, Inc.
* @since 1.6, JAXB 2.0
*/

54
jaxws/src/java.xml.bind/share/classes/javax/xml/bind/attachment/AttachmentMarshaller.java
View File

@ -29,22 +29,22 @@ import javax.activation.DataHandler;
import javax.xml.bind.Marshaller;
/**
* <p>Enable JAXB marshalling to optimize storage of binary data.</p>
* <p>Enable JAXB marshalling to optimize storage of binary data.
*
* <p>This API enables an efficient cooperative creation of optimized
* binary data formats between a JAXB marshalling process and a MIME-based package
* processor. A JAXB implementation marshals the root body of a MIME-based package,
* delegating the creation of referenceable MIME parts to
* the MIME-based package processor that implements this abstraction.</p>
* the MIME-based package processor that implements this abstraction.
*
* <p>XOP processing is enabled when {@link #isXOPPackage()} is true.
* See {@link #addMtomAttachment(DataHandler, String, String)} for details.
* </p>
*
*
* <p>WS-I Attachment Profile 1.0 is supported by
* {@link #addSwaRefAttachment(DataHandler)} being called by the
* marshaller for each JAXB property related to
* {http://ws-i.org/profiles/basic/1.1/xsd}swaRef.</p>
* {http://ws-i.org/profiles/basic/1.1/xsd}swaRef.
*
*
* @author Marc Hadley
@ -60,33 +60,33 @@ import javax.xml.bind.Marshaller;
public abstract class AttachmentMarshaller {
/**
* <p>Consider MIME content <code>data</code> for optimized binary storage as an attachment.
* <p>Consider MIME content {@code data} for optimized binary storage as an attachment.
*
* <p>
* This method is called by JAXB marshal process when {@link #isXOPPackage()} is
* <code>true</code>, for each element whose datatype is "base64Binary", as described in
* {@code true}, for each element whose datatype is "base64Binary", as described in
* Step 3 in
* <a href="http://www.w3.org/TR/2005/REC-xop10-20050125/#creating_xop_packages">Creating XOP Packages</a>.
*
* <p>
* The method implementor determines whether <code>data</code> shall be attached separately
* The method implementor determines whether {@code data} shall be attached separately
* or inlined as base64Binary data. If the implementation chooses to optimize the storage
* of the binary data as a MIME part, it is responsible for attaching <code>data</code> to the
* of the binary data as a MIME part, it is responsible for attaching {@code data} to the
* MIME-based package, and then assigning an unique content-id, cid, that identifies
* the MIME part within the MIME message. This method returns the cid,
* which enables the JAXB marshaller to marshal a XOP element that refers to that cid in place
* of marshalling the binary data. When the method returns null, the JAXB marshaller
* inlines <code>data</code> as base64binary data.
* inlines {@code data} as base64binary data.
*
* <p>
* The caller of this method is required to meet the following constraint.
* If the element infoset item containing <code>data</code> has the attribute
* <code>xmime:contentType</code> or if the JAXB property/field representing
* <code>data</code>is annotated with a known MIME type,
* <code>data.getContentType()</code> should be set to that MIME type.
* If the element infoset item containing {@code data} has the attribute
* {@code xmime:contentType} or if the JAXB property/field representing
* {@code data} is annotated with a known MIME type,
* {@code data.getContentType()} should be set to that MIME type.
*
* <p>
* The <code>elementNamespace</code> and <code>elementLocalName</code>
* The {@code elementNamespace} and {@code elementLocalName}
* parameters provide the
* context that contains the binary data. This information could
* be used by the MIME-based package processor to determine if the
@ -101,7 +101,7 @@ public abstract class AttachmentMarshaller {
* The local name of the element. Always a non-null valid string.
*
* @return
* a valid content-id URI (see <a href="http://www.w3.org/TR/xop10/#RFC2387">RFC 2387</a>) that identifies the attachment containing <code>data</code>.
* a valid content-id URI (see <a href="http://www.w3.org/TR/xop10/#RFC2387">RFC 2387</a>) that identifies the attachment containing {@code data}.
* Otherwise, null if the attachment was not added and should instead be inlined in the message.
*
* @see <a href="http://www.w3.org/TR/2005/REC-xop10-20050125/">XML-binary Optimized Packaging</a>
@ -110,12 +110,12 @@ public abstract class AttachmentMarshaller {
public abstract String addMtomAttachment(DataHandler data, String elementNamespace, String elementLocalName);
/**
* <p>Consider binary <code>data</code> for optimized binary storage as an attachment.
* <p>Consider binary {@code data} for optimized binary storage as an attachment.
*
* <p>Since content type is not known, the attachment's MIME content type must be set to "application/octet-stream".</p>
* <p>Since content type is not known, the attachment's MIME content type must be set to "application/octet-stream".
*
* <p>
* The <code>elementNamespace</code> and <code>elementLocalName</code>
* The {@code elementNamespace} and {@code elementLocalName}
* parameters provide the
* context that contains the binary data. This information could
* be used by the MIME-based package processor to determine if the
@ -146,21 +146,21 @@ public abstract class AttachmentMarshaller {
* The local name of the element. Always a non-null valid string.
*
* @return content-id URI, cid, to the attachment containing
* <code>data</code> or null if data should be inlined.
* {@code data} or null if data should be inlined.
*
* @see #addMtomAttachment(DataHandler, String, String)
*/
public abstract String addMtomAttachment(byte[] data, int offset, int length, String mimeType, String elementNamespace, String elementLocalName);
/**
* <p>Read-only property that returns true if JAXB marshaller should enable XOP creation.</p>
* <p>Read-only property that returns true if JAXB marshaller should enable XOP creation.
*
* <p>This value must not change during the marshalling process. When this
* value is true, the <code>addMtomAttachment(...)</code> method
* value is true, the {@code addMtomAttachment(...)} method
* is invoked when the appropriate binary datatypes are encountered by
* the marshal process.</p>
* the marshal process.
*
* <p>Marshaller.marshal() must throw IllegalStateException if this value is <code>true</code>
* <p>Marshaller.marshal() must throw IllegalStateException if this value is {@code true}
* and the XML content to be marshalled violates Step 1 in
* <a href="http://www.w3.org/TR/2005/REC-xop10-20050125/#creating_xop_packages">Creating XOP Pacakges</a>
* http://www.w3.org/TR/2005/REC-xop10-20050125/#creating_xop_packages.
@ -168,18 +168,18 @@ public abstract class AttachmentMarshaller {
* [namespace name] of "http://www.w3.org/2004/08/xop/include" and a [local name] of Include"</i>
*
* <p>When this method returns true and during the marshal process
* at least one call to <code>addMtomAttachment(...)</code> returns
* at least one call to {@code addMtomAttachment(...)} returns
* a content-id, the MIME-based package processor must label the
* root part with the application/xop+xml media type as described in
* Step 5 of
* <a href="http://www.w3.org/TR/2005/REC-xop10-20050125/#creating_xop_packages">Creating XOP Pacakges</a>.<p>
* <a href="http://www.w3.org/TR/2005/REC-xop10-20050125/#creating_xop_packages">Creating XOP Pacakges</a>.
*
* @return true when MIME context is a XOP Package.
*/
public boolean isXOPPackage() { return false; }
/**
* <p>Add MIME <code>data</code> as an attachment and return attachment's content-id, cid.</p>
* <p>Add MIME {@code data} as an attachment and return attachment's content-id, cid.
*
* <p>
* This method is called by JAXB marshal process for each element/attribute typed as
@ -188,7 +188,7 @@ public abstract class AttachmentMarshaller {
* MIME attachment, and generating a content-id, cid, that uniquely identifies the attachment
* within the MIME-based package.
*
* <p>Caller inserts the returned content-id, cid, into the XML content being marshalled.</p>
* <p>Caller inserts the returned content-id, cid, into the XML content being marshalled.
*
* @param data
* represents the data to be attached. Must be non-null.

2
jaxws/src/java.xml.ws/share/classes/javax/jws/soap/InitParam.java
View File

@ -27,7 +27,7 @@ package javax.jws.soap;
/**
* @since 1.6
* @Deprecated
* @deprecated
*/
@Deprecated public @interface InitParam {
String name();

2
jaxws/src/java.xml.ws/share/classes/javax/jws/soap/SOAPMessageHandler.java
View File

@ -27,7 +27,7 @@ package javax.jws.soap;
/**
* @since 1.6
* @Deprecated
* @deprecated
*/
@Deprecated public @interface SOAPMessageHandler {
String name() default "";

2
jaxws/src/java.xml.ws/share/classes/javax/jws/soap/SOAPMessageHandlers.java
View File

@ -29,7 +29,7 @@ import static java.lang.annotation.ElementType.*;
/**
* @since 1.6
* @Deprecated
* @deprecated
*/
@Retention(value=RetentionPolicy.RUNTIME)
@Target({TYPE})

251
jaxws/src/java.xml.ws/share/classes/javax/xml/soap/AttachmentPart.java
View File

@ -32,54 +32,53 @@ import java.util.Iterator;
import javax.activation.DataHandler;
/**
* A single attachment to a <code>SOAPMessage</code> object. A <code>SOAPMessage</code>
* object may contain zero, one, or many <code>AttachmentPart</code> objects.
* Each <code>AttachmentPart</code> object consists of two parts,
* A single attachment to a {@code SOAPMessage} object. A {@code SOAPMessage}
* object may contain zero, one, or many {@code AttachmentPart} objects.
* Each {@code AttachmentPart} object consists of two parts,
* application-specific content and associated MIME headers. The
* MIME headers consists of name/value pairs that can be used to
* identify and describe the content.
* <p>
* An <code>AttachmentPart</code> object must conform to certain standards.
* An {@code AttachmentPart} object must conform to certain standards.
* <OL>
* <LI>It must conform to <a href="http://www.ietf.org/rfc/rfc2045.txt">
* MIME [RFC2045] standards</a>
* <LI>It MUST contain content
* <LI>The header portion MUST include the following header:
* <UL>
* <LI><code>Content-Type</code><br>
* <LI>{@code Content-Type}<br>
* This header identifies the type of data in the content of an
* <code>AttachmentPart</code> object and MUST conform to [RFC2045].
* {@code AttachmentPart} object and MUST conform to [RFC2045].
* The following is an example of a Content-Type header:
* <PRE>
* Content-Type: application/xml
* </PRE>
* The following line of code, in which <code>ap</code> is an
* <code>AttachmentPart</code> object, sets the header shown in
* The following line of code, in which {@code ap} is an
* {@code AttachmentPart} object, sets the header shown in
* the previous example.
* <PRE>
* ap.setMimeHeader("Content-Type", "application/xml");
* </PRE>
* <p>
* </UL>
* </OL>
* <p>
* There are no restrictions on the content portion of an <code>
* AttachmentPart</code> object. The content may be anything from a
* There are no restrictions on the content portion of an {@code
* AttachmentPart} object. The content may be anything from a
* simple plain text object to a complex XML document or image file.
*
* <p>
* An <code>AttachmentPart</code> object is created with the method
* <code>SOAPMessage.createAttachmentPart</code>. After setting its MIME headers,
* the <code>AttachmentPart</code> object is added to the message
* that created it with the method <code>SOAPMessage.addAttachmentPart</code>.
* An {@code AttachmentPart} object is created with the method
* {@code SOAPMessage.createAttachmentPart}. After setting its MIME headers,
* the {@code AttachmentPart} object is added to the message
* that created it with the method {@code SOAPMessage.addAttachmentPart}.
*
* <p>
* The following code fragment, in which <code>m</code> is a
* <code>SOAPMessage</code> object and <code>contentStringl</code> is a
* <code>String</code>, creates an instance of <code>AttachmentPart</code>,
* sets the <code>AttachmentPart</code> object with some content and
* header information, and adds the <code>AttachmentPart</code> object to
* the <code>SOAPMessage</code> object.
* The following code fragment, in which {@code m} is a
* {@code SOAPMessage} object and {@code contentStringl} is a
* {@code String}, creates an instance of {@code AttachmentPart},
* sets the {@code AttachmentPart} object with some content and
* header information, and adds the {@code AttachmentPart} object to
* the {@code SOAPMessage} object.
* <PRE>
* AttachmentPart ap1 = m.createAttachmentPart();
* ap1.setContent(contentString1, "text/plain");
@ -89,7 +88,7 @@ import javax.activation.DataHandler;
*
* <p>
* The following code fragment creates and adds a second
* <code>AttachmentPart</code> instance to the same message. <code>jpegData</code>
* {@code AttachmentPart} instance to the same message. {@code jpegData}
* is a binary byte buffer representing the jpeg file.
* <PRE>
* AttachmentPart ap2 = m.createAttachmentPart();
@ -98,19 +97,19 @@ import javax.activation.DataHandler;
* m.addAttachmentPart(ap2);
* </PRE>
* <p>
* The <code>getContent</code> method retrieves the contents and header from
* an <code>AttachmentPart</code> object. Depending on the
* <code>DataContentHandler</code> objects present, the returned
* <code>Object</code> can either be a typed Java object corresponding
* to the MIME type or an <code>InputStream</code> object that contains the
* The {@code getContent} method retrieves the contents and header from
* an {@code AttachmentPart} object. Depending on the
* {@code DataContentHandler} objects present, the returned
* {@code Object} can either be a typed Java object corresponding
* to the MIME type or an {@code InputStream} object that contains the
* content as bytes.
* <PRE>
* String content1 = ap1.getContent();
* java.io.InputStream content2 = ap2.getContent();
* </PRE>
*
* The method <code>clearContent</code> removes all the content from an
* <code>AttachmentPart</code> object but does not affect its header information.
* The method {@code clearContent} removes all the content from an
* {@code AttachmentPart} object but does not affect its header information.
* <PRE>
* ap1.clearContent();
* </PRE>
@ -120,10 +119,10 @@ import javax.activation.DataHandler;
public abstract class AttachmentPart {
/**
* Returns the number of bytes in this <code>AttachmentPart</code>
* Returns the number of bytes in this {@code AttachmentPart}
* object.
*
* @return the size of this <code>AttachmentPart</code> object in bytes
* @return the size of this {@code AttachmentPart} object in bytes
* or -1 if the size cannot be determined
* @exception SOAPException if the content of this attachment is
* corrupted of if there was an exception while trying
@ -132,52 +131,52 @@ public abstract class AttachmentPart {
public abstract int getSize() throws SOAPException;
/**
* Clears out the content of this <code>AttachmentPart</code> object.
* Clears out the content of this {@code AttachmentPart} object.
* The MIME header portion is left untouched.
*/
public abstract void clearContent();
/**
* Gets the content of this <code>AttachmentPart</code> object as a Java
* Gets the content of this {@code AttachmentPart} object as a Java
* object. The type of the returned Java object depends on (1) the
* <code>DataContentHandler</code> object that is used to interpret the bytes
* and (2) the <code>Content-Type</code> given in the header.
* {@code DataContentHandler} object that is used to interpret the bytes
* and (2) the {@code Content-Type} given in the header.
* <p>
* For the MIME content types "text/plain", "text/html" and "text/xml", the
* <code>DataContentHandler</code> object does the conversions to and
* {@code DataContentHandler} object does the conversions to and
* from the Java types corresponding to the MIME types.
* For other MIME types,the <code>DataContentHandler</code> object
* can return an <code>InputStream</code> object that contains the content data
* For other MIME types,the {@code DataContentHandler} object
* can return an {@code InputStream} object that contains the content data
* as raw bytes.
* <p>
* A SAAJ-compliant implementation must, as a minimum, return a
* <code>java.lang.String</code> object corresponding to any content
* stream with a <code>Content-Type</code> value of
* <code>text/plain</code>, a
* <code>javax.xml.transform.stream.StreamSource</code> object corresponding to a
* content stream with a <code>Content-Type</code> value of
* <code>text/xml</code>, a <code>java.awt.Image</code> object
* {@code java.lang.String} object corresponding to any content
* stream with a {@code Content-Type} value of
* {@code text/plain}, a
* {@code javax.xml.transform.stream.StreamSource} object corresponding to a
* content stream with a {@code Content-Type} value of
* {@code text/xml}, a {@code java.awt.Image} object
* corresponding to a content stream with a
* <code>Content-Type</code> value of <code>image/gif</code> or
* <code>image/jpeg</code>. For those content types that an
* installed <code>DataContentHandler</code> object does not understand, the
* <code>DataContentHandler</code> object is required to return a
* <code>java.io.InputStream</code> object with the raw bytes.
* {@code Content-Type} value of {@code image/gif} or
* {@code image/jpeg}. For those content types that an
* installed {@code DataContentHandler} object does not understand, the
* {@code DataContentHandler} object is required to return a
* {@code java.io.InputStream} object with the raw bytes.
*
* @return a Java object with the content of this <code>AttachmentPart</code>
* @return a Java object with the content of this {@code AttachmentPart}
* object
*
* @exception SOAPException if there is no content set into this
* <code>AttachmentPart</code> object or if there was a data
* {@code AttachmentPart} object or if there was a data
* transformation error
*/
public abstract Object getContent() throws SOAPException;
/**
* Gets the content of this <code>AttachmentPart</code> object as an
* InputStream as if a call had been made to <code>getContent</code> and no
* <code>DataContentHandler</code> had been registered for the
* <code>content-type</code> of this <code>AttachmentPart</code>.
* Gets the content of this {@code AttachmentPart} object as an
* InputStream as if a call had been made to {@code getContent} and no
* {@code DataContentHandler} had been registered for the
* {@code content-type} of this {@code AttachmentPart}.
*<p>
* Note that reading from the returned InputStream would result in consuming
* the data in the stream. It is the responsibility of the caller to reset
@ -185,11 +184,11 @@ public abstract class AttachmentPart {
* of the raw attachment content is required then the {@link #getRawContentBytes} API
* should be used instead.
*
* @return an <code>InputStream</code> from which the raw data contained by
* the <code>AttachmentPart</code> can be accessed.
* @return an {@code InputStream} from which the raw data contained by
* the {@code AttachmentPart} can be accessed.
*
* @throws SOAPException if there is no content set into this
* <code>AttachmentPart</code> object or if there was a data
* {@code AttachmentPart} object or if there was a data
* transformation error.
*
* @since 1.6, SAAJ 1.3
@ -198,16 +197,16 @@ public abstract class AttachmentPart {
public abstract InputStream getRawContent() throws SOAPException;
/**
* Gets the content of this <code>AttachmentPart</code> object as a
* byte[] array as if a call had been made to <code>getContent</code> and no
* <code>DataContentHandler</code> had been registered for the
* <code>content-type</code> of this <code>AttachmentPart</code>.
* Gets the content of this {@code AttachmentPart} object as a
* byte[] array as if a call had been made to {@code getContent} and no
* {@code DataContentHandler} had been registered for the
* {@code content-type} of this {@code AttachmentPart}.
*
* @return a <code>byte[]</code> array containing the raw data of the
* <code>AttachmentPart</code>.
* @return a {@code byte[]} array containing the raw data of the
* {@code AttachmentPart}.
*
* @throws SOAPException if there is no content set into this
* <code>AttachmentPart</code> object or if there was a data
* {@code AttachmentPart} object or if there was a data
* transformation error.
*
* @since 1.6, SAAJ 1.3
@ -215,16 +214,16 @@ public abstract class AttachmentPart {
public abstract byte[] getRawContentBytes() throws SOAPException;
/**
* Returns an <code>InputStream</code> which can be used to obtain the
* content of <code>AttachmentPart</code> as Base64 encoded
* Returns an {@code InputStream} which can be used to obtain the
* content of {@code AttachmentPart} as Base64 encoded
* character data, this method would base64 encode the raw bytes
* of the attachment and return.
*
* @return an <code>InputStream</code> from which the Base64 encoded
* <code>AttachmentPart</code> can be read.
* @return an {@code InputStream} from which the Base64 encoded
* {@code AttachmentPart} can be read.
*
* @throws SOAPException if there is no content set into this
* <code>AttachmentPart</code> object or if there was a data
* {@code AttachmentPart} object or if there was a data
* transformation error.
*
* @since 1.6, SAAJ 1.3
@ -233,11 +232,11 @@ public abstract class AttachmentPart {
/**
* Sets the content of this attachment part to that of the given
* <code>Object</code> and sets the value of the <code>Content-Type</code>
* {@code Object} and sets the value of the {@code Content-Type}
* header to the given type. The type of the
* <code>Object</code> should correspond to the value given for the
* <code>Content-Type</code>. This depends on the particular
* set of <code>DataContentHandler</code> objects in use.
* {@code Object} should correspond to the value given for the
* {@code Content-Type}. This depends on the particular
* set of {@code DataContentHandler} objects in use.
*
*
* @param object the Java object that makes up the content for
@ -247,7 +246,7 @@ public abstract class AttachmentPart {
*
* @exception IllegalArgumentException may be thrown if the contentType
* does not match the type of the content object, or if there
* was no <code>DataContentHandler</code> object for this
* was no {@code DataContentHandler} object for this
* content object
*
* @see #getContent
@ -256,31 +255,31 @@ public abstract class AttachmentPart {
/**
* Sets the content of this attachment part to that contained by the
* <code>InputStream</code> <code>content</code> and sets the value of the
* <code>Content-Type</code> header to the value contained in
* <code>contentType</code>.
* {@code InputStream} {@code content} and sets the value of the
* {@code Content-Type} header to the value contained in
* {@code contentType}.
* <P>
* A subsequent call to getSize() may not be an exact measure
* of the content size.
*
* @param content the raw data to add to the attachment part
* @param contentType the value to set into the <code>Content-Type</code>
* @param contentType the value to set into the {@code Content-Type}
* header
*
* @exception SOAPException if an there is an error in setting the content
* @exception NullPointerException if <code>content</code> is null
* @exception NullPointerException if {@code content} is null
* @since 1.6, SAAJ 1.3
*/
public abstract void setRawContent(InputStream content, String contentType) throws SOAPException;
/**
* Sets the content of this attachment part to that contained by the
* <code>byte[]</code> array <code>content</code> and sets the value of the
* <code>Content-Type</code> header to the value contained in
* <code>contentType</code>.
* {@code byte[]} array {@code content} and sets the value of the
* {@code Content-Type} header to the value contained in
* {@code contentType}.
*
* @param content the raw data to add to the attachment part
* @param contentType the value to set into the <code>Content-Type</code>
* @param contentType the value to set into the {@code Content-Type}
* header
* @param offset the offset in the byte array of the content
* @param len the number of bytes that form the content
@ -296,20 +295,20 @@ public abstract class AttachmentPart {
/**
* Sets the content of this attachment part from the Base64 source
* <code>InputStream</code> and sets the value of the
* <code>Content-Type</code> header to the value contained in
* <code>contentType</code>, This method would first decode the base64
* {@code InputStream} and sets the value of the
* {@code Content-Type} header to the value contained in
* {@code contentType}, This method would first decode the base64
* input and write the resulting raw bytes to the attachment.
* <P>
* A subsequent call to getSize() may not be an exact measure
* of the content size.
*
* @param content the base64 encoded data to add to the attachment part
* @param contentType the value to set into the <code>Content-Type</code>
* @param contentType the value to set into the {@code Content-Type}
* header
*
* @exception SOAPException if an there is an error in setting the content
* @exception NullPointerException if <code>content</code> is null
* @exception NullPointerException if {@code content} is null
*
* @since 1.6, SAAJ 1.3
*/
@ -318,30 +317,30 @@ public abstract class AttachmentPart {
/**
* Gets the <code>DataHandler</code> object for this <code>AttachmentPart</code>
* Gets the {@code DataHandler} object for this {@code AttachmentPart}
* object.
*
* @return the <code>DataHandler</code> object associated with this
* <code>AttachmentPart</code> object
* @return the {@code DataHandler} object associated with this
* {@code AttachmentPart} object
*
* @exception SOAPException if there is no data in
* this <code>AttachmentPart</code> object
* this {@code AttachmentPart} object
*/
public abstract DataHandler getDataHandler()
throws SOAPException;
/**
* Sets the given <code>DataHandler</code> object as the data handler
* for this <code>AttachmentPart</code> object. Typically, on an incoming
* Sets the given {@code DataHandler} object as the data handler
* for this {@code AttachmentPart} object. Typically, on an incoming
* message, the data handler is automatically set. When
* a message is being created and populated with content, the
* <code>setDataHandler</code> method can be used to get data from
* {@code setDataHandler} method can be used to get data from
* various data sources into the message.
*
* @param dataHandler the <code>DataHandler</code> object to be set
* @param dataHandler the {@code DataHandler} object to be set
*
* @exception IllegalArgumentException if there was a problem with
* the specified <code>DataHandler</code> object
* the specified {@code DataHandler} object
*/
public abstract void setDataHandler(DataHandler dataHandler);
@ -349,8 +348,8 @@ public abstract class AttachmentPart {
/**
* Gets the value of the MIME header whose name is "Content-ID".
*
* @return a <code>String</code> giving the value of the
* "Content-ID" header or <code>null</code> if there
* @return a {@code String} giving the value of the
* "Content-ID" header or {@code null} if there
* is none
* @see #setContentId
*/
@ -364,8 +363,8 @@ public abstract class AttachmentPart {
/**
* Gets the value of the MIME header whose name is "Content-Location".
*
* @return a <code>String</code> giving the value of the
* "Content-Location" header or <code>null</code> if there
* @return a {@code String} giving the value of the
* "Content-Location" header or {@code null} if there
* is none
*/
public String getContentLocation() {
@ -378,8 +377,8 @@ public abstract class AttachmentPart {
/**
* Gets the value of the MIME header whose name is "Content-Type".
*
* @return a <code>String</code> giving the value of the
* "Content-Type" header or <code>null</code> if there
* @return a {@code String} giving the value of the
* "Content-Type" header or {@code null} if there
* is none
*/
public String getContentType() {
@ -392,11 +391,11 @@ public abstract class AttachmentPart {
/**
* Sets the MIME header whose name is "Content-ID" with the given value.
*
* @param contentId a <code>String</code> giving the value of the
* @param contentId a {@code String} giving the value of the
* "Content-ID" header
*
* @exception IllegalArgumentException if there was a problem with
* the specified <code>contentId</code> value
* the specified {@code contentId} value
* @see #getContentId
*/
public void setContentId(String contentId)
@ -409,7 +408,7 @@ public abstract class AttachmentPart {
* Sets the MIME header whose name is "Content-Location" with the given value.
*
*
* @param contentLocation a <code>String</code> giving the value of the
* @param contentLocation a {@code String} giving the value of the
* "Content-Location" header
* @exception IllegalArgumentException if there was a problem with
* the specified content location
@ -422,7 +421,7 @@ public abstract class AttachmentPart {
/**
* Sets the MIME header whose name is "Content-Type" with the given value.
*
* @param contentType a <code>String</code> giving the value of the
* @param contentType a {@code String} giving the value of the
* "Content-Type" header
*
* @exception IllegalArgumentException if there was a problem with
@ -449,10 +448,10 @@ public abstract class AttachmentPart {
/**
* Gets all the values of the header identified by the given
* <code>String</code>.
* {@code String}.
*
* @param name the name of the header; example: "Content-Type"
* @return a <code>String</code> array giving the value for the
* @return a {@code String} array giving the value for the
* specified header
* @see #setMimeHeader
*/
@ -466,9 +465,9 @@ public abstract class AttachmentPart {
*
* Note that RFC822 headers can only contain US-ASCII characters.
*
* @param name a <code>String</code> giving the name of the header
* @param name a {@code String} giving the name of the header
* for which to search
* @param value a <code>String</code> giving the value to be set for
* @param value a {@code String} giving the value to be set for
* the header whose name matches the given name
*
* @exception IllegalArgumentException if there was a problem with
@ -479,13 +478,13 @@ public abstract class AttachmentPart {
/**
* Adds a MIME header with the specified name and value to this
* <code>AttachmentPart</code> object.
* {@code AttachmentPart} object.
* <p>
* Note that RFC822 headers can contain only US-ASCII characters.
*
* @param name a <code>String</code> giving the name of the header
* @param name a {@code String} giving the name of the header
* to be added
* @param value a <code>String</code> giving the value of the header
* @param value a {@code String} giving the value of the header
* to be added
*
* @exception IllegalArgumentException if there was a problem with
@ -494,35 +493,35 @@ public abstract class AttachmentPart {
public abstract void addMimeHeader(String name, String value);
/**
* Retrieves all the headers for this <code>AttachmentPart</code> object
* as an iterator over the <code>MimeHeader</code> objects.
* Retrieves all the headers for this {@code AttachmentPart} object
* as an iterator over the {@code MimeHeader} objects.
*
* @return an <code>Iterator</code> object with all of the Mime
* headers for this <code>AttachmentPart</code> object
* @return an {@code Iterator} object with all of the Mime
* headers for this {@code AttachmentPart} object
*/
public abstract Iterator getAllMimeHeaders();
/**
* Retrieves all <code>MimeHeader</code> objects that match a name in
* Retrieves all {@code MimeHeader} objects that match a name in
* the given array.
*
* @param names a <code>String</code> array with the name(s) of the
* @param names a {@code String} 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 as an <code>Iterator</code> object
* given array as an {@code Iterator} object
*/
public abstract Iterator getMatchingMimeHeaders(String[] names);
/**
* Retrieves all <code>MimeHeader</code> objects whose name does
* Retrieves all {@code MimeHeader} 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
* @param names a {@code String} array with the name(s) of the
* MIME headers not to be returned
* @return all of the MIME headers in this <code>AttachmentPart</code> object
* @return all of the MIME headers in this {@code AttachmentPart} 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.
* {@code Iterator} object.
*/
public abstract Iterator getNonMatchingMimeHeaders(String[] names);
}

46
jaxws/src/java.xml.ws/share/classes/javax/xml/soap/Name.java
View File

@ -32,52 +32,50 @@ package javax.xml.soap;
* to get the URI of the namespace.
* <P>
* The following is an example of a namespace declaration in an element.
* <PRE>
* &lt;wombat:GetLastTradePrice xmlns:wombat="http://www.wombat.org/trader"&gt;
* </PRE>
* {@code <wombat:GetLastTradePrice xmlns:wombat="http://www.wombat.org/trader">}
* ("xmlns" stands for "XML namespace".)
* The following
* shows what the methods in the <code>Name</code> interface will return.
* shows what the methods in the {@code Name} interface will return.
* <UL>
* <LI><code>getQualifiedName</code> will return "prefix:LocalName" =
* <LI>{@code getQualifiedName} will return "prefix:LocalName" =
* "WOMBAT:GetLastTradePrice"
* <LI><code>getURI</code> will return "http://www.wombat.org/trader"
* <LI><code>getLocalName</code> will return "GetLastTracePrice"
* <LI><code>getPrefix</code> will return "WOMBAT"
* <LI>{@code getURI} will return "http://www.wombat.org/trader"
* <LI>{@code getLocalName} will return "GetLastTracePrice"
* <LI>{@code getPrefix} will return "WOMBAT"
* </UL>
* <P>
* XML namespaces are used to disambiguate SOAP identifiers from
* application-specific identifiers.
* <P>
* <code>Name</code> objects are created using the method
* <code>SOAPEnvelope.createName</code>, which has two versions.
* One method creates <code>Name</code> objects with
* {@code Name} objects are created using the method
* {@code SOAPEnvelope.createName}, which has two versions.
* One method creates {@code Name} objects with
* a local name, a namespace prefix, and a namespace URI.
* and the second creates <code>Name</code> objects with just a local name.
* and the second creates {@code Name} objects with just a local name.
* The following line of
* code, in which <i>se</i> is a <code>SOAPEnvelope</code> object, creates a new
* <code>Name</code> object with all three.
* code, in which <i>se</i> is a {@code SOAPEnvelope} object, creates a new
* {@code Name} object with all three.
* <PRE>
* Name name = se.createName("GetLastTradePrice", "WOMBAT",
* "http://www.wombat.org/trader");
* </PRE>
* The following line of code gives an example of how a <code>Name</code> object
* can be used. The variable <i>element</i> is a <code>SOAPElement</code> object.
* This code creates a new <code>SOAPElement</code> object with the given name and
* The following line of code gives an example of how a {@code Name} object
* can be used. The variable <i>element</i> is a {@code SOAPElement} object.
* This code creates a new {@code SOAPElement} object with the given name and
* adds it to <i>element</i>.
* <PRE>
* element.addChildElement(name);
* </PRE>
* <P>
* The <code>Name</code> interface may be deprecated in a future release of SAAJ
* in favor of <code>javax.xml.namespace.QName<code>
* The {@code Name} interface may be deprecated in a future release of SAAJ
* in favor of {@code javax.xml.namespace.QName}
* @see SOAPEnvelope#createName(String, String, String) SOAPEnvelope.createName
* @see SOAPFactory#createName(String, String, String) SOAPFactory.createName
* @since 1.6
*/
public interface Name {
/**
* Gets the local name part of the XML name that this <code>Name</code>
* Gets the local name part of the XML name that this {@code Name}
* object represents.
*
* @return a string giving the local name
@ -86,16 +84,16 @@ public interface Name {
/**
* Gets the namespace-qualified name of the XML name that this
* <code>Name</code> object represents.
* {@code Name} object represents.
*
* @return the namespace-qualified name as a string
*/
String getQualifiedName();
/**
* Returns the prefix that was specified when this <code>Name</code> object
* Returns the prefix that was specified when this {@code Name} object
* was initialized. This prefix is associated with the namespace for the XML
* name that this <code>Name</code> object represents.
* name that this {@code Name} object represents.
*
* @return the prefix as a string
*/
@ -103,7 +101,7 @@ public interface Name {
/**
* Returns the URI of the namespace for the XML
* name that this <code>Name</code> object represents.
* name that this {@code Name} object represents.
*
* @return the URI as a string
*/

186
jaxws/src/java.xml.ws/share/classes/javax/xml/soap/SOAPBody.java
View File

@ -36,10 +36,10 @@ import javax.xml.namespace.QName;
* element in a SOAP message. A SOAP body element consists of XML data
* that affects the way the application-specific content is processed.
* <P>
* A <code>SOAPBody</code> object contains <code>SOAPBodyElement</code>
* A {@code SOAPBody} object contains {@code SOAPBodyElement}
* objects, which have the content for the SOAP body.
* A <code>SOAPFault</code> object, which carries status and/or
* error information, is an example of a <code>SOAPBodyElement</code> object.
* A {@code SOAPFault} object, which carries status and/or
* error information, is an example of a {@code SOAPBodyElement} object.
*
* @see SOAPFault
* @since 1.6
@ -47,47 +47,47 @@ import javax.xml.namespace.QName;
public interface SOAPBody extends SOAPElement {
/**
* Creates a new <code>SOAPFault</code> object and adds it to
* this <code>SOAPBody</code> object. The new <code>SOAPFault</code> will
* Creates a new {@code SOAPFault} object and adds it to
* this {@code SOAPBody} object. The new {@code SOAPFault} will
* have default values set for the mandatory child elements. The type of
* the <code>SOAPFault</code> will be a SOAP 1.1 or a SOAP 1.2 <code>SOAPFault</code>
* depending on the <code>protocol</code> specified while creating the
* <code>MessageFactory</code> instance.
* the {@code SOAPFault} will be a SOAP 1.1 or a SOAP 1.2 {@code SOAPFault}
* depending on the {@code protocol} specified while creating the
* {@code MessageFactory} instance.
* <p>
* A <code>SOAPBody</code> may contain at most one <code>SOAPFault</code>
* A {@code SOAPBody} may contain at most one {@code SOAPFault}
* child element.
*
* @return the new <code>SOAPFault</code> object
* @return the new {@code SOAPFault} object
* @exception SOAPException if there is a SOAP error
*/
public SOAPFault addFault() throws SOAPException;
/**
* Creates a new <code>SOAPFault</code> object and adds it to
* this <code>SOAPBody</code> object. The type of the
* <code>SOAPFault</code> will be a SOAP 1.1 or a SOAP 1.2
* <code>SOAPFault</code> depending on the <code>protocol</code>
* specified while creating the <code>MessageFactory</code> instance.
* Creates a new {@code SOAPFault} object and adds it to
* this {@code SOAPBody} object. The type of the
* {@code SOAPFault} will be a SOAP 1.1 or a SOAP 1.2
* {@code SOAPFault} depending on the {@code protocol}
* specified while creating the {@code MessageFactory} instance.
* <p>
* For SOAP 1.2 the <code>faultCode</code> parameter is the value of the
* <i>Fault/Code/Value</i> element and the <code>faultString</code> parameter
* For SOAP 1.2 the {@code faultCode} parameter is the value of the
* <i>Fault/Code/Value</i> element and the {@code faultString} parameter
* is the value of the <i>Fault/Reason/Text</i> element. For SOAP 1.1
* the <code>faultCode</code> parameter is the value of the <code>faultcode</code>
* element and the <code>faultString</code> parameter is the value of the <code>faultstring</code>
* the {@code faultCode} parameter is the value of the {@code faultcode}
* element and the {@code faultString} parameter is the value of the {@code faultstring}
* element.
* <p>
* A <code>SOAPBody</code> may contain at most one <code>SOAPFault</code>
* A {@code SOAPBody} may contain at most one {@code SOAPFault}
* child element.
*
* @param faultCode a <code>Name</code> object giving the fault
* @param faultCode a {@code Name} object giving the fault
* code to be set; must be one of the fault codes defined in the Version
* of SOAP specification in use
* @param faultString a <code>String</code> giving an explanation of
* @param faultString a {@code String} giving an explanation of
* the fault
* @param locale a {@link java.util.Locale} object indicating
* the native language of the <code>faultString</code>
* @return the new <code>SOAPFault</code> object
* the native language of the {@code faultString}
* @return the new {@code SOAPFault} object
* @exception SOAPException if there is a SOAP error
* @see SOAPFault#setFaultCode
* @see SOAPFault#setFaultString
@ -96,32 +96,32 @@ public interface SOAPBody extends SOAPElement {
public SOAPFault addFault(Name faultCode, String faultString, Locale locale) throws SOAPException;
/**
* Creates a new <code>SOAPFault</code> object and adds it to this
* <code>SOAPBody</code> object. The type of the <code>SOAPFault</code>
* will be a SOAP 1.1 or a SOAP 1.2 <code>SOAPFault</code> depending on
* the <code>protocol</code> specified while creating the <code>MessageFactory</code>
* Creates a new {@code SOAPFault} object and adds it to this
* {@code SOAPBody} object. The type of the {@code SOAPFault}
* will be a SOAP 1.1 or a SOAP 1.2 {@code SOAPFault} depending on
* the {@code protocol} specified while creating the {@code MessageFactory}
* instance.
* <p>
* For SOAP 1.2 the <code>faultCode</code> parameter is the value of the
* <i>Fault/Code/Value</i> element and the <code>faultString</code> parameter
* For SOAP 1.2 the {@code faultCode} parameter is the value of the
* <i>Fault/Code/Value</i> element and the {@code faultString} parameter
* is the value of the <i>Fault/Reason/Text</i> element. For SOAP 1.1
* the <code>faultCode</code> parameter is the value of the <code>faultcode</code>
* element and the <code>faultString</code> parameter is the value of the <code>faultstring</code>
* the {@code faultCode} parameter is the value of the {@code faultcode}
* element and the {@code faultString} parameter is the value of the {@code faultstring}
* element.
* <p>
* A <code>SOAPBody</code> may contain at most one <code>SOAPFault</code>
* A {@code SOAPBody} may contain at most one {@code SOAPFault}
* child element.
*
* @param faultCode
* a <code>QName</code> object giving the fault code to be
* a {@code QName} object giving the fault code to be
* set; must be one of the fault codes defined in the version
* of SOAP specification in use.
* @param faultString
* a <code>String</code> giving an explanation of the fault
* a {@code String} giving an explanation of the fault
* @param locale
* a {@link java.util.Locale Locale} object indicating the
* native language of the <code>faultString</code>
* @return the new <code>SOAPFault</code> object
* native language of the {@code faultString}
* @return the new {@code SOAPFault} object
* @exception SOAPException
* if there is a SOAP error
* @see SOAPFault#setFaultCode
@ -134,33 +134,33 @@ public interface SOAPBody extends SOAPElement {
throws SOAPException;
/**
* Creates a new <code>SOAPFault</code> object and adds it to this
* <code>SOAPBody</code> object. The type of the <code>SOAPFault</code>
* will be a SOAP 1.1 or a SOAP 1.2 <code>SOAPFault</code> depending on
* the <code>protocol</code> specified while creating the <code>MessageFactory</code>
* Creates a new {@code SOAPFault} object and adds it to this
* {@code SOAPBody} object. The type of the {@code SOAPFault}
* will be a SOAP 1.1 or a SOAP 1.2 {@code SOAPFault} depending on
* the {@code protocol} specified while creating the {@code MessageFactory}
* instance.
* <p>
* For SOAP 1.2 the <code>faultCode</code> parameter is the value of the
* <i>Fault/Code/Value</i> element and the <code>faultString</code> parameter
* For SOAP 1.2 the {@code faultCode} parameter is the value of the
* <i>Fault/Code/Value</i> element and the {@code faultString} parameter
* is the value of the <i>Fault/Reason/Text</i> element. For SOAP 1.1
* the <code>faultCode</code> parameter is the value of the <i>faultcode</i>
* element and the <code>faultString</code> parameter is the value of the <i>faultstring</i>
* the {@code faultCode} parameter is the value of the <i>faultcode</i>
* element and the {@code faultString} parameter is the value of the <i>faultstring</i>
* element.
* <p>
* In case of a SOAP 1.2 fault, the default value for the mandatory <code>xml:lang</code>
* In case of a SOAP 1.2 fault, the default value for the mandatory {@code xml:lang}
* attribute on the <i>Fault/Reason/Text</i> element will be set to
* <code>java.util.Locale.getDefault()</code>
* {@code java.util.Locale.getDefault()}
* <p>
* A <code>SOAPBody</code> may contain at most one <code>SOAPFault</code>
* A {@code SOAPBody} may contain at most one {@code SOAPFault}
* child element.
*
* @param faultCode
* a <code>Name</code> object giving the fault code to be set;
* a {@code Name} object giving the fault code to be set;
* must be one of the fault codes defined in the version of SOAP
* specification in use
* @param faultString
* a <code>String</code> giving an explanation of the fault
* @return the new <code>SOAPFault</code> object
* a {@code String} giving an explanation of the fault
* @return the new {@code SOAPFault} object
* @exception SOAPException
* if there is a SOAP error
* @see SOAPFault#setFaultCode
@ -171,33 +171,33 @@ public interface SOAPBody extends SOAPElement {
throws SOAPException;
/**
* Creates a new <code>SOAPFault</code> object and adds it to this <code>SOAPBody</code>
* object. The type of the <code>SOAPFault</code>
* will be a SOAP 1.1 or a SOAP 1.2 <code>SOAPFault</code> depending on
* the <code>protocol</code> specified while creating the <code>MessageFactory</code>
* Creates a new {@code SOAPFault} object and adds it to this {@code SOAPBody}
* object. The type of the {@code SOAPFault}
* will be a SOAP 1.1 or a SOAP 1.2 {@code SOAPFault} depending on
* the {@code protocol} specified while creating the {@code MessageFactory}
* instance.
* <p>
* For SOAP 1.2 the <code>faultCode</code> parameter is the value of the
* <i>Fault/Code/Value</i> element and the <code>faultString</code> parameter
* For SOAP 1.2 the {@code faultCode} parameter is the value of the
* <i>Fault/Code/Value</i> element and the {@code faultString} parameter
* is the value of the <i>Fault/Reason/Text</i> element. For SOAP 1.1
* the <code>faultCode</code> parameter is the value of the <i>faultcode</i>
* element and the <code>faultString</code> parameter is the value of the <i>faultstring</i>
* the {@code faultCode} parameter is the value of the <i>faultcode</i>
* element and the {@code faultString} parameter is the value of the <i>faultstring</i>
* element.
* <p>
* In case of a SOAP 1.2 fault, the default value for the mandatory <code>xml:lang</code>
* In case of a SOAP 1.2 fault, the default value for the mandatory {@code xml:lang}
* attribute on the <i>Fault/Reason/Text</i> element will be set to
* <code>java.util.Locale.getDefault()</code>
* {@code java.util.Locale.getDefault()}
* <p>
* A <code>SOAPBody</code> may contain at most one <code>SOAPFault</code>
* A {@code SOAPBody} may contain at most one {@code SOAPFault}
* child element
*
* @param faultCode
* a <code>QName</code> object giving the fault code to be
* a {@code QName} object giving the fault code to be
* set; must be one of the fault codes defined in the version
* of SOAP specification in use
* @param faultString
* a <code>String</code> giving an explanation of the fault
* @return the new <code>SOAPFault</code> object
* a {@code String} giving an explanation of the fault
* @return the new {@code SOAPFault} object
* @exception SOAPException
* if there is a SOAP error
* @see SOAPFault#setFaultCode
@ -209,32 +209,32 @@ public interface SOAPBody extends SOAPElement {
throws SOAPException;
/**
* Indicates whether a <code>SOAPFault</code> object exists in this
* <code>SOAPBody</code> object.
* Indicates whether a {@code SOAPFault} object exists in this
* {@code SOAPBody} object.
*
* @return <code>true</code> if a <code>SOAPFault</code> object exists
* in this <code>SOAPBody</code> object; <code>false</code>
* @return {@code true} if a {@code SOAPFault} object exists
* in this {@code SOAPBody} object; {@code false}
* otherwise
*/
public boolean hasFault();
/**
* Returns the <code>SOAPFault</code> object in this <code>SOAPBody</code>
* Returns the {@code SOAPFault} object in this {@code SOAPBody}
* object.
*
* @return the <code>SOAPFault</code> object in this <code>SOAPBody</code>
* @return the {@code SOAPFault} object in this {@code SOAPBody}
* object if present, null otherwise.
*/
public SOAPFault getFault();
/**
* Creates a new <code>SOAPBodyElement</code> object with the specified
* name and adds it to this <code>SOAPBody</code> object.
* Creates a new {@code SOAPBodyElement} object with the specified
* name and adds it to this {@code SOAPBody} object.
*
* @param name
* a <code>Name</code> object with the name for the new <code>SOAPBodyElement</code>
* a {@code Name} object with the name for the new {@code SOAPBodyElement}
* object
* @return the new <code>SOAPBodyElement</code> object
* @return the new {@code SOAPBodyElement} object
* @exception SOAPException
* if a SOAP error occurs
* @see SOAPBody#addBodyElement(javax.xml.namespace.QName)
@ -243,13 +243,13 @@ public interface SOAPBody extends SOAPElement {
/**
* Creates a new <code>SOAPBodyElement</code> object with the specified
* QName and adds it to this <code>SOAPBody</code> object.
* Creates a new {@code SOAPBodyElement} object with the specified
* QName and adds it to this {@code SOAPBody} object.
*
* @param qname
* a <code>QName</code> object with the qname for the new
* <code>SOAPBodyElement</code> object
* @return the new <code>SOAPBodyElement</code> object
* a {@code QName} object with the qname for the new
* {@code SOAPBodyElement} object
* @return the new {@code SOAPBodyElement} object
* @exception SOAPException
* if a SOAP error occurs
* @see SOAPBody#addBodyElement(Name)
@ -259,20 +259,20 @@ public interface SOAPBody extends SOAPElement {
/**
* Adds the root node of the DOM <code>{@link org.w3c.dom.Document}</code>
* to this <code>SOAPBody</code> object.
* to this {@code SOAPBody} object.
* <p>
* Calling this method invalidates the <code>document</code> parameter.
* The client application should discard all references to this <code>Document</code>
* and its contents upon calling <code>addDocument</code>. The behavior
* Calling this method invalidates the {@code document} parameter.
* The client application should discard all references to this {@code Document}
* and its contents upon calling {@code addDocument}. The behavior
* of an application that continues to use such references is undefined.
*
* @param document
* the <code>Document</code> object whose root node will be
* added to this <code>SOAPBody</code>.
* @return the <code>SOAPBodyElement</code> that represents the root node
* the {@code Document} object whose root node will be
* added to this {@code SOAPBody}.
* @return the {@code SOAPBodyElement} that represents the root node
* that was added.
* @exception SOAPException
* if the <code>Document</code> cannot be added
* if the {@code Document} cannot be added
* @since 1.6, SAAJ 1.2
*/
public SOAPBodyElement addDocument(org.w3c.dom.Document document)
@ -280,16 +280,16 @@ public interface SOAPBody extends SOAPElement {
/**
* Creates a new DOM <code>{@link org.w3c.dom.Document}</code> and sets
* the first child of this <code>SOAPBody</code> as it's document
* element. The child <code>SOAPElement</code> is removed as part of the
* the first child of this {@code SOAPBody} as it's document
* element. The child {@code SOAPElement} is removed as part of the
* process.
*
* @return the <code>{@link org.w3c.dom.Document}</code> representation
* of the <code>SOAPBody</code> content.
* of the {@code SOAPBody} content.
*
* @exception SOAPException
* if there is not exactly one child <code>SOAPElement</code> of the <code>
* <code>SOAPBody</code>.
* if there is not exactly one child {@code SOAPElement} of the
* {@code SOAPBody}.
*
* @since 1.6, SAAJ 1.3
*/

318
jaxws/src/java.xml.ws/share/classes/javax/xml/soap/SOAPElement.java
View File

@ -38,7 +38,7 @@ import javax.xml.namespace.QName;
* Methods in this interface that are required to return SAAJ specific objects
* may "silently" replace nodes in the tree as required to successfully return
* objects of the correct type. See {@link #getChildElements()} and
* {@link <a HREF="package-summary.html#package_description">javax.xml.soap<a>}
* {@link <a HREF="package-summary.html#package_description">javax.xml.soap</a>}
* for details.
*
* @since 1.6
@ -46,115 +46,115 @@ import javax.xml.namespace.QName;
public interface SOAPElement extends Node, org.w3c.dom.Element {
/**
* Creates a new <code>SOAPElement</code> object initialized with the
* given <code>Name</code> object and adds the new element to this
* <code>SOAPElement</code> object.
* Creates a new {@code SOAPElement} object initialized with the
* given {@code Name} object and adds the new element to this
* {@code SOAPElement} object.
* <P>
* This method may be deprecated in a future release of SAAJ in favor of
* addChildElement(javax.xml.namespace.QName)
*
* @param name a <code>Name</code> object with the XML name for the
* @param name a {@code Name} object with the XML name for the
* new element
*
* @return the new <code>SOAPElement</code> object that was created
* @return the new {@code SOAPElement} object that was created
* @exception SOAPException if there is an error in creating the
* <code>SOAPElement</code> object
* {@code SOAPElement} object
* @see SOAPElement#addChildElement(javax.xml.namespace.QName)
*/
public SOAPElement addChildElement(Name name) throws SOAPException;
/**
* Creates a new <code>SOAPElement</code> object initialized with the given
* <code>QName</code> object and adds the new element to this <code>SOAPElement</code>
* Creates a new {@code SOAPElement} object initialized with the given
* {@code QName} object and adds the new element to this {@code SOAPElement}
* object. The <i>namespace</i>, <i>localname</i> and <i>prefix</i> of the new
* <code>SOAPElement</code> are all taken from the <code>qname</code> argument.
* {@code SOAPElement} are all taken from the {@code qname} argument.
*
* @param qname a <code>QName</code> object with the XML name for the
* @param qname a {@code QName} object with the XML name for the
* new element
*
* @return the new <code>SOAPElement</code> object that was created
* @return the new {@code SOAPElement} object that was created
* @exception SOAPException if there is an error in creating the
* <code>SOAPElement</code> object
* {@code SOAPElement} object
* @see SOAPElement#addChildElement(Name)
* @since 1.6, SAAJ 1.3
*/
public SOAPElement addChildElement(QName qname) throws SOAPException;
/**
* Creates a new <code>SOAPElement</code> object initialized with the
* Creates a new {@code SOAPElement} object initialized with the
* specified local name and adds the new element to this
* <code>SOAPElement</code> object.
* The new <code>SOAPElement</code> inherits any in-scope default namespace.
* {@code SOAPElement} object.
* The new {@code SOAPElement} inherits any in-scope default namespace.
*
* @param localName a <code>String</code> giving the local name for
* @param localName a {@code String} giving the local name for
* the element
* @return the new <code>SOAPElement</code> object that was created
* @return the new {@code SOAPElement} object that was created
* @exception SOAPException if there is an error in creating the
* <code>SOAPElement</code> object
* {@code SOAPElement} object
*/
public SOAPElement addChildElement(String localName) throws SOAPException;
/**
* Creates a new <code>SOAPElement</code> object initialized with the
* Creates a new {@code SOAPElement} object initialized with the
* specified local name and prefix and adds the new element to this
* <code>SOAPElement</code> object.
* {@code SOAPElement} object.
*
* @param localName a <code>String</code> giving the local name for
* @param localName a {@code String} giving the local name for
* the new element
* @param prefix a <code>String</code> giving the namespace prefix for
* @param prefix a {@code String} giving the namespace prefix for
* the new element
*
* @return the new <code>SOAPElement</code> object that was created
* @exception SOAPException if the <code>prefix</code> is not valid in the
* context of this <code>SOAPElement</code> or if there is an error in creating the
* <code>SOAPElement</code> object
* @return the new {@code SOAPElement} object that was created
* @exception SOAPException if the {@code prefix} is not valid in the
* context of this {@code SOAPElement} or if there is an error in creating the
* {@code SOAPElement} object
*/
public SOAPElement addChildElement(String localName, String prefix)
throws SOAPException;
/**
* Creates a new <code>SOAPElement</code> object initialized with the
* Creates a new {@code SOAPElement} object initialized with the
* specified local name, prefix, and URI and adds the new element to this
* <code>SOAPElement</code> object.
* {@code SOAPElement} object.
*
* @param localName a <code>String</code> giving the local name for
* @param localName a {@code String} giving the local name for
* the new element
* @param prefix a <code>String</code> giving the namespace prefix for
* @param prefix a {@code String} giving the namespace prefix for
* the new element
* @param uri a <code>String</code> giving the URI of the namespace
* @param uri a {@code String} giving the URI of the namespace
* to which the new element belongs
*
* @return the new <code>SOAPElement</code> object that was created
* @return the new {@code SOAPElement} object that was created
* @exception SOAPException if there is an error in creating the
* <code>SOAPElement</code> object
* {@code SOAPElement} object
*/
public SOAPElement addChildElement(String localName, String prefix,
String uri)
throws SOAPException;
/**
* Add a <code>SOAPElement</code> as a child of this
* <code>SOAPElement</code> instance. The <code>SOAPElement</code>
* Add a {@code SOAPElement} as a child of this
* {@code SOAPElement} instance. The {@code SOAPElement}
* is expected to be created by a
* <code>SOAPFactory</code>. Callers should not rely on the
* {@code SOAPFactory}. Callers should not rely on the
* element instance being added as is into the XML
* tree. Implementations could end up copying the content
* of the <code>SOAPElement</code> passed into an instance of
* a different <code>SOAPElement</code> implementation. For
* instance if <code>addChildElement()</code> is called on a
* <code>SOAPHeader</code>, <code>element</code> will be copied
* into an instance of a <code>SOAPHeaderElement</code>.
* of the {@code SOAPElement} passed into an instance of
* a different {@code SOAPElement} implementation. For
* instance if {@code addChildElement()} is called on a
* {@code SOAPHeader}, {@code element} will be copied
* into an instance of a {@code SOAPHeaderElement}.
*
* <P>The fragment rooted in <code>element</code> is either added
* <P>The fragment rooted in {@code element} is either added
* as a whole or not at all, if there was an error.
*
* <P>The fragment rooted in <code>element</code> cannot contain
* <P>The fragment rooted in {@code element} cannot contain
* elements named "Envelope", "Header" or "Body" and in the SOAP
* namespace. Any namespace prefixes present in the fragment
* should be fully resolved using appropriate namespace
* declarations within the fragment itself.
*
* @param element the <code>SOAPElement</code> to be added as a
* @param element the {@code SOAPElement} to be added as a
* new child
*
* @exception SOAPException if there was an error in adding this
@ -167,10 +167,10 @@ public interface SOAPElement extends Node, org.w3c.dom.Element {
throws SOAPException;
/**
* Detaches all children of this <code>SOAPElement</code>.
* Detaches all children of this {@code SOAPElement}.
* <p>
* This method is useful for rolling back the construction of partially
* completed <code>SOAPHeaders</code> and <code>SOAPBodys</code> in
* completed {@code SOAPHeaders} and {@code SOAPBodys} in
* preparation for sending a fault when an error condition is detected. It
* is also useful for recycling portions of a document within a SOAP
* message.
@ -180,33 +180,33 @@ public interface SOAPElement extends Node, org.w3c.dom.Element {
public abstract void removeContents();
/**
* Creates a new <code>Text</code> object initialized with the given
* <code>String</code> and adds it to this <code>SOAPElement</code> object.
* Creates a new {@code Text} object initialized with the given
* {@code String} and adds it to this {@code SOAPElement} object.
*
* @param text a <code>String</code> object with the textual content to be added
* @param text a {@code String} object with the textual content to be added
*
* @return the <code>SOAPElement</code> object into which
* the new <code>Text</code> object was inserted
* @return the {@code SOAPElement} object into which
* the new {@code Text} object was inserted
* @exception SOAPException if there is an error in creating the
* new <code>Text</code> object or if it is not legal to
* new {@code Text} object or if it is not legal to
* attach it as a child to this
* <code>SOAPElement</code>
* {@code SOAPElement}
*/
public SOAPElement addTextNode(String text) throws SOAPException;
/**
* Adds an attribute with the specified name and value to this
* <code>SOAPElement</code> object.
* {@code SOAPElement} object.
*
* @param name a <code>Name</code> object with the name of the attribute
* @param value a <code>String</code> giving the value of the attribute
* @return the <code>SOAPElement</code> object into which the attribute was
* @param name a {@code Name} object with the name of the attribute
* @param value a {@code String} giving the value of the attribute
* @return the {@code SOAPElement} object into which the attribute was
* inserted
*
* @exception SOAPException if there is an error in creating the
* Attribute, or it is invalid to set
an attribute with <code>Name</code>
<code>name</code> on this SOAPElement.
an attribute with {@code Name}
{@code name} on this SOAPElement.
* @see SOAPElement#addAttribute(javax.xml.namespace.QName, String)
*/
public SOAPElement addAttribute(Name name, String value)
@ -214,17 +214,17 @@ public interface SOAPElement extends Node, org.w3c.dom.Element {
/**
* Adds an attribute with the specified name and value to this
* <code>SOAPElement</code> object.
* {@code SOAPElement} object.
*
* @param qname a <code>QName</code> object with the name of the attribute
* @param value a <code>String</code> giving the value of the attribute
* @return the <code>SOAPElement</code> object into which the attribute was
* @param qname a {@code QName} object with the name of the attribute
* @param value a {@code String} giving the value of the attribute
* @return the {@code SOAPElement} object into which the attribute was
* inserted
*
* @exception SOAPException if there is an error in creating the
* Attribute, or it is invalid to set
an attribute with <code>QName</code>
<code>qname</code> on this SOAPElement.
an attribute with {@code QName}
{@code qname} on this SOAPElement.
* @see SOAPElement#addAttribute(Name, String)
* @since 1.6, SAAJ 1.3
*/
@ -233,11 +233,11 @@ public interface SOAPElement extends Node, org.w3c.dom.Element {
/**
* Adds a namespace declaration with the specified prefix and URI to this
* <code>SOAPElement</code> object.
* {@code SOAPElement} object.
*
* @param prefix a <code>String</code> giving the prefix of the namespace
* @param uri a <code>String</code> giving the uri of the namespace
* @return the <code>SOAPElement</code> object into which this
* @param prefix a {@code String} giving the prefix of the namespace
* @param uri a {@code String} giving the uri of the namespace
* @return the {@code SOAPElement} object into which this
* namespace declaration was inserted.
*
* @exception SOAPException if there is an error in creating the
@ -249,8 +249,8 @@ public interface SOAPElement extends Node, org.w3c.dom.Element {
/**
* Returns the value of the attribute with the specified name.
*
* @param name a <code>Name</code> object with the name of the attribute
* @return a <code>String</code> giving the value of the specified
* @param name a {@code Name} object with the name of the attribute
* @return a {@code String} giving the value of the specified
* attribute, Null if there is no such attribute
* @see SOAPElement#getAttributeValue(javax.xml.namespace.QName)
*/
@ -259,8 +259,8 @@ public interface SOAPElement extends Node, org.w3c.dom.Element {
/**
* Returns the value of the attribute with the specified qname.
*
* @param qname a <code>QName</code> object with the qname of the attribute
* @return a <code>String</code> giving the value of the specified
* @param qname a {@code QName} object with the qname of the attribute
* @return a {@code String} giving the value of the specified
* attribute, Null if there is no such attribute
* @see SOAPElement#getAttributeValue(Name)
* @since 1.6, SAAJ 1.3
@ -268,11 +268,11 @@ public interface SOAPElement extends Node, org.w3c.dom.Element {
public String getAttributeValue(QName qname);
/**
* Returns an <code>Iterator</code> over all of the attribute
* <code>Name</code> objects in this
* <code>SOAPElement</code> object. The iterator can be used to get
* Returns an {@code Iterator} over all of the attribute
* {@code Name} objects in this
* {@code SOAPElement} object. The iterator can be used to get
* the attribute names, which can then be passed to the method
* <code>getAttributeValue</code> to retrieve the value of each
* {@code getAttributeValue} to retrieve the value of each
* attribute.
*
* @see SOAPElement#getAllAttributesAsQNames()
@ -281,10 +281,10 @@ public interface SOAPElement extends Node, org.w3c.dom.Element {
public Iterator getAllAttributes();
/**
* Returns an <code>Iterator</code> over all of the attributes
* in this <code>SOAPElement</code> as <code>QName</code> objects.
* Returns an {@code Iterator} over all of the attributes
* in this {@code SOAPElement} as {@code QName} objects.
* The iterator can be used to get the attribute QName, which can then
* be passed to the method <code>getAttributeValue</code> to retrieve
* be passed to the method {@code getAttributeValue} to retrieve
* the value of each attribute.
*
* @return an iterator over the QNames of the attributes
@ -297,94 +297,94 @@ public interface SOAPElement extends Node, org.w3c.dom.Element {
/**
* Returns the URI of the namespace that has the given prefix.
*
* @param prefix a <code>String</code> giving the prefix of the namespace
* @param prefix a {@code String} giving the prefix of the namespace
* for which to search
* @return a <code>String</code> with the uri of the namespace that has
* @return a {@code String} with the uri of the namespace that has
* the given prefix
*/
public String getNamespaceURI(String prefix);
/**
* Returns an <code>Iterator</code> over the namespace prefix
* <code>String</code>s declared by this element. The prefixes returned by
* Returns an {@code Iterator} over the namespace prefix
* {@code String}s declared by this element. The prefixes returned by
* this iterator can be passed to the method
* <code>getNamespaceURI</code> to retrieve the URI of each namespace.
* {@code getNamespaceURI} to retrieve the URI of each namespace.
*
* @return an iterator over the namespace prefixes in this
* <code>SOAPElement</code> object
* {@code SOAPElement} object
*/
public Iterator getNamespacePrefixes();
/**
* Returns an <code>Iterator</code> over the namespace prefix
* <code>String</code>s visible to this element. The prefixes returned by
* Returns an {@code Iterator} over the namespace prefix
* {@code String}s visible to this element. The prefixes returned by
* this iterator can be passed to the method
* <code>getNamespaceURI</code> to retrieve the URI of each namespace.
* {@code getNamespaceURI} to retrieve the URI of each namespace.
*
* @return an iterator over the namespace prefixes are within scope of this
* <code>SOAPElement</code> object
* {@code SOAPElement} object
*
* @since 1.6, SAAJ 1.2
*/
public Iterator getVisibleNamespacePrefixes();
/**
* Creates a <code>QName</code> whose namespace URI is the one associated
* with the parameter, <code>prefix</code>, in the context of this
* <code>SOAPElement</code>. The remaining elements of the new
* <code>QName</code> are taken directly from the parameters,
* <code>localName</code> and <code>prefix</code>.
* Creates a {@code QName} whose namespace URI is the one associated
* with the parameter, {@code prefix}, in the context of this
* {@code SOAPElement}. The remaining elements of the new
* {@code QName} are taken directly from the parameters,
* {@code localName} and {@code prefix}.
*
* @param localName
* a <code>String</code> containing the local part of the name.
* a {@code String} containing the local part of the name.
* @param prefix
* a <code>String</code> containing the prefix for the name.
* a {@code String} containing the prefix for the name.
*
* @return a <code>QName</code> with the specified <code>localName</code>
* and <code>prefix</code>, and with a namespace that is associated
* with the <code>prefix</code> in the context of this
* <code>SOAPElement</code>. This namespace will be the same as
* @return a {@code QName} with the specified {@code localName}
* and {@code prefix}, and with a namespace that is associated
* with the {@code prefix} in the context of this
* {@code SOAPElement}. This namespace will be the same as
* the one that would be returned by
* <code>{@link #getNamespaceURI(String)}</code> if it were given
* <code>prefix</code> as it's parameter.
* {@code prefix} as it's parameter.
*
* @exception SOAPException if the <code>QName</code> cannot be created.
* @exception SOAPException if the {@code QName} cannot be created.
*
* @since 1.6, SAAJ 1.3
*/
public QName createQName(String localName, String prefix)
throws SOAPException;
/**
* Returns the name of this <code>SOAPElement</code> object.
* Returns the name of this {@code SOAPElement} object.
*
* @return a <code>Name</code> object with the name of this
* <code>SOAPElement</code> object
* @return a {@code Name} object with the name of this
* {@code SOAPElement} object
*/
public Name getElementName();
/**
* Returns the qname of this <code>SOAPElement</code> object.
* Returns the qname of this {@code SOAPElement} object.
*
* @return a <code>QName</code> object with the qname of this
* <code>SOAPElement</code> object
* @return a {@code QName} object with the qname of this
* {@code SOAPElement} object
* @see SOAPElement#getElementName()
* @since 1.6, SAAJ 1.3
*/
public QName getElementQName();
/**
* Changes the name of this <code>Element</code> to <code>newName</code> if
* Changes the name of this {@code Element} to {@code newName} if
* possible. SOAP Defined elements such as SOAPEnvelope, SOAPHeader, SOAPBody
* etc. cannot have their names changed using this method. Any attempt to do
* so will result in a SOAPException being thrown.
*<P>
* Callers should not rely on the element instance being renamed as is.
* Implementations could end up copying the content of the
* <code>SOAPElement</code> to a renamed instance.
* {@code SOAPElement} to a renamed instance.
*
* @param newName the new name for the <code>Element</code>.
* @param newName the new name for the {@code Element}.
*
* @exception SOAPException if changing the name of this <code>Element</code>
* @exception SOAPException if changing the name of this {@code Element}
* is not allowed.
* @return The renamed Node
*
@ -395,10 +395,10 @@ public interface SOAPElement extends Node, org.w3c.dom.Element {
/**
* Removes the attribute with the specified name.
*
* @param name the <code>Name</code> object with the name of the
* @param name the {@code Name} object with the name of the
* attribute to be removed
* @return <code>true</code> if the attribute was
* removed successfully; <code>false</code> if it was not
* @return {@code true} if the attribute was
* removed successfully; {@code false} if it was not
* @see SOAPElement#removeAttribute(javax.xml.namespace.QName)
*/
public boolean removeAttribute(Name name);
@ -406,10 +406,10 @@ public interface SOAPElement extends Node, org.w3c.dom.Element {
/**
* Removes the attribute with the specified qname.
*
* @param qname the <code>QName</code> object with the qname of the
* @param qname the {@code QName} object with the qname of the
* attribute to be removed
* @return <code>true</code> if the attribute was
* removed successfully; <code>false</code> if it was not
* @return {@code true} if the attribute was
* removed successfully; {@code false} if it was not
* @see SOAPElement#removeAttribute(Name)
* @since 1.6, SAAJ 1.3
*/
@ -418,84 +418,84 @@ public interface SOAPElement extends Node, org.w3c.dom.Element {
/**
* Removes the namespace declaration corresponding to the given prefix.
*
* @param prefix a <code>String</code> giving the prefix for which
* @param prefix a {@code String} giving the prefix for which
* to search
* @return <code>true</code> if the namespace declaration was
* removed successfully; <code>false</code> if it was not
* @return {@code true} if the namespace declaration was
* removed successfully; {@code false} if it was not
*/
public boolean removeNamespaceDeclaration(String prefix);
/**
* Returns an <code>Iterator</code> over all the immediate child
* {@link Node}s of this element. This includes <code>javax.xml.soap.Text</code>
* objects as well as <code>SOAPElement</code> objects.
* Returns an {@code Iterator} over all the immediate child
* {@link Node}s of this element. This includes {@code javax.xml.soap.Text}
* objects as well as {@code SOAPElement} objects.
* <p>
* Calling this method may cause child <code>Element</code>,
* <code>SOAPElement</code> and <code>org.w3c.dom.Text</code> nodes to be
* replaced by <code>SOAPElement</code>, <code>SOAPHeaderElement</code>,
* <code>SOAPBodyElement</code> or <code>javax.xml.soap.Text</code> nodes as
* Calling this method may cause child {@code Element},
* {@code SOAPElement} and {@code org.w3c.dom.Text} nodes to be
* replaced by {@code SOAPElement}, {@code SOAPHeaderElement},
* {@code SOAPBodyElement} or {@code javax.xml.soap.Text} nodes as
* appropriate for the type of this parent node. As a result the calling
* application must treat any existing references to these child nodes that
* have been obtained through DOM APIs as invalid and either discard them or
* refresh them with the values returned by this <code>Iterator</code>. This
* refresh them with the values returned by this {@code Iterator}. This
* behavior can be avoided by calling the equivalent DOM APIs. See
* {@link <a HREF="package-summary.html#package_description">javax.xml.soap<a>}
* {@link <a HREF="package-summary.html#package_description">javax.xml.soap</a>}
* for more details.
*
* @return an iterator with the content of this <code>SOAPElement</code>
* @return an iterator with the content of this {@code SOAPElement}
* object
*/
public Iterator getChildElements();
/**
* Returns an <code>Iterator</code> over all the immediate child
* Returns an {@code Iterator} over all the immediate child
* {@link Node}s of this element with the specified name. All of these
* children will be <code>SOAPElement</code> nodes.
* children will be {@code SOAPElement} nodes.
* <p>
* Calling this method may cause child <code>Element</code>,
* <code>SOAPElement</code> and <code>org.w3c.dom.Text</code> nodes to be
* replaced by <code>SOAPElement</code>, <code>SOAPHeaderElement</code>,
* <code>SOAPBodyElement</code> or <code>javax.xml.soap.Text</code> nodes as
* Calling this method may cause child {@code Element},
* {@code SOAPElement} and {@code org.w3c.dom.Text} nodes to be
* replaced by {@code SOAPElement}, {@code SOAPHeaderElement},
* {@code SOAPBodyElement} or {@code javax.xml.soap.Text} nodes as
* appropriate for the type of this parent node. As a result the calling
* application must treat any existing references to these child nodes that
* have been obtained through DOM APIs as invalid and either discard them or
* refresh them with the values returned by this <code>Iterator</code>. This
* refresh them with the values returned by this {@code Iterator}. This
* behavior can be avoided by calling the equivalent DOM APIs. See
* {@link <a HREF="package-summary.html#package_description">javax.xml.soap<a>}
* {@link <a HREF="package-summary.html#package_description">javax.xml.soap</a>}
* for more details.
*
* @param name a <code>Name</code> object with the name of the child
* @param name a {@code Name} object with the name of the child
* elements to be returned
*
* @return an <code>Iterator</code> object over all the elements
* in this <code>SOAPElement</code> object with the
* @return an {@code Iterator} object over all the elements
* in this {@code SOAPElement} object with the
* specified name
* @see SOAPElement#getChildElements(javax.xml.namespace.QName)
*/
public Iterator getChildElements(Name name);
/**
* Returns an <code>Iterator</code> over all the immediate child
* Returns an {@code Iterator} over all the immediate child
* {@link Node}s of this element with the specified qname. All of these
* children will be <code>SOAPElement</code> nodes.
* children will be {@code SOAPElement} nodes.
* <p>
* Calling this method may cause child <code>Element</code>,
* <code>SOAPElement</code> and <code>org.w3c.dom.Text</code> nodes to be
* replaced by <code>SOAPElement</code>, <code>SOAPHeaderElement</code>,
* <code>SOAPBodyElement</code> or <code>javax.xml.soap.Text</code> nodes as
* Calling this method may cause child {@code Element},
* {@code SOAPElement} and {@code org.w3c.dom.Text} nodes to be
* replaced by {@code SOAPElement}, {@code SOAPHeaderElement},
* {@code SOAPBodyElement} or {@code javax.xml.soap.Text} nodes as
* appropriate for the type of this parent node. As a result the calling
* application must treat any existing references to these child nodes that
* have been obtained through DOM APIs as invalid and either discard them or
* refresh them with the values returned by this <code>Iterator</code>. This
* refresh them with the values returned by this {@code Iterator}. This
* behavior can be avoided by calling the equivalent DOM APIs. See
* {@link <a HREF="package-summary.html#package_description">javax.xml.soap<a>}
* {@link <a HREF="package-summary.html#package_description">javax.xml.soap</a>}
* for more details.
*
* @param qname a <code>QName</code> object with the qname of the child
* @param qname a {@code QName} object with the qname of the child
* elements to be returned
*
* @return an <code>Iterator</code> object over all the elements
* in this <code>SOAPElement</code> object with the
* @return an {@code Iterator} object over all the elements
* in this {@code SOAPElement} object with the
* specified qname
* @see SOAPElement#getChildElements(Name)
* @since 1.6, SAAJ 1.3
@ -503,10 +503,10 @@ public interface SOAPElement extends Node, org.w3c.dom.Element {
public Iterator getChildElements(QName qname);
/**
* Sets the encoding style for this <code>SOAPElement</code> object
* Sets the encoding style for this {@code SOAPElement} object
* to one specified.
*
* @param encodingStyle a <code>String</code> giving the encoding style
* @param encodingStyle a {@code String} giving the encoding style
*
* @exception IllegalArgumentException if there was a problem in the
* encoding style being set.
@ -516,9 +516,9 @@ public interface SOAPElement extends Node, org.w3c.dom.Element {
public void setEncodingStyle(String encodingStyle)
throws SOAPException;
/**
* Returns the encoding style for this <code>SOAPElement</code> object.
* Returns the encoding style for this {@code SOAPElement} object.
*
* @return a <code>String</code> giving the encoding style
* @return a {@code String} giving the encoding style
*
* @see #setEncodingStyle
*/

229
jaxws/src/java.xml.ws/share/classes/javax/xml/soap/SOAPMessage.java
View File

@ -36,24 +36,24 @@ import javax.activation.DataHandler;
* message is an XML document or a MIME message whose first body part is an
* XML/SOAP document.
* <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
* 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.
* <P>
* A new <code>SOAPMessage</code> object contains the following by default:
* A new {@code SOAPMessage} object contains the following by default:
* <UL>
* <LI>A <code>SOAPPart</code> object
* <LI>A <code>SOAPEnvelope</code> object
* <LI>A <code>SOAPBody</code> object
* <LI>A <code>SOAPHeader</code> object
* <LI>A {@code SOAPPart} object
* <LI>A {@code SOAPEnvelope} object
* <LI>A {@code SOAPBody} object
* <LI>A {@code SOAPHeader} object
* </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.
* 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.
*
* <PRE>
* SOAPPart sp = message.getSOAPPart();
@ -63,32 +63,32 @@ import javax.activation.DataHandler;
* </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
* 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.
* <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.
* {@code AttachmentPart} object.
* <P>
* A <code>MessageFactory</code> object may create <code>SOAPMessage</code>
* 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 <code>MessageFactory</code> object
* may produce <code>SOAPMessage</code> objects that conform to a particular
* Profile such as ebXML. In this case a <code>MessageFactory</code> object
* might produce <code>SOAPMessage</code> 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.
* <P>
* 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 <code>UnsupportedOperationException</code>
* 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 @@ public abstract class SOAPMessage {
"javax.xml.soap.write-xml-declaration";
/**
* Sets the description of this <code>SOAPMessage</code> object's
* Sets the description of this {@code SOAPMessage} object's
* content with the given description.
*
* @param description a <code>String</code> 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 <code>SOAPMessage</code> object's
* Retrieves a description of this {@code SOAPMessage} object's
* content.
*
* @return a <code>String</code> describing the content of this
* message or <code>null</code> 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 <code>SOAPMessage</code> object.
* Gets the SOAP part of this {@code SOAPMessage} object.
* <P>
* <code>SOAPMessage</code> 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 <code>SOAPPart</code> object for this <code>SOAPMessage</code>
* @return the {@code SOAPPart} object for this {@code SOAPMessage}
* object
*/
public abstract SOAPPart getSOAPPart();
/**
* Gets the SOAP Body contained in this <code>SOAPMessage</code> object.
* <p>
* Gets the SOAP Body contained in this {@code SOAPMessage} object.
*
* @return the <code>SOAPBody</code> object contained by this <code>SOAPMessage</code>
* @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 @@ public abstract class SOAPMessage {
}
/**
* Gets the SOAP Header contained in this <code>SOAPMessage</code>
* object.
* <p>
*
* @return the <code>SOAPHeader</code> object contained by this <code>SOAPMessage</code>
* 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 <code>AttachmentPart</code> objects that have been added
* to this <code>SOAPMessage</code> object.
* Removes all {@code AttachmentPart} objects that have been added
* to this {@code SOAPMessage} object.
* <P>
* This method does not touch the SOAP part.
*/
@ -197,26 +194,26 @@ public abstract class SOAPMessage {
* 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
* @return the number of {@code AttachmentPart} objects that are
* part of this {@code SOAPMessage} object
*/
public abstract int countAttachments();
/**
* Retrieves all the <code>AttachmentPart</code> objects that are part of
* this <code>SOAPMessage</code> 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 <code>AttachmentPart</code> 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 <code>MimeHeaders</code> 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 class SOAPMessage {
public abstract Iterator getAttachments(MimeHeaders headers);
/**
* Removes all the <code>AttachmentPart</code> 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 <code>MimeHeaders</code> 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 @@ public abstract class SOAPMessage {
/**
* Returns an <code>AttachmentPart</code> object that is associated with an
* attachment that is referenced by this <code>SOAPElement</code> or
* <code>null</code> if no such attachment exists. References can be made
* via an <code>href</code> attribute as described in
* {@link <a href="http://www.w3.org/TR/SOAP-attachments#SOAPReferenceToAttachements">SOAP Messages with Attachments</a>},
* or via a single <code>Text</code> 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
* <a href="http://www.w3.org/TR/SOAP-attachments#SOAPReferenceToAttachements">SOAP Messages with Attachments</a>,
* 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 <a href="http://www.ws-i.org/Profiles/AttachmentsProfile-1.0-2004-08-24.html">ref:swaRef</a>}. These two mechanisms must be supported.
* The support for references via <code>href</code> attribute also implies that
* type <a href="http://www.ws-i.org/Profiles/AttachmentsProfile-1.0-2004-08-24.html">ref:swaRef</a>.
* 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
* <i>xop:Include</i> element (
* {@link <a href="http://www.w3.org/2000/xp/Group/3/06/Attachments/XOP.html">XOP</a>}).
* <a href="http://www.w3.org/2000/xp/Group/3/06/Attachments/XOP.html">XOP</a>).
* other reference mechanisms may be supported by individual
* implementations of this standard. Contact your vendor for details.
*
* @param element The <code>SOAPElement</code> containing the reference to an Attachment
* @return the referenced <code>AttachmentPart</code> or null if no such
* <code>AttachmentPart</code> exists or no reference can be
* found in this <code>SOAPElement</code>.
* @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 @@ public abstract class SOAPMessage {
/**
* Adds the given <code>AttachmentPart</code> object to this <code>SOAPMessage</code>
* object. An <code>AttachmentPart</code> 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 <code>AttachmentPart</code> object that is to become part
* of this <code>SOAPMessage</code> 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 <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.
* 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 <code>AttachmentPart</code> object that can be populated
* and added to this <code>SOAPMessage</code> object
* @return a new {@code AttachmentPart} object that can be populated
* and added to this {@code SOAPMessage} object
*/
public abstract AttachmentPart createAttachmentPart();
/**
* Creates an <code>AttachmentPart</code> object and populates it using
* the given <code>DataHandler</code> object.
* Creates an {@code AttachmentPart} object and populates it using
* the given {@code DataHandler} object.
*
* @param dataHandler
* the <code>javax.activation.DataHandler</code> object that
* will generate the content for this <code>SOAPMessage</code>
* the {@code javax.activation.DataHandler} object that
* will generate the content for this {@code SOAPMessage}
* object
* @return a new <code>AttachmentPart</code> object that contains data
* generated by the given <code>DataHandler</code> 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 <code>DataHandler</code>
* if there was a problem with the specified {@code DataHandler}
* object
* @see javax.activation.DataHandler
* @see javax.activation.DataContentHandler
@ -310,32 +308,32 @@ public abstract class SOAPMessage {
}
/**
* Returns all the transport-specific MIME headers for this <code>SOAPMessage</code>
* Returns all the transport-specific MIME headers for this {@code SOAPMessage}
* object in a transport-independent fashion.
*
* @return a <code>MimeHeaders</code> object containing the <code>MimeHeader</code>
* @return a {@code MimeHeaders} object containing the {@code MimeHeader}
* objects
*/
public abstract MimeHeaders getMimeHeaders();
/**
* Creates an <code>AttachmentPart</code> 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
* <code>Object</code> should correspond to the value given for the
* <code>Content-Type</code>.
* {@code Object} should correspond to the value given for the
* {@code Content-Type}.
*
* @param content
* an <code>Object</code> containing the content for the
* <code>AttachmentPart</code> object to be created
* an {@code Object} containing the content for the
* {@code AttachmentPart} object to be created
* @param contentType
* a <code>String</code> 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 <code>AttachmentPart</code> 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
* <code>DataContentHandler</code> object for the given
* {@code DataContentHandler} object for the given
* content object
* @see javax.activation.DataHandler
* @see javax.activation.DataContentHandler
@ -349,50 +347,49 @@ public abstract class SOAPMessage {
}
/**
* Updates this <code>SOAPMessage</code> 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 <code>saveChanges</code> needs to be
* called explicitly in order to save the changes. The method <code>saveChanges</code>
* 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 <code>saveChanges</code> has been called.
* valid values only after {@code saveChanges} 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
* constituent {@code AttachmentPart} objects are pulled into the
* message.
* <P>
*
* @exception <code>SOAPException</code> 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 <code>SOAPMessage</code> object needs to have
* the method <code>saveChanges</code> called on it.
* Indicates whether this {@code SOAPMessage} object needs to have
* the method {@code saveChanges} called on it.
*
* @return <code>true</code> if <code>saveChanges</code> needs to be
* called; <code>false</code> otherwise.
* @return {@code true} if {@code saveChanges} needs to be
* called; {@code false} otherwise.
*/
public abstract boolean saveRequired();
/**
* Writes this <code>SOAPMessage</code> 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.
* <P>
* If there are no attachments, just an XML stream is written out. For
* those messages that have attachments, <code>writeTo</code> writes a
* those messages that have attachments, {@code writeTo} writes a
* MIME-encoded byte stream.
* <P>
* Note that this method does not write the transport-specific MIME Headers
* of the Message
*
* @param out
* the <code>OutputStream</code> object to which this <code>SOAPMessage</code>
* 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 @@ public abstract class SOAPMessage {
* 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>
* 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.
* <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>
* 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.
* <p>
* Some implementations may allow encodings in addition to UTF-8 and
@ -445,7 +442,7 @@ public abstract class SOAPMessage {
*
* @param property
* the name of the property to retrieve
* @return the value associated with the named property or <code>null</code>
* @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.

121
jaxws/src/java.xml.ws/share/classes/javax/xml/soap/SOAPPart.java
View File

@ -30,52 +30,51 @@ import java.util.Iterator;
import javax.xml.transform.Source;
/**
* The container for the SOAP-specific portion of a <code>SOAPMessage</code>
* The container for the SOAP-specific portion of a {@code SOAPMessage}
* 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>
* A <code>SOAPPart</code> object is a MIME part and has the MIME headers
* {@code SOAPMessage} object is created, it will automatically
* have a {@code SOAPPart} object.
* <P>
* A {@code SOAPPart} 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
* Content-Type must be "text/xml", a {@code SOAPPart} 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.
* must be in an {@code AttachmentPart} object rather than in the
* {@code SOAPPart} object.
* <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>
* 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.
* A client can access the {@code SOAPPart} object of a
* {@code SOAPMessage} object by
* calling the method {@code SOAPMessage.getSOAPPart}. The
* following line of code, in which {@code message} is a
* {@code SOAPMessage} object, retrieves the SOAP part of a message.
* <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>
* A {@code SOAPPart} object contains a {@code SOAPEnvelope} object,
* which in turn contains a {@code SOAPBody} object and a
* {@code SOAPHeader} object.
* The {@code SOAPPart} method {@code getEnvelope} can be used
* to retrieve the {@code SOAPEnvelope} object.
*
* @since 1.6
*/
public abstract class SOAPPart implements org.w3c.dom.Document, Node {
/**
* Gets the <code>SOAPEnvelope</code> object associated with this
* <code>SOAPPart</code> object. Once the SOAP envelope is obtained, it
* Gets the {@code SOAPEnvelope} object associated with this
* {@code SOAPPart} 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
* @return the {@code SOAPEnvelope} object for this
* {@code SOAPPart} object
* @exception SOAPException if there is a SOAP error
*/
public abstract SOAPEnvelope getEnvelope() throws SOAPException;
@ -83,7 +82,7 @@ public abstract class SOAPPart implements org.w3c.dom.Document, Node {
/**
* Retrieves the value of the MIME header whose name is "Content-Id".
*
* @return a <code>String</code> giving the value of the MIME header
* @return a {@code String} giving the value of the MIME header
* named "Content-Id"
* @see #setContentId
*/
@ -97,7 +96,7 @@ public abstract class SOAPPart implements org.w3c.dom.Document, Node {
/**
* 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
* @return a {@code String} giving the value of the MIME header whose
* name is "Content-Location"
* @see #setContentLocation
*/
@ -110,9 +109,9 @@ public abstract class SOAPPart implements org.w3c.dom.Document, Node {
/**
* Sets the value of the MIME header named "Content-Id"
* to the given <code>String</code>.
* to the given {@code String}.
*
* @param contentId a <code>String</code> giving the value of the MIME
* @param contentId a {@code String} giving the value of the MIME
* header "Content-Id"
*
* @exception IllegalArgumentException if there is a problem in
@ -125,9 +124,9 @@ public abstract class SOAPPart implements org.w3c.dom.Document, Node {
}
/**
* Sets the value of the MIME header "Content-Location"
* to the given <code>String</code>.
* to the given {@code String}.
*
* @param contentLocation a <code>String</code> giving the value
* @param contentLocation a {@code String} giving the value
* of the MIME
* header "Content-Location"
* @exception IllegalArgumentException if there is a problem in
@ -141,24 +140,24 @@ public abstract class SOAPPart implements org.w3c.dom.Document, Node {
/**
* Removes all MIME headers that match the given name.
*
* @param header a <code>String</code> giving the name of the MIME header(s) to
* @param header a {@code String} 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} objects for this
* {@code SOAPEnvelope} 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>.
* Gets all the values of the {@code MimeHeader} object
* in this {@code SOAPPart} object that
* is identified by the given {@code String}.
*
* @param name the name of the header; example: "Content-Type"
* @return a <code>String</code> array giving all the values for the
* @return a {@code String} array giving all the values for the
* specified header
* @see #setMimeHeader
*/
@ -176,13 +175,13 @@ public abstract class SOAPPart implements org.w3c.dom.Document, Node {
* <P>
* Note that RFC822 headers can contain only US-ASCII characters.
*
* @param name a <code>String</code> giving the header name
* @param name a {@code String} giving the header name
* for which to search
* @param value a <code>String</code> giving the value to be set.
* @param value a {@code String} 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.
* a new {@code MimeHeader} object.
*
* @exception IllegalArgumentException if there was a problem with
* the specified mime header name or value
@ -191,16 +190,16 @@ public abstract class SOAPPart implements org.w3c.dom.Document, Node {
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
* Creates a {@code MimeHeader} object with the specified
* name and value and adds it to this {@code SOAPPart} object.
* If a {@code MimeHeader} 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.
*
* @param name a <code>String</code> giving the header name
* @param value a <code>String</code> giving the value to be set
* @param name a {@code String} giving the header name
* @param value a {@code String} giving the value to be set
* or added
* @exception IllegalArgumentException if there was a problem with
* the specified mime header name or value
@ -208,44 +207,44 @@ public abstract class SOAPPart implements org.w3c.dom.Document, Node {
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.
* Retrieves all the headers for this {@code SOAPPart} object
* as an iterator over the {@code MimeHeader} objects.
*
* @return an <code>Iterator</code> object with all of the Mime
* headers for this <code>SOAPPart</code> object
* @return an {@code Iterator} object with all of the Mime
* headers for this {@code SOAPPart} object
*/
public abstract Iterator getAllMimeHeaders();
/**
* Retrieves all <code>MimeHeader</code> objects that match a name in
* Retrieves all {@code MimeHeader} objects that match a name in
* the given array.
*
* @param names a <code>String</code> array with the name(s) of the
* @param names a {@code String} 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
* given array, returned as an {@code Iterator} object
*/
public abstract Iterator getMatchingMimeHeaders(String[] names);
/**
* Retrieves all <code>MimeHeader</code> objects whose name does
* Retrieves all {@code MimeHeader} 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
* @param names a {@code String} 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
* @return all of the MIME headers in this {@code SOAPPart} 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.
* {@code Iterator} 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. This <code>Source</code>
* Sets the content of the {@code SOAPEnvelope} object with the data
* from the given {@code Source} object. This {@code Source}
* must contain a valid SOAP document.
*
* @param source the <code>javax.xml.transform.Source</code> object with the
* @param source the {@code javax.xml.transform.Source} object with the
* data to be set
*
* @exception SOAPException if there is a problem in setting the source
@ -254,13 +253,13 @@ public abstract class SOAPPart implements org.w3c.dom.Document, Node {
public abstract void setContent(Source source) throws SOAPException;
/**
* Returns the content of the SOAPEnvelope as a JAXP <code>Source</code>
* Returns the content of the SOAPEnvelope as a JAXP {@code Source}
* object.
*
* @return the content as a <code>javax.xml.transform.Source</code> object
* @return the content as a {@code javax.xml.transform.Source} object
*
* @exception SOAPException if the implementation cannot convert
* the specified <code>Source</code> object
* the specified {@code Source} object
* @see #setContent
*/
public abstract Source getContent() throws SOAPException;

117
jaxws/src/java.xml.ws/share/classes/javax/xml/ws/Action.java
View File

@ -32,89 +32,90 @@ import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
/**
* The <code>Action</code> annotation allows explicit association of a
* WS-Addressing <code>Action</code> message addressing property with
* <code>input</code>, <code>output</code>, and
* <code>fault</code> messages of the mapped WSDL operation.
* The {@code Action} annotation allows explicit association of a
* WS-Addressing {@code Action} message addressing property with
* {@code input}, {@code output}, and
* {@code fault} messages of the mapped WSDL operation.
* <p>
* This annotation can be specified on each method of a service endpoint interface.
* For such a method, the mapped operation in the generated WSDL's
* <code>wsam:Action</code> attribute on the WSDL <code>input</code>,
* <code>output</code> and <code>fault</code> messages of the WSDL <code>operation</code>
* is based upon which attributes of the <code>Action</code> annotation have been specified.
* For the exact computation of <code>wsam:Action</code> values for the messages, refer
* {@code wsam:Action} attribute on the WSDL {@code input},
* {@code output} and {@code fault} messages of the WSDL {@code operation}
* is based upon which attributes of the {@code Action} annotation have been specified.
* For the exact computation of {@code wsam:Action} values for the messages, refer
* to the algorithm in the JAX-WS specification.
* <p>
* <b>Example 1</b>: Specify explicit values for <code>Action</code> message addressing property
* for <code>input</code> and <code>output</code> messages.
* <b>Example 1</b>: Specify explicit values for {@code Action} message addressing property
* for {@code input} and {@code output} messages.
*
* <pre>
* &#64;WebService(targetNamespace="http://example.com/numbers")
* public class AddNumbersImpl {
* <b>&#64;Action(
* input="http://example.com/inputAction",
* output="http://example.com/outputAction")</b>
* public int addNumbers(int number1, int number2) {
* return number1 + number2;
* }
* }
* {@literal @}WebService(targetNamespace="http://example.com/numbers")
* public class AddNumbersImpl {
* <b>{@literal @}Action(
* input="http://example.com/inputAction",
* output="http://example.com/outputAction")</b>
* public int addNumbers(int number1, int number2) {
* return number1 + number2;
* }
* }
* </pre>
*
* The generated WSDL looks like:
* <pre>
* &lt;definitions targetNamespace="http://example.com/numbers" ...>
* <pre> {@code
* <definitions targetNamespace="http://example.com/numbers" ...>
* ...
* &lt;portType name="AddNumbersPortType">
* &lt;operation name="AddNumbers">
* &lt;input message="tns:AddNumbersInput" name="foo"
* <portType name="AddNumbersPortType">
* <operation name="AddNumbers">
* <input message="tns:AddNumbersInput" name="foo"
* <b>wsam:Action="http://example.com/inputAction"</b>/>
* &lt;output message="tns:AddNumbersOutput" name="bar"
* <output message="tns:AddNumbersOutput" name="bar"
* <b>wsam:Action="http://example.com/outputAction"</b>/>
* &lt;/operation>
* &lt;/portType>
* </operation>
* </portType>
* ...
* &lt;/definitions>
* </definitions>
* }
* </pre>
*
* <p>
* <b>Example 2</b>: Specify explicit value for <code>Action</code> message addressing property
* for only the <code>input</code> message. The <code>wsam:Action</code> values for the
* WSDL <code>output</code> message are computed using the algorithm in the JAX-WS specification.
* <b>Example 2</b>: Specify explicit value for {@code Action} message addressing property
* for only the {@code input} message. The {@code wsam:Action} values for the
* WSDL {@code output} message are computed using the algorithm in the JAX-WS specification.
*
* <pre>
* &#64;WebService(targetNamespace="http://example.com/numbers")
* public class AddNumbersImpl {
* <b>&#64;Action(input="http://example.com/inputAction")</b>
* public int addNumbers(int number1, int number2) {
* return number1 + number2;
* }
* }
* {@literal @}WebService(targetNamespace="http://example.com/numbers")
* public class AddNumbersImpl {
* <b>{@literal @}Action(input="http://example.com/inputAction")</b>
* public int addNumbers(int number1, int number2) {
* return number1 + number2;
* }
* }
* </pre>
*
* The generated WSDL looks like:
* <pre>
* &lt;definitions targetNamespace="http://example.com/numbers" ...>
* <pre> {@code
* <definitions targetNamespace="http://example.com/numbers" ...>
* ...
* &lt;portType name="AddNumbersPortType">
* &lt;operation name="AddNumbers">
* &lt;input message="tns:AddNumbersInput" name="foo"
* <b>wsam:Action="http://example.com/inputAction"</b> />
* &lt;output message="tns:AddNumbersOutput" name="bar"
* <portType name="AddNumbersPortType">
* <operation name="AddNumbers">
* <input message="tns:AddNumbersInput" name="foo"
* <b>wsam:Action="http://example.com/inputAction"</b>/>
* <output message="tns:AddNumbersOutput" name="bar"
* <b>wsam:Action="http://example.com/numbers/AddNumbersPortType/AddNumbersResponse"</b>/>
* &lt;/operation>
* &lt;/portType>
* </operation>
* </portType>
* ...
* &lt;/definitions>
* </pre>
* </definitions>
* }</pre>
*
* It is legitimate to specify an explicit value for <code>Action</code> message addressing property for
* <code>output</code> message only. In this case, <code>wsam:Action</code> value for the
* WSDL <code>input</code> message is computed using the algorithm in the JAX-WS specification.
* It is legitimate to specify an explicit value for {@code Action} message addressing property for
* {@code output} message only. In this case, {@code wsam:Action} value for the
* WSDL {@code input} message is computed using the algorithm in the JAX-WS specification.
*
* <p>
* <b>Example 3</b>: See {@link FaultAction} annotation for an example of
* how to specify an explicit value for <code>Action</code> message addressing property for the
* <code>fault</code> message.
* how to specify an explicit value for {@code Action} message addressing property for the
* {@code fault} message.
*
* @see FaultAction
*
@ -126,21 +127,21 @@ import java.lang.annotation.Target;
@Target(ElementType.METHOD)
public @interface Action {
/**
* Explicit value of the WS-Addressing <code>Action</code> message addressing property for the <code>input</code>
* Explicit value of the WS-Addressing {@code Action} message addressing property for the {@code input}
* message of the operation.
*/
String input() default "";
/**
* Explicit value of the WS-Addressing <code>Action</code> message addressing property for the <code>output</code>
* Explicit value of the WS-Addressing {@code Action} message addressing property for the {@code output}
* message of the operation.
*/
String output() default "";
/**
* Explicit value of the WS-Addressing <code>Action</code> message addressing property for the <code>fault</code>
* Explicit value of the WS-Addressing {@code Action} message addressing property for the {@code fault}
* message(s) of the operation. Each exception that is mapped to a fault and requires an explicit WS-Addressing
* <code>Action</code> message addressing property, needs to be specified as a value in this property
* {@code Action} message addressing property, needs to be specified as a value in this property
* using {@link FaultAction} annotation.
*/
FaultAction[] fault() default { };

8
jaxws/src/java.xml.ws/share/classes/javax/xml/ws/Binding.java
View File

@ -26,7 +26,7 @@
package javax.xml.ws;
/** The <code>Binding</code> interface is the base interface
/** The {@code Binding} interface is the base interface
* for JAX-WS protocol bindings.
*
* @since 1.6, JAX-WS 2.0
@ -35,10 +35,10 @@ public interface Binding {
/**
* Gets a copy of the handler chain for a protocol binding instance.
* If the returned chain is modified a call to <code>setHandlerChain</code>
* If the returned chain is modified a call to {@code setHandlerChain}
* is required to configure the binding instance with the new chain.
*
* @return java.util.List&lt;Handler> Handler chain
* @return {@code java.util.List<Handler>} Handler chain
*/
public java.util.List<javax.xml.ws.handler.Handler> getHandlerChain();
@ -59,7 +59,7 @@ public interface Binding {
* Get the URI for this binding instance.
*
* @return String The binding identifier for the port.
* Never returns <code>null</code>
* Never returns {@code null}
*
* @since 1.6, JAX-WS 2.1
*/

30
jaxws/src/java.xml.ws/share/classes/javax/xml/ws/Dispatch.java
View File

@ -27,10 +27,10 @@ package javax.xml.ws;
import java.util.concurrent.Future;
/** The <code>Dispatch</code> interface provides support
/** The {@code Dispatch} interface provides support
* for the dynamic invocation of a service endpoint operations. The
* <code>javax.xml.ws.Service</code>
* class acts as a factory for the creation of <code>Dispatch</code>
* {@code javax.xml.ws.Service}
* class acts as a factory for the creation of {@code Dispatch}
* instances.
*
* @since 1.6, JAX-WS 2.0
@ -39,7 +39,7 @@ public interface Dispatch<T> extends BindingProvider {
/** Invoke a service operation synchronously.
*
* The client is responsible for ensuring that the <code>msg</code> object
* The client is responsible for ensuring that the {@code msg} object
* when marshalled is formed according to the requirements of the protocol
* binding in use.
*
@ -50,16 +50,16 @@ public interface Dispatch<T> extends BindingProvider {
* @throws WebServiceException If a fault occurs during communication with
* the service
* @throws WebServiceException If there is any error in the configuration of
* the <code>Dispatch</code> instance
* the {@code Dispatch} instance
**/
public T invoke(T msg);
/** Invoke a service operation asynchronously. The
* method returns without waiting for the response to the operation
* invocation, the results of the operation are obtained by polling the
* returned <code>Response</code>.
* returned {@code Response}.
* <p>
* The client is responsible for ensuring that the <code>msg</code> object
* The client is responsible for ensuring that the {@code msg} object
* when marshalled is formed according to the requirements of the protocol
* binding in use.
*
@ -68,16 +68,16 @@ public interface Dispatch<T> extends BindingProvider {
* @return The response message or message payload to the
* operation invocation.
* @throws WebServiceException If there is any error in the configuration of
* the <code>Dispatch</code> instance
* the {@code Dispatch} instance
**/
public Response<T> invokeAsync(T msg);
/** Invoke a service operation asynchronously. The
* method returns without waiting for the response to the operation
* invocation, the results of the operation are communicated to the client
* via the passed in <code>handler</code>.
* via the passed in {@code handler}.
* <p>
* The client is responsible for ensuring that the <code>msg</code> object
* The client is responsible for ensuring that the {@code msg} object
* when marshalled is formed according to the requirements of the protocol
* binding in use.
*
@ -85,13 +85,13 @@ public interface Dispatch<T> extends BindingProvider {
* the message used to invoke the operation.
* @param handler The handler object that will receive the
* response to the operation invocation.
* @return A <code>Future</code> object that may be used to check the status
* @return A {@code Future} object that may be used to check the status
* of the operation invocation. This object MUST NOT be used to try to
* obtain the results of the operation - the object returned from
* <code>Future&lt;?>.get()</code> is implementation dependent
* {@code Future<?>.get()} is implementation dependent
* and any use of it will result in non-portable behaviour.
* @throws WebServiceException If there is any error in the configuration of
* the <code>Dispatch</code> instance
* the {@code Dispatch} instance
**/
public Future<?> invokeAsync(T msg, AsyncHandler<T> handler);
@ -102,14 +102,14 @@ public interface Dispatch<T> extends BindingProvider {
* the protocol in use is SOAP/HTTP, this method MUST block until
* an HTTP response code has been received or an error occurs.
* <p>
* The client is responsible for ensuring that the <code>msg</code> object
* The client is responsible for ensuring that the {@code msg} object
* when marshalled is formed according to the requirements of the protocol
* binding in use.
*
* @param msg An object that will form the message or payload of
* the message used to invoke the operation.
* @throws WebServiceException If there is any error in the configuration of
* the <code>Dispatch</code> instance or if an error occurs during the
* the {@code Dispatch} instance or if an error occurs during the
* invocation.
**/
public void invokeOneWay(T msg);

110
jaxws/src/java.xml.ws/share/classes/javax/xml/ws/FaultAction.java
View File

@ -32,28 +32,28 @@ import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
/**
* The <code>FaultAction</code> annotation is used inside an {@link Action}
* The {@code FaultAction} annotation is used inside an {@link Action}
* annotation to allow an explicit association of a WS-Addressing
* <code>Action</code> message addressing property with the <code>fault</code>
* {@code Action} message addressing property with the {@code fault}
* messages of the WSDL operation mapped from the exception class.
* <p>
* The <code>wsam:Action</code> attribute value in the <code>fault</code>
* message in the generated WSDL operation mapped for <code>className</code>
* class is equal to the corresponding value in the <code>FaultAction</code>.
* For the exact computation of <code>wsam:Action</code> values for the
* The {@code wsam:Action} attribute value in the {@code fault}
* message in the generated WSDL operation mapped for {@code className}
* class is equal to the corresponding value in the {@code FaultAction}.
* For the exact computation of {@code wsam:Action} values for the
* fault messages, refer to the algorithm in the JAX-WS specification.
*
* <p>
* <b>Example 1</b>: Specify explicit values for <code>Action</code> message addressing
* property for the <code>input</code>, <code>output</code> and <code>fault</code> message
* <b>Example 1</b>: Specify explicit values for {@code Action} message addressing
* property for the {@code input}, {@code output} and {@code fault} message
* if the Java method throws only one service specific exception.
*
* <pre>
* &#64;WebService(targetNamespace="http://example.com/numbers")
* public class AddNumbersImpl {
* &#64;Action(
* {@literal @}WebService(targetNamespace="http://example.com/numbers")
* public class AddNumbersImpl {
* {@literal @}Action(
* fault = {
* <b>&#64;FaultAction(className=AddNumbersException.class, value="http://example.com/faultAction")</b>
* <b>{@literal @}FaultAction(className=AddNumbersException.class, value="http://example.com/faultAction")</b>
* })
* public int addNumbers(int number1, int number2)
* throws AddNumbersException {
@ -64,86 +64,86 @@ import java.lang.annotation.Target;
*
* The generated WSDL looks like:
*
* <pre>
* &lt;definitions targetNamespace="http://example.com/numbers" ...>
* <pre> {@code
* <definitions targetNamespace="http://example.com/numbers" ...>
* ...
* &lt;portType name="AddNumbersPortType">
* &lt;operation name="AddNumbers">
* <portType name="AddNumbersPortType">
* <operation name="AddNumbers">
* ...
* &lt;fault message="tns:AddNumbersException" name="AddNumbersException"
* <b>wsam:Action="http://example.com/faultAction"</b>/>
* &lt;/operation>
* &lt;/portType>
* <fault message="tns:AddNumbersException" name="AddNumbersException"}
* <b>wsam:Action="http://example.com/faultAction"</b>{@code />
* </operation>
* </portType>
* ...
* &lt;/definitions>
* </definitions> }
* </pre>
*
* <p>
* Example 2: Here is an example that shows if the explicit value for <code>Action</code>
* Example 2: Here is an example that shows if the explicit value for {@code Action}
* message addressing property for the service specific exception is not present.
*
* <pre>
* &#64;WebService(targetNamespace="http://example.com/numbers")
* public class AddNumbersImpl {
* {@literal @}WebService(targetNamespace="http://example.com/numbers")
* public class AddNumbersImpl {
* public int addNumbers(int number1, int number2)
* throws AddNumbersException {
* return number1 + number2;
* }
* }
* }
* </pre>
*
* The generated WSDL looks like:
*
* <pre>
* &lt;definitions targetNamespace="http://example.com/numbers" ...>
* <pre>{@code
* <definitions targetNamespace="http://example.com/numbers" ...>
* ...
* &lt;portType name="AddNumbersPortType">
* &lt;operation name="AddNumbers">
* <portType name="AddNumbersPortType">
* <operation name="AddNumbers">
* ...
* &lt;fault message="tns:addNumbersFault" name="InvalidNumbers"
* <b>wsam:Action="http://example.com/numbers/AddNumbersPortType/AddNumbers/Fault/AddNumbersException"</b>/>
* &lt;/operation>
* &lt;/portType>
* <fault message="tns:addNumbersFault" name="InvalidNumbers"}
* <b>wsam:Action="http://example.com/numbers/AddNumbersPortType/AddNumbers/Fault/AddNumbersException"</b>{@code />
* </operation>
* </portType>
* ...
* &lt;/definitions>
* </pre>
* </definitions>
* }</pre>
*
* <p>
* Example 3: Here is an example that shows how to specify explicit values for <code>Action</code>
* Example 3: Here is an example that shows how to specify explicit values for {@code Action}
* message addressing property if the Java method throws more than one service specific exception.
*
* <pre>
* &#64;WebService(targetNamespace="http://example.com/numbers")
* public class AddNumbersImpl {
* &#64;Action(
* {@literal @}WebService(targetNamespace="http://example.com/numbers")
* public class AddNumbersImpl {
* {@literal @}Action(
* fault = {
* <b>&#64;FaultAction(className=AddNumbersException.class, value="http://example.com/addFaultAction"),
* &#64;FaultAction(className=TooBigNumbersException.class, value="http://example.com/toobigFaultAction")</b>
* <b>{@literal @}FaultAction(className=AddNumbersException.class, value="http://example.com/addFaultAction"),
* {@literal @}FaultAction(className=TooBigNumbersException.class, value="http://example.com/toobigFaultAction")</b>
* })
* public int addNumbers(int number1, int number2)
* throws AddNumbersException, TooBigNumbersException {
* return number1 + number2;
* }
* }
* }
* </pre>
*
* The generated WSDL looks like:
*
* <pre>
* &lt;definitions targetNamespace="http://example.com/numbers" ...>
* <pre> {@code
* <definitions targetNamespace="http://example.com/numbers" ...>
* ...
* &lt;portType name="AddNumbersPortType">
* &lt;operation name="AddNumbers">
* <portType name="AddNumbersPortType">
* <operation name="AddNumbers">
* ...
* &lt;fault message="tns:addNumbersFault" name="AddNumbersException"
* <b>wsam:Action="http://example.com/addFaultAction"</b>/>
* &lt;fault message="tns:tooBigNumbersFault" name="TooBigNumbersException"
* <b>wsam:Action="http://example.com/toobigFaultAction"</b>/>
* &lt;/operation>
* &lt;/portType>
* <fault message="tns:addNumbersFault" name="AddNumbersException"}
* <b>wsam:Action="http://example.com/addFaultAction"</b>{@code />
* <fault message="tns:tooBigNumbersFault" name="TooBigNumbersException"}
* <b>wsam:Action="http://example.com/toobigFaultAction"</b>{@code />
* </operation>
* </portType>
* ...
* &lt;/definitions>
* </pre>
* </definitions>
* }</pre>
*
* @since 1.6, JAX-WS 2.1
*/
@ -158,7 +158,7 @@ public @interface FaultAction {
Class<? extends Exception> className();
/**
* Value of WS-Addressing <code>Action</code> message addressing property for the exception
* Value of WS-Addressing {@code Action} message addressing property for the exception
*/
String value() default "";
}

20
jaxws/src/java.xml.ws/share/classes/javax/xml/ws/WebServicePermission.java
View File

@ -35,16 +35,14 @@ import java.security.BasicPermission;
* with them.
* <p>
* The following permission target name is defined:
* <p>
* <dl>
* <dt>publishEndpoint
* </dl>
* The {@code publishEndpoint} permission allows publishing a
* web service endpoint using the {@code publish} methods
* defined by the {@code javax.xml.ws.Endpoint} class.
* <p>
* The <code>publishEndpoint</code> permission allows publishing a
* web service endpoint using the <code>publish</code> methods
* defined by the <code>javax.xml.ws.Endpoint</code> class.
* <p>
* Granting <code>publishEndpoint</code> allows the application to be
* Granting {@code publishEndpoint} allows the application to be
* exposed as a network service. Depending on the security of the runtime and
* the security of the application, this may introduce a security hole that
* is remotely exploitable.
@ -64,7 +62,7 @@ public final class WebServicePermission extends BasicPermission {
/**
* Creates a new permission with the specified name.
*
* @param name the name of the <code>WebServicePermission</code>
* @param name the name of the {@code WebServicePermission}
*/
public WebServicePermission(String name) {
super(name);
@ -73,11 +71,11 @@ public final class WebServicePermission extends BasicPermission {
/**
* Creates a new permission with the specified name and actions.
*
* The <code>actions</code> parameter is currently unused and
* it should be <code>null</code>.
* The {@code actions} parameter is currently unused and
* it should be {@code null}.
*
* @param name the name of the <code>WebServicePermission</code>
* @param actions should be <code>null</code>
* @param name the name of the {@code WebServicePermission}
* @param actions should be {@code null}
*/
public WebServicePermission(String name, String actions) {
super(name, actions);

14
jaxws/src/java.xml.ws/share/classes/javax/xml/ws/handler/HandlerResolver.java
View File

@ -26,15 +26,15 @@
package javax.xml.ws.handler;
/**
* <code>HandlerResolver</code> is an interface implemented
* {@code HandlerResolver} is an interface implemented
* by an application to get control over the handler chain
* set on proxy/dispatch objects at the time of their creation.
* <p>
* A <code>HandlerResolver</code> may be set on a <code>Service</code>
* using the <code>setHandlerResolver</code> method.
* <p>
* When the runtime invokes a <code>HandlerResolver</code>, it will
* pass it a <code>PortInfo</code> object containing information
* A {@code HandlerResolver} may be set on a {@code Service}
* using the {@code setHandlerResolver} method.
* <p>
* When the runtime invokes a {@code HandlerResolver}, it will
* pass it a {@code PortInfo} object containing information
* about the port that the proxy/dispatch object will be accessing.
*
* @see javax.xml.ws.Service#setHandlerResolver
@ -47,7 +47,7 @@ public interface HandlerResolver {
* Gets the handler chain for the specified port.
*
* @param portInfo Contains information about the port being accessed.
* @return java.util.List&lt;Handler> chain
* @return {@code java.util.List<Handler>} chain
**/
public java.util.List<Handler> getHandlerChain(PortInfo portInfo);
}

28
jaxws/src/java.xml.ws/share/classes/javax/xml/ws/handler/MessageContext.java
View File

@ -27,12 +27,12 @@ package javax.xml.ws.handler;
import java.util.Map;
/**
* The interface <code>MessageContext</code> abstracts the message
* context that is processed by a handler in the <code>handle</code>
* The interface {@code MessageContext} abstracts the message
* context that is processed by a handler in the {@code handle}
* method.
*
* <p>The <code>MessageContext</code> interface provides methods to
* manage a property set. <code>MessageContext</code> properties
* <p>The {@code MessageContext} interface provides methods to
* manage a property set. {@code MessageContext} properties
* enable handlers in a handler chain to share processing related
* state.
*
@ -41,8 +41,8 @@ import java.util.Map;
public interface MessageContext extends Map<String, Object> {
/**
* Standard property: message direction, <code>true</code> for
* outbound messages, <code>false</code> for inbound.
* Standard property: message direction, {@code true} for
* outbound messages, {@code false} for inbound.
* <p>Type: boolean
*/
public static final String MESSAGE_OUTBOUND_PROPERTY =
@ -51,7 +51,7 @@ public interface MessageContext extends Map<String, Object> {
/**
* Standard property: Map of attachments to a message for the inbound
* message, key is the MIME Content-ID, value is a DataHandler.
* <p>Type: java.util.Map&lt;String,DataHandler>
* <p>Type: {@code java.util.Map<String, DataHandler>}
*/
public static final String INBOUND_MESSAGE_ATTACHMENTS =
"javax.xml.ws.binding.attachments.inbound";
@ -59,7 +59,7 @@ public interface MessageContext extends Map<String, Object> {
/**
* Standard property: Map of attachments to a message for the outbound
* message, key is the MIME Content-ID, value is a DataHandler.
* <p>Type: java.util.Map&lt;String,DataHandler>
* <p>Type: {@code java.util.Map<String, DataHandler>}
*/
public static final String OUTBOUND_MESSAGE_ATTACHMENTS =
"javax.xml.ws.binding.attachments.outbound";
@ -108,14 +108,14 @@ public interface MessageContext extends Map<String, Object> {
/**
* Standard property: HTTP request headers.
* <p>Type: java.util.Map&lt;java.lang.String, java.util.List&lt;java.lang.String>>
* <p>Type: {@code java.util.Map<java.lang.String, java.util.List<java.lang.String>>}
*/
public static final String HTTP_REQUEST_HEADERS =
"javax.xml.ws.http.request.headers";
/**
* Standard property: HTTP response headers.
* <p>Type: java.util.Map&lt;java.lang.String, java.util.List&lt;java.lang.String>>
* <p>Type: {@code java.util.Map<java.lang.String, java.util.List<java.lang.String>>}
*/
public static final String HTTP_RESPONSE_HEADERS =
"javax.xml.ws.http.response.headers";
@ -166,7 +166,7 @@ public interface MessageContext extends Map<String, Object> {
* Standard property: WS Addressing Reference Parameters.
* The list MUST include all SOAP headers marked with the
* wsa:IsReferenceParameter="true" attribute.
* <p>Type: List&lt;Element>
* <p>Type: {@code List<Element>}
*
* @since 1.6, JAX-WS 2.1
*/
@ -174,10 +174,10 @@ public interface MessageContext extends Map<String, Object> {
"javax.xml.ws.reference.parameters";
/**
* Property scope. Properties scoped as <code>APPLICATION</code> are
* Property scope. Properties scoped as {@code APPLICATION} are
* visible to handlers,
* client applications and service endpoints; properties scoped as
* <code>HANDLER</code>
* {@code HANDLER}
* are only normally visible to handlers.
*/
public enum Scope {APPLICATION, HANDLER};
@ -186,7 +186,7 @@ public interface MessageContext extends Map<String, Object> {
* Sets the scope of a property.
*
* @param name Name of the property associated with the
* <code>MessageContext</code>
* {@code MessageContext}
* @param scope Desired scope of the property
* @throws java.lang.IllegalArgumentException if an illegal
* property name is specified

59
jaxws/src/java.xml.ws/share/classes/javax/xml/ws/soap/AddressingFeature.java
View File

@ -52,10 +52,10 @@ import javax.xml.ws.Service;
* receiver.
* </ul>
* <p>
* If the feature is enabled, the <code>required</code> property determines
* If the feature is enabled, the {@code required} property determines
* whether the endpoint requires WS-Addressing. If it is set true,
* WS-Addressing headers MUST be present on incoming and outgoing messages.
* By default the <code>required</code> property is <code>false</code>.
* By default the {@code required} property is {@code false}.
*
* <p>
* If the web service developer has not explicitly enabled this feature,
@ -75,31 +75,31 @@ import javax.xml.ws.Service;
*
* <p>
* <b>Example 1: </b>Possible Policy Assertion in the generated WSDL for
* <code>&#64;Addressing</code>
* <pre>
* &lt;wsam:Addressing wsp:Optional="true">
* &lt;wsp:Policy/>
* &lt;/wsam:Addressing>
* {@code @Addressing}
* <pre> {@code
* <wsam:Addressing wsp:Optional="true">
* <wsp:Policy/>
* </wsam:Addressing> }
* </pre>
*
* <p>
* <b>Example 2: </b>Possible Policy Assertion in the generated WSDL for
* <code>&#64;Addressing(required=true)</code>
* <pre>
* &lt;wsam:Addressing>
* &lt;wsp:Policy/>
* &lt;/wsam:Addressing>
* {@code @Addressing(required=true)}
* <pre> {@code
* <wsam:Addressing>
* <wsp:Policy/>
* </wsam:Addressing> }
* </pre>
*
* <p>
* <b>Example 3: </b>Possible Policy Assertion in the generated WSDL for
* <code>&#64;Addressing(required=true, responses=Responses.ANONYMOUS)</code>
* <pre>
* &lt;wsam:Addressing>
* &lt;wsp:Policy>
* &lt;wsam:AnonymousResponses/>
* &lt;/wsp:Policy>
* &lt;/wsam:Addressing>
* {@code @Addressing(required=true, responses=Responses.ANONYMOUS)}
* <pre> {@code
* <wsam:Addressing>
* <wsp:Policy>
* <wsam:AnonymousResponses/>
* </wsp:Policy>
* </wsam:Addressing> }
* </pre>
*
* <p>
@ -181,7 +181,7 @@ public final class AddressingFeature extends WebServiceFeature {
private final Responses responses;
/**
* Creates and configures an <code>AddressingFeature</code> with the
* Creates and configures an {@code AddressingFeature} with the
* use of addressing requirements. The created feature enables
* ws-addressing i.e. supports ws-addressing but doesn't require
* its use. It is also configured to accept all the response types.
@ -191,8 +191,8 @@ public final class AddressingFeature extends WebServiceFeature {
}
/**
* Creates and configures an <code>AddressingFeature</code> with the
* use of addressing requirements. If <code>enabled</code> is true,
* Creates and configures an {@code AddressingFeature} with the
* use of addressing requirements. If {@code enabled} is true,
* it enables ws-addressing i.e. supports ws-addressing but doesn't
* require its use. It also configures to accept all the response types.
*
@ -204,9 +204,9 @@ public final class AddressingFeature extends WebServiceFeature {
}
/**
* Creates and configures an <code>AddressingFeature</code> with the
* use of addressing requirements. If <code>enabled</code> and
* <code>required</code> are true, it enables ws-addressing and
* Creates and configures an {@code AddressingFeature} with the
* use of addressing requirements. If {@code enabled} and
* {@code required} are true, it enables ws-addressing and
* requires its use. It also configures to accept all the response types.
*
* @param enabled true enables ws-addressing i.e.ws-addressing
@ -218,11 +218,11 @@ public final class AddressingFeature extends WebServiceFeature {
}
/**
* Creates and configures an <code>AddressingFeature</code> with the
* use of addressing requirements. If <code>enabled</code> and
* <code>required</code> are true, it enables ws-addressing and
* Creates and configures an {@code AddressingFeature} with the
* use of addressing requirements. If {@code enabled} and
* {@code required} are true, it enables ws-addressing and
* requires its use. Also, the response types can be configured using
* <code>responses</code> parameter.
* {@code responses} parameter.
*
* @param enabled true enables ws-addressing i.e.ws-addressing
* is supported but doesn't require its use
@ -260,7 +260,6 @@ public final class AddressingFeature extends WebServiceFeature {
* requires the use of anonymous responses, or non-anonymous responses,
* or all responses.
*
* <p>
* @return {@link Responses#ALL} when endpoint supports all types of
* responses,
* {@link Responses#ANONYMOUS} when endpoint requires the use of

10
jaxws/src/java.xml.ws/share/classes/javax/xml/ws/soap/MTOM.java
View File

@ -40,14 +40,14 @@ import javax.xml.ws.WebServiceProvider;
* web service.
* <p>
* This annotation MUST only be used in conjunction the
* <code>javax.jws.WebService</code>, {@link WebServiceProvider},
* {@code javax.jws.WebService}, {@link WebServiceProvider},
* {@link WebServiceRef} annotations.
* When used with the <code>javax.jws.WebService</code> annotation this
* When used with the {@code javax.jws.WebService} annotation this
* annotation MUST only be used on the service endpoint implementation
* class.
* When used with a <code>WebServiceRef</code> annotation, this annotation
* When used with a {@code WebServiceRef} annotation, this annotation
* MUST only be used when a proxy instance is created. The injected SEI
* proxy, and endpoint MUST honor the values of the <code>MTOM</code>
* proxy, and endpoint MUST honor the values of the {@code MTOM}
* annotation.
* <p>
*
@ -69,7 +69,7 @@ public @interface MTOM {
/**
* Property for MTOM threshold value. When MTOM is enabled, binary data above this
* size in bytes will be XOP encoded or sent as attachment. The value of this property
* MUST always be >= 0. Default value is 0.
* MUST always be {@literal >=} 0. Default value is 0.
*/
int threshold() default 0;
}

14
jaxws/src/java.xml.ws/share/classes/javax/xml/ws/soap/MTOMFeature.java
View File

@ -67,14 +67,14 @@ public final class MTOMFeature extends WebServiceFeature {
* Property for MTOM threshold value. This property serves as a hint when
* MTOM is enabled, binary data above this size in bytes SHOULD be sent
* as attachment.
* The value of this property MUST always be >= 0. Default value is 0.
* The value of this property MUST always be {@literal >=} 0. Default value is 0.
*/
// should be changed to private final, keeping original modifier to keep backwards compatibility
protected int threshold;
/**
* Create an <code>MTOMFeature</code>.
* Create an {@code MTOMFeature}.
* The instance created will be enabled.
*/
public MTOMFeature() {
@ -83,7 +83,7 @@ public final class MTOMFeature extends WebServiceFeature {
}
/**
* Creates an <code>MTOMFeature</code>.
* Creates a {@code MTOMFeature}.
*
* @param enabled specifies if this feature should be enabled or not
*/
@ -94,13 +94,13 @@ public final class MTOMFeature extends WebServiceFeature {
/**
* Creates an <code>MTOMFeature</code>.
* Creates a {@code MTOMFeature}.
* The instance created will be enabled.
*
* @param threshold the size in bytes that binary data SHOULD be before
* being sent as an attachment.
*
* @throws WebServiceException if threshold is < 0
* @throws WebServiceException if threshold is {@literal <} 0
*/
public MTOMFeature(int threshold) {
if (threshold < 0)
@ -110,13 +110,13 @@ public final class MTOMFeature extends WebServiceFeature {
}
/**
* Creates an <code>MTOMFeature</code>.
* Creates a {@code MTOMFeature}.
*
* @param enabled specifies if this feature should be enabled or not
* @param threshold the size in bytes that binary data SHOULD be before
* being sent as an attachment.
*
* @throws WebServiceException if threshold is < 0
* @throws WebServiceException if threshold is {@literal <} 0
*/
public MTOMFeature(boolean enabled, int threshold) {
if (threshold < 0)

14
jaxws/src/java.xml.ws/share/classes/javax/xml/ws/soap/SOAPBinding.java
View File

@ -31,7 +31,7 @@ import javax.xml.ws.Binding;
import javax.xml.soap.SOAPFactory;
import javax.xml.soap.MessageFactory;
/** The <code>SOAPBinding</code> interface is an abstraction for
/** The {@code SOAPBinding} interface is an abstraction for
* the SOAP binding.
*
* @since 1.6, JAX-WS 2.0
@ -63,7 +63,7 @@ public interface SOAPBinding extends Binding {
/** Gets the roles played by the SOAP binding instance.
*
* @return Set&lt;String> The set of roles played by the binding instance.
* @return {@code Set<String>} The set of roles played by the binding instance.
**/
public Set<String> getRoles();
@ -76,9 +76,9 @@ public interface SOAPBinding extends Binding {
public void setRoles(Set<String> roles);
/**
* Returns <code>true</code> if the use of MTOM is enabled.
* Returns {@code true} if the use of MTOM is enabled.
*
* @return <code>true</code> if and only if the use of MTOM is enabled.
* @return {@code true} if and only if the use of MTOM is enabled.
**/
public boolean isMTOMEnabled();
@ -86,7 +86,7 @@ public interface SOAPBinding extends Binding {
/**
* Enables or disables use of MTOM.
*
* @param flag A <code>boolean</code> specifying whether the use of MTOM should
* @param flag A {@code boolean} specifying whether the use of MTOM should
* be enabled or disabled.
* @throws WebServiceException If the specified setting is not supported
* by this binding instance.
@ -95,14 +95,14 @@ public interface SOAPBinding extends Binding {
public void setMTOMEnabled(boolean flag);
/**
* Gets the SAAJ <code>SOAPFactory</code> instance used by this SOAP binding.
* Gets the SAAJ {@code SOAPFactory} instance used by this SOAP binding.
*
* @return SOAPFactory instance used by this SOAP binding.
**/
public SOAPFactory getSOAPFactory();
/**
* Gets the SAAJ <code>MessageFactory</code> instance used by this SOAP binding.
* Gets the SAAJ {@code MessageFactory} instance used by this SOAP binding.
*
* @return MessageFactory instance used by this SOAP binding.
**/

210
jaxws/src/java.xml.ws/share/classes/javax/xml/ws/spi/Provider.java
View File

@ -37,9 +37,8 @@ import javax.xml.ws.wsaddressing.W3CEndpointReference;
import org.w3c.dom.Element;
/**
* Service provider for <code>ServiceDelegate</code> and
* <code>Endpoint</code> objects.
* <p>
* Service provider for {@code ServiceDelegate} and
* {@code Endpoint} objects.
*
* @since 1.6, JAX-WS 2.0
*/
@ -47,14 +46,14 @@ public abstract class Provider {
/**
* A constant representing the property used to lookup the
* name of a <code>Provider</code> implementation
* name of a {@code Provider} implementation
* class.
*/
static public final String JAXWSPROVIDER_PROPERTY = "javax.xml.ws.spi.Provider";
/**
* A constant representing the name of the default
* <code>Provider</code> implementation class.
* {@code Provider} implementation class.
**/
// Using two strings so that package renaming doesn't change it
static final String DEFAULT_JAXWSPROVIDER
@ -72,22 +71,21 @@ public abstract class Provider {
* <p>
* The algorithm used to locate the provider subclass to use consists
* of the following steps:
* <p>
* <ul>
* <li>
* If a resource with the name of
* <code>META-INF/services/javax.xml.ws.spi.Provider</code>
* {@code META-INF/services/javax.xml.ws.spi.Provider}
* exists, then its first line, if present, is used as the UTF-8 encoded
* name of the implementation class.
* </li>
* <li>
* If the $java.home/lib/jaxws.properties file exists and it is readable by
* the <code>java.util.Properties.load(InputStream)</code> method and it contains
* an entry whose key is <code>javax.xml.ws.spi.Provider</code>, then the value of
* the {@code java.util.Properties.load(InputStream)} method and it contains
* an entry whose key is {@code javax.xml.ws.spi.Provider}, then the value of
* that entry is used as the name of the implementation class.
* </li>
* <li>
* If a system property with the name <code>javax.xml.ws.spi.Provider</code>
* If a system property with the name {@code javax.xml.ws.spi.Provider}
* is defined, then its value is used as the name of the implementation class.
* </li>
* <li>
@ -136,12 +134,12 @@ public abstract class Provider {
/**
* Creates a service delegate object.
* <p>
*
* @param wsdlDocumentLocation A URL pointing to the WSDL document
* for the service, or <code>null</code> if there isn't one.
* for the service, or {@code null} if there isn't one.
* @param serviceName The qualified name of the service.
* @param serviceClass The service class, which MUST be either
* <code>javax.xml.ws.Service</code> or a subclass thereof.
* {@code javax.xml.ws.Service} or a subclass thereof.
* @return The newly created service delegate.
*/
public abstract ServiceDelegate createServiceDelegate(
@ -150,12 +148,12 @@ public abstract class Provider {
/**
* Creates a service delegate object.
* <p>
*
* @param wsdlDocumentLocation A URL pointing to the WSDL document
* for the service, or <code>null</code> if there isn't one.
* for the service, or {@code null} if there isn't one.
* @param serviceName The qualified name of the service.
* @param serviceClass The service class, which MUST be either
* <code>javax.xml.ws.Service</code> or a subclass thereof.
* {@code javax.xml.ws.Service} or a subclass thereof.
* @param features Web Service features that must be configured on
* the service. If the provider doesn't understand a feature,
* it must throw a WebServiceException.
@ -205,18 +203,18 @@ public abstract class Provider {
/**
* read an EndpointReference from the infoset contained in
* <code>eprInfoset</code>.
* {@code eprInfoset}.
*
* @param eprInfoset infoset for EndpointReference
*
* @return the <code>EndpointReference</code> unmarshalled from
* <code>eprInfoset</code>. This method never returns <code>null</code>.
* @return the {@code EndpointReference} unmarshalled from
* {@code eprInfoset}. This method never returns {@code null}.
*
* @throws WebServiceException If there is an error creating the
* <code>EndpointReference</code> from the specified <code>eprInfoset</code>.
* {@code EndpointReference} from the specified {@code eprInfoset}.
*
* @throws NullPointerException If the <code>null</code>
* <code>eprInfoset</code> value is given.
* @throws NullPointerException If the {@code null}
* {@code eprInfoset} value is given.
*
* @since 1.6, JAX-WS 2.1
**/
@ -226,31 +224,31 @@ public abstract class Provider {
/**
* The getPort method returns a proxy. If there
* are any reference parameters in the
* <code>endpointReference</code>, then those reference
* {@code endpointReference}, then those reference
* parameters MUST appear as SOAP headers, indicating them to be
* reference parameters, on all messages sent to the endpoint.
* The parameter <code>serviceEndpointInterface</code> specifies
* The parameter {@code serviceEndpointInterface} specifies
* the service endpoint interface that is supported by the
* returned proxy.
* The parameter <code>endpointReference</code> specifies the
* The parameter {@code endpointReference} specifies the
* endpoint that will be invoked by the returned proxy.
* In the implementation of this method, the JAX-WS
* runtime system takes the responsibility of selecting a protocol
* binding (and a port) and configuring the proxy accordingly from
* the WSDL metadata of the
* <code>serviceEndpointInterface</code> and the <code>EndpointReference</code>.
* {@code serviceEndpointInterface} and the {@code EndpointReference}.
* For this method
* to successfully return a proxy, WSDL metadata MUST be available and the
* <code>endpointReference</code> MUST contain an implementation understood
* <code>serviceName</code> metadata.
* {@code endpointReference} MUST contain an implementation understood
* {@code serviceName} metadata.
*
*
* @param endpointReference the EndpointReference that will
* be invoked by the returned proxy.
* @param serviceEndpointInterface Service endpoint interface
* @param features A list of WebServiceFeatures to configure on the
* proxy. Supported features not in the <code>features
* </code> parameter will have their default values.
* proxy. Supported features not in the {@code features
* } parameter will have their default values.
* @return Object Proxy instance that supports the
* specified service endpoint interface
* @throws WebServiceException
@ -260,10 +258,10 @@ public abstract class Provider {
* <LI>If there is any missing WSDL metadata
* as required by this method}
* <LI>If this
* <code>endpointReference</code>
* {@code endpointReference}
* is illegal
* <LI>If an illegal
* <code>serviceEndpointInterface</code>
* {@code serviceEndpointInterface}
* is specified
* <LI>If a feature is enabled that is not compatible with
* this port or is unsupported.
@ -278,60 +276,60 @@ public abstract class Provider {
WebServiceFeature... features);
/**
* Factory method to create a <code>W3CEndpointReference</code>.
* Factory method to create a {@code W3CEndpointReference}.
*
* <p>
* This method can be used to create a <code>W3CEndpointReference</code>
* for any endpoint by specifying the <code>address</code> property along
* This method can be used to create a {@code W3CEndpointReference}
* for any endpoint by specifying the {@code address} property along
* with any other desired properties. This method
* can also be used to create a <code>W3CEndpointReference</code> for
* can also be used to create a {@code W3CEndpointReference} for
* an endpoint that is published by the same Java EE application.
* To do so the <code>address</code> property can be provided or this
* method can automatically determine the <code>address</code> of
* To do so the {@code address} property can be provided or this
* method can automatically determine the {@code address} of
* an endpoint that is published by the same Java EE application and is
* identified by the <code>serviceName</code> and
* <code>portName</code> propeties. If the <code>address</code> is
* <code>null</code> and the <code>serviceName</code> and
* <code>portName</code> do not identify an endpoint published by the
* identified by the {@code serviceName} and
* {@code portName} propeties. If the {@code address} is
* {@code null} and the {@code serviceName} and
* {@code portName} do not identify an endpoint published by the
* same Java EE application, a
* <code>javax.lang.IllegalStateException</code> MUST be thrown.
* {@code javax.lang.IllegalStateException} MUST be thrown.
*
* @param address Specifies the address of the target endpoint
* @param serviceName Qualified name of the service in the WSDL.
* @param portName Qualified name of the endpoint in the WSDL.
* @param metadata A list of elements that should be added to the
* <code>W3CEndpointReference</code> instances <code>wsa:metadata</code>
* {@code W3CEndpointReference} instances {@code wsa:metadata}
* element.
* @param wsdlDocumentLocation URL for the WSDL document location for
* the service.
* @param referenceParameters Reference parameters to be associated
* with the returned <code>EndpointReference</code> instance.
* with the returned {@code EndpointReference} instance.
*
* @return the <code>W3CEndpointReference</code> created from
* <code>serviceName</code>, <code>portName</code>,
* <code>metadata</code>, <code>wsdlDocumentLocation</code>
* and <code>referenceParameters</code>. This method
* never returns <code>null</code>.
* @return the {@code W3CEndpointReference} created from
* {@code serviceName}, {@code portName},
* {@code metadata}, {@code wsdlDocumentLocation}
* and {@code referenceParameters}. This method
* never returns {@code null}.
*
* @throws java.lang.IllegalStateException
* <ul>
* <li>If the <code>address</code>, <code>serviceName</code> and
* <code>portName</code> are all <code>null</code>.
* <li>If the <code>serviceName</code> service is <code>null</code> and the
* <code>portName</code> is NOT <code>null</code>.
* <li>If the <code>address</code> property is <code>null</code> and
* the <code>serviceName</code> and <code>portName</code> do not
* <li>If the {@code address}, {@code serviceName} and
* {@code portName} are all {@code null}.
* <li>If the {@code serviceName} service is {@code null} and the
* {@code portName} is NOT {@code null}.
* <li>If the {@code address} property is {@code null} and
* the {@code serviceName} and {@code portName} do not
* specify a valid endpoint published by the same Java EE
* application.
* <li>If the <code>serviceName</code>is NOT <code>null</code>
* <li>If the {@code serviceName}is NOT {@code null}
* and is not present in the specified WSDL.
* <li>If the <code>portName</code> port is not <code>null</code> and it
* is not present in <code>serviceName</code> service in the WSDL.
* <li>If the <code>wsdlDocumentLocation</code> is NOT <code>null</code>
* <li>If the {@code portName} port is not {@code null} and it
* is not present in {@code serviceName} service in the WSDL.
* <li>If the {@code wsdlDocumentLocation} is NOT {@code null}
* and does not represent a valid WSDL.
* </ul>
* @throws WebServiceException If an error occurs while creating the
* <code>W3CEndpointReference</code>.
* {@code W3CEndpointReference}.
*
* @since 1.6, JAX-WS 2.1
*/
@ -340,73 +338,73 @@ public abstract class Provider {
/**
* Factory method to create a <code>W3CEndpointReference</code>.
* Using this method, a <code>W3CEndpointReference</code> instance
* Factory method to create a {@code W3CEndpointReference}.
* Using this method, a {@code W3CEndpointReference} instance
* can be created with extension elements, and attributes.
* <code>Provider</code> implementations must override the default
* {@code Provider} implementations must override the default
* implementation.
*
* <p>
* This method can be used to create a <code>W3CEndpointReference</code>
* for any endpoint by specifying the <code>address</code> property along
* This method can be used to create a {@code W3CEndpointReference}
* for any endpoint by specifying the {@code address} property along
* with any other desired properties. This method
* can also be used to create a <code>W3CEndpointReference</code> for
* can also be used to create a {@code W3CEndpointReference} for
* an endpoint that is published by the same Java EE application.
* To do so the <code>address</code> property can be provided or this
* method can automatically determine the <code>address</code> of
* To do so the {@code address} property can be provided or this
* method can automatically determine the {@code address} of
* an endpoint that is published by the same Java EE application and is
* identified by the <code>serviceName</code> and
* <code>portName</code> propeties. If the <code>address</code> is
* <code>null</code> and the <code>serviceName</code> and
* <code>portName</code> do not identify an endpoint published by the
* identified by the {@code serviceName} and
* {@code portName} propeties. If the {@code address} is
* {@code null} and the {@code serviceName} and
* {@code portName} do not identify an endpoint published by the
* same Java EE application, a
* <code>javax.lang.IllegalStateException</code> MUST be thrown.
* {@code javax.lang.IllegalStateException} MUST be thrown.
*
* @param address Specifies the address of the target endpoint
* @param interfaceName the <code>wsam:InterfaceName</code> element in the
* <code>wsa:Metadata</code> element.
* @param interfaceName the {@code wsam:InterfaceName} element in the
* {@code wsa:Metadata} element.
* @param serviceName Qualified name of the service in the WSDL.
* @param portName Qualified name of the endpoint in the WSDL.
* @param metadata A list of elements that should be added to the
* <code>W3CEndpointReference</code> instances <code>wsa:metadata</code>
* {@code W3CEndpointReference} instances {@code wsa:metadata}
* element.
* @param wsdlDocumentLocation URL for the WSDL document location for
* the service.
* @param referenceParameters Reference parameters to be associated
* with the returned <code>EndpointReference</code> instance.
* with the returned {@code EndpointReference} instance.
* @param elements extension elements to be associated
* with the returned <code>EndpointReference</code> instance.
* with the returned {@code EndpointReference} instance.
* @param attributes extension attributes to be associated
* with the returned <code>EndpointReference</code> instance.
* with the returned {@code EndpointReference} instance.
*
* @return the <code>W3CEndpointReference</code> created from
* <code>serviceName</code>, <code>portName</code>,
* <code>metadata</code>, <code>wsdlDocumentLocation</code>
* and <code>referenceParameters</code>. This method
* never returns <code>null</code>.
* @return the {@code W3CEndpointReference} created from
* {@code serviceName}, {@code portName},
* {@code metadata}, {@code wsdlDocumentLocation}
* and {@code referenceParameters}. This method
* never returns {@code null}.
*
* @throws java.lang.IllegalStateException
* <ul>
* <li>If the <code>address</code>, <code>serviceName</code> and
* <code>portName</code> are all <code>null</code>.
* <li>If the <code>serviceName</code> service is <code>null</code> and the
* <code>portName</code> is NOT <code>null</code>.
* <li>If the <code>address</code> property is <code>null</code> and
* the <code>serviceName</code> and <code>portName</code> do not
* <li>If the {@code address}, {@code serviceName} and
* {@code portName} are all {@code null}.
* <li>If the {@code serviceName} service is {@code null} and the
* {@code portName} is NOT {@code null}.
* <li>If the {@code address} property is {@code null} and
* the {@code serviceName} and {@code portName} do not
* specify a valid endpoint published by the same Java EE
* application.
* <li>If the <code>serviceName</code>is NOT <code>null</code>
* <li>If the {@code serviceName}is NOT {@code null}
* and is not present in the specified WSDL.
* <li>If the <code>portName</code> port is not <code>null</code> and it
* is not present in <code>serviceName</code> service in the WSDL.
* <li>If the <code>wsdlDocumentLocation</code> is NOT <code>null</code>
* <li>If the {@code portName} port is not {@code null} and it
* is not present in {@code serviceName} service in the WSDL.
* <li>If the {@code wsdlDocumentLocation} is NOT {@code null}
* and does not represent a valid WSDL.
* <li>If the <code>wsdlDocumentLocation</code> is NOT <code>null</code> but
* <li>If the {@code wsdlDocumentLocation} is NOT {@code null} but
* wsdli:wsdlLocation's namespace name cannot be got from the available
* metadata.
* </ul>
* @throws WebServiceException If an error occurs while creating the
* <code>W3CEndpointReference</code>.
* {@code W3CEndpointReference}.
* @since 1.7, JAX-WS 2.2
*/
public W3CEndpointReference createW3CEndpointReference(String address,
@ -419,7 +417,7 @@ public abstract class Provider {
/**
* Creates and publishes an endpoint object with the specified
* address, implementation object and web service features.
* <code>Provider</code> implementations must override the
* {@code Provider} implementations must override the
* default implementation.
*
* @param address A URI specifying the address and transport/protocol
@ -431,8 +429,8 @@ public abstract class Provider {
* class MUST be annotated with all the necessary Web service
* annotations.
* @param features A list of WebServiceFeatures to configure on the
* endpoint. Supported features not in the <code>features
* </code> parameter will have their default values.
* endpoint. Supported features not in the {@code features}
* parameter will have their default values.
* @return The newly created endpoint.
* @since 1.7, JAX-WS 2.2
*/
@ -443,7 +441,7 @@ public abstract class Provider {
/**
* Creates an endpoint object with the provided binding, implementation
* object and web service features. <code>Provider</code> implementations
* object and web service features. {@code Provider} implementations
* must override the default implementation.
*
* @param bindingId A URI specifying the desired binding (e.g. SOAP/HTTP)
@ -452,8 +450,8 @@ public abstract class Provider {
* class MUST be annotated with all the necessary Web service
* annotations.
* @param features A list of WebServiceFeatures to configure on the
* endpoint. Supported features not in the <code>features
* </code> parameter will have their default values.
* endpoint. Supported features not in the {@code features}
* parameter will have their default values.
* @return The newly created endpoint.
* @since 1.7, JAX-WS 2.2
*/
@ -465,7 +463,7 @@ public abstract class Provider {
/**
* Creates an endpoint object with the provided binding, implementation
* class, invoker and web service features. Containers typically use
* this to create Endpoint objects. <code>Provider</code>
* this to create Endpoint objects. {@code Provider}
* implementations must override the default implementation.
*
* @param bindingId A URI specifying the desired binding (e.g. SOAP/HTTP).
@ -475,8 +473,8 @@ public abstract class Provider {
* annotations.
* @param invoker that does the actual invocation on the service instance.
* @param features A list of WebServiceFeatures to configure on the
* endpoint. Supported features not in the <code>features
* </code> parameter will have their default values.
* endpoint. Supported features not in the {@code features
* } parameter will have their default values.
* @return The newly created endpoint.
* @since 1.7, JAX-WS 2.2
*/

21
jaxws/src/java.xml.ws/share/classes/javax/xml/ws/spi/WebServiceFeatureAnnotation.java
View File

@ -39,27 +39,26 @@ import javax.xml.ws.soap.MTOM;
/**
* Annotation used to identify other annotations
* as a <code>WebServiceFeature</code>.
* as a {@code WebServiceFeature}.
* <p>
* Each <code>WebServiceFeature</code> annotation annotated with
* Each {@code WebServiceFeature} annotation annotated with
* this annotation MUST contain an
* <code>enabled</code> property of type
* <code>boolean</code> with a default value of <code>true</code>.
* {@code enabled} property of type
* {@code boolean} with a default value of {@code true}.
* <p>
* JAX-WS defines the following
* <code>WebServiceFeature</code> annotations (<code>Addressing</code>,
* <code>MTOM</code>, <code>RespectBinding</code>), however, an implementation
* {@code WebServiceFeature} annotations ({@code Addressing},
* {@code MTOM}, {@code RespectBinding}), however, an implementation
* may define vendors specific annotations for other features.
* <p>
* Annotations annotated with <code>WebServiceFeatureAnnotation</code> MUST
* Annotations annotated with {@code WebServiceFeatureAnnotation} MUST
* have the same @Target of {@link WebServiceRef} annotation, so that the resulting
* feature annotation can be used in conjunction with the {@link WebServiceRef}
* annotation if necessary.
* <p>
* If a JAX-WS implementation encounters an annotation annotated
* with the <code>WebServiceFeatureAnnotation</code> that it does not
* with the {@code WebServiceFeatureAnnotation} that it does not
* recognize/support an error MUST be given.
* <p>
*
* @see Addressing
* @see MTOM
@ -79,8 +78,8 @@ public @interface WebServiceFeatureAnnotation {
String id();
/**
* The <code>WebServiceFeature</code> bean that is associated
* with the <code>WebServiceFeature</code> annotation
* The {@code WebServiceFeature} bean that is associated
* with the {@code WebServiceFeature} annotation
*/
Class<? extends WebServiceFeature> bean();
}

10
jaxws/src/java.xml.ws/share/classes/javax/xml/ws/spi/http/package-info.java
View File

@ -47,7 +47,7 @@
object encapsulates a HTTP request and a response.
</ol>
<pre>
<pre>{@literal
Container JAX-WS runtime
--------- --------------
1. Creates Invoker1, ... InvokerN
@ -64,10 +64,10 @@
10. EndpointN.publish(HttpContextN) --> 11. creates HttpHandlerN
HttpContextN.setHandler(HttpHandlerN)
</pre>
}</pre>
The request processing is done as below(for every request):
<pre>
<pre>{@literal
Container JAX-WS runtime
--------- --------------
1. Creates a HttpExchange
@ -76,14 +76,14 @@
<-- 5. Calls Invoker
6. Invokes the actual instance
7. Writes the response to HttpExchange
</pre>
}</pre>
<p>
The portable undeployment is done as below:
<pre>
Container
---------
1. @preDestroy on instances
1. {@literal @}preDestroy on instances
2. Endpoint1.stop()
...
3. EndpointN.stop()