archive/jdk
1
0
Fork 0
mirror of https://github.com/openjdk/jdk.git synced 2025-09-20 02:54:35 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

8077332: tidy warnings from javax/xml

Browse source 
Some HTML markup fix (jaxp part)

Reviewed-by: joehw, lancea
This commit is contained in:
Alexander Stepanov 2015-04-21 20:01:21 +04:00
parent 7cbdcf978d
commit b27f042010
30 changed files with 1381 additions and 1412 deletions
Download patch file Download diff file Expand all files Collapse all files

107
jaxp/src/java.xml/share/classes/javax/xml/XMLConstants.java
View file

@ -26,7 +26,7 @@
package javax.xml; package javax.xml;
/** /**
* <p>Utility class to contain basic XML values as constants.</p> * <p>Utility class to contain basic XML values as constants.
* *
* @author <a href="mailto:Jeff.Suttor@Sun.com">Jeff Suttor</a> * @author <a href="mailto:Jeff.Suttor@Sun.com">Jeff Suttor</a>
* @see <a href="http://www.w3.org/TR/xml11/">Extensible Markup Language (XML) 1.1</a> * @see <a href="http://www.w3.org/TR/xml11/">Extensible Markup Language (XML) 1.1</a>
@ -42,15 +42,15 @@ package javax.xml;
public final class XMLConstants { public final class XMLConstants {
/** /**
* <p>Private constructor to prevent instantiation.</p> * Private constructor to prevent instantiation.
*/ */
private XMLConstants() { private XMLConstants() {
} }
/** /**
* <p>Namespace URI to use to represent that there is no Namespace.</p> * Namespace URI to use to represent that there is no Namespace.
* *
* <p>Defined by the Namespace specification to be "".</p> * <p>Defined by the Namespace specification to be "".
* *
* @see <a href="http://www.w3.org/TR/REC-xml-names/#defaulting"> * @see <a href="http://www.w3.org/TR/REC-xml-names/#defaulting">
* Namespaces in XML, 5.2 Namespace Defaulting</a> * Namespaces in XML, 5.2 Namespace Defaulting</a>
@ -58,9 +58,9 @@ public final class XMLConstants {
public static final String NULL_NS_URI = ""; public static final String NULL_NS_URI = "";
/** /**
* <p>Prefix to use to represent the default XML Namespace.</p> * Prefix to use to represent the default XML Namespace.
* *
* <p>Defined by the XML specification to be "".</p> * <p>Defined by the XML specification to be "".
* *
* @see <a * @see <a
* href="http://www.w3.org/TR/REC-xml-names/#ns-qualnames"> * href="http://www.w3.org/TR/REC-xml-names/#ns-qualnames">
@ -69,10 +69,10 @@ public final class XMLConstants {
public static final String DEFAULT_NS_PREFIX = ""; public static final String DEFAULT_NS_PREFIX = "";
/** /**
* <p>The official XML Namespace name URI.</p> * The official XML Namespace name URI.
* *
* <p>Defined by the XML specification to be * <p>Defined by the XML specification to be
* "{@code http://www.w3.org/XML/1998/namespace}".</p> * "{@code http://www.w3.org/XML/1998/namespace}".
* *
* @see <a * @see <a
* href="http://www.w3.org/TR/REC-xml-names/#ns-qualnames"> * href="http://www.w3.org/TR/REC-xml-names/#ns-qualnames">
@ -82,23 +82,23 @@ public final class XMLConstants {
"http://www.w3.org/XML/1998/namespace"; "http://www.w3.org/XML/1998/namespace";
/** /**
* <p>The official XML Namespace prefix.</p> * The official XML Namespace prefix.
* *
* <p>Defined by the XML specification to be "{@code xml}".</p> * <p>Defined by the XML specification to be "{@code xml}".
* *
* @see <a * @see <a
* href="http://www.w3.org/TR/REC-xml-names/#ns-qualnames"> * href="http://www.w3.org/TR/REC-xml-names/#ns-qualnames">
* Namespaces in XML, 3. Qualified Names<</a> * Namespaces in XML, 3. Qualified Names</a>
*/ */
public static final String XML_NS_PREFIX = "xml"; public static final String XML_NS_PREFIX = "xml";
/** /**
* <p>The official XML attribute used for specifying XML Namespace * The official XML attribute used for specifying XML Namespace
* declarations, {@link #XMLNS_ATTRIBUTE * declarations, {@link #XMLNS_ATTRIBUTE
* XMLConstants.XMLNS_ATTRIBUTE}, Namespace name URI.</p> * XMLConstants.XMLNS_ATTRIBUTE}, Namespace name URI.
* *
* <p>Defined by the XML specification to be * <p>Defined by the XML specification to be
* "{@code http://www.w3.org/2000/xmlns/}".</p> * "{@code http://www.w3.org/2000/xmlns/}".
* *
* @see <a * @see <a
* href="http://www.w3.org/TR/REC-xml-names/#ns-qualnames"> * href="http://www.w3.org/TR/REC-xml-names/#ns-qualnames">
@ -111,12 +111,12 @@ public final class XMLConstants {
"http://www.w3.org/2000/xmlns/"; "http://www.w3.org/2000/xmlns/";
/** /**
* <p>The official XML attribute used for specifying XML Namespace * The official XML attribute used for specifying XML Namespace
* declarations.</p> * declarations.
* *
* <p>It is <strong><em>NOT</em></strong> valid to use as a * <p>It is <strong><em>NOT</em></strong> valid to use as a
* prefix. Defined by the XML specification to be * prefix. Defined by the XML specification to be
* "{@code xmlns}".</p> * "{@code xmlns}".
* *
* @see <a * @see <a
* href="http://www.w3.org/TR/REC-xml-names/#ns-qualnames"> * href="http://www.w3.org/TR/REC-xml-names/#ns-qualnames">
@ -125,7 +125,7 @@ public final class XMLConstants {
public static final String XMLNS_ATTRIBUTE = "xmlns"; public static final String XMLNS_ATTRIBUTE = "xmlns";
/** /**
* <p>W3C XML Schema Namespace URI.</p> * W3C XML Schema Namespace URI.
* *
* <p>Defined to be "{@code http://www.w3.org/2001/XMLSchema}". * <p>Defined to be "{@code http://www.w3.org/2001/XMLSchema}".
* *
@ -138,9 +138,9 @@ public final class XMLConstants {
"http://www.w3.org/2001/XMLSchema"; "http://www.w3.org/2001/XMLSchema";
/** /**
* <p>W3C XML Schema Instance Namespace URI.</p> * W3C XML Schema Instance Namespace URI.
* *
* <p>Defined to be "{@code http://www.w3.org/2001/XMLSchema-instance}".</p> * <p>Defined to be "{@code http://www.w3.org/2001/XMLSchema-instance}".
* *
* @see <a href= * @see <a href=
* "http://www.w3.org/TR/xmlschema-1/#Instance_Document_Constructions"> * "http://www.w3.org/TR/xmlschema-1/#Instance_Document_Constructions">
@ -150,33 +150,33 @@ public final class XMLConstants {
public static final String W3C_XML_SCHEMA_INSTANCE_NS_URI = public static final String W3C_XML_SCHEMA_INSTANCE_NS_URI =
"http://www.w3.org/2001/XMLSchema-instance"; "http://www.w3.org/2001/XMLSchema-instance";
/** /**
* <p>W3C XPath Datatype Namespace URI.</p> * W3C XPath Datatype Namespace URI.
* *
* <p>Defined to be "{@code http://www.w3.org/2003/11/xpath-datatypes}".</p> * <p>Defined to be "{@code http://www.w3.org/2003/11/xpath-datatypes}".
* *
* @see <a href="http://www.w3.org/TR/xpath-datamodel">XQuery 1.0 and XPath 2.0 Data Model</a> * @see <a href="http://www.w3.org/TR/xpath-datamodel">XQuery 1.0 and XPath 2.0 Data Model</a>
*/ */
public static final String W3C_XPATH_DATATYPE_NS_URI = "http://www.w3.org/2003/11/xpath-datatypes"; public static final String W3C_XPATH_DATATYPE_NS_URI = "http://www.w3.org/2003/11/xpath-datatypes";
/** /**
* <p>XML Document Type Declaration Namespace URI as an arbitrary value.</p> * XML Document Type Declaration Namespace URI as an arbitrary value.
* *
* <p>Since not formally defined by any existing standard, arbitrarily define to be "{@code http://www.w3.org/TR/REC-xml}". * <p>Since not formally defined by any existing standard, arbitrarily define to be "{@code http://www.w3.org/TR/REC-xml}".
*/ */
public static final String XML_DTD_NS_URI = "http://www.w3.org/TR/REC-xml"; public static final String XML_DTD_NS_URI = "http://www.w3.org/TR/REC-xml";
/** /**
* <p>RELAX NG Namespace URI.</p> * RELAX NG Namespace URI.
* *
* <p>Defined to be "{@code http://relaxng.org/ns/structure/1.0}".</p> * <p>Defined to be "{@code http://relaxng.org/ns/structure/1.0}".
* *
* @see <a href="http://relaxng.org/spec-20011203.html">RELAX NG Specification</a> * @see <a href="http://relaxng.org/spec-20011203.html">RELAX NG Specification</a>
*/ */
public static final String RELAXNG_NS_URI = "http://relaxng.org/ns/structure/1.0"; public static final String RELAXNG_NS_URI = "http://relaxng.org/ns/structure/1.0";
/** /**
* <p>Feature for secure processing.</p> * Feature for secure processing.
* *
* <ul> * <ul>
* <li> * <li>
@ -193,14 +193,13 @@ public final class XMLConstants {
/** /**
* <p>Property: accessExternalDTD</p> * Property: accessExternalDTD
* *
* <p> * <p>
* Restrict access to external DTDs and external Entity References to the protocols specified. * Restrict access to external DTDs and external Entity References to the protocols specified.
* If access is denied due to the restriction of this property, a runtime exception that * If access is denied due to the restriction of this property, a runtime exception that
* is specific to the context is thrown. In the case of {@link javax.xml.parsers.SAXParser} * is specific to the context is thrown. In the case of {@link javax.xml.parsers.SAXParser}
* for example, {@link org.xml.sax.SAXException} is thrown. * for example, {@link org.xml.sax.SAXException} is thrown.
* </p>
* *
* <p> * <p>
* <b>Value: </b> a list of protocols separated by comma. A protocol is the scheme portion of a * <b>Value: </b> a list of protocols separated by comma. A protocol is the scheme portion of a
@ -221,7 +220,6 @@ public final class XMLConstants {
* Examples of protocols are file, http, jar:file. * Examples of protocols are file, http, jar:file.
* *
* </blockquote> * </blockquote>
*</p>
* *
*<p> *<p>
* <b>Default value:</b> The default value is implementation specific and therefore not specified. * <b>Default value:</b> The default value is implementation specific and therefore not specified.
@ -231,20 +229,19 @@ public final class XMLConstants {
* <LI>an empty string to deny all access to external references;</LI> * <LI>an empty string to deny all access to external references;</LI>
* <LI>a specific protocol, such as file, to give permission to only the protocol;</LI> * <LI>a specific protocol, such as file, to give permission to only the protocol;</LI>
* <LI>the keyword "all" to grant permission to all protocols.</LI> * <LI>the keyword "all" to grant permission to all protocols.</LI>
*</UL><br> * </UL><br>
* When FEATURE_SECURE_PROCESSING is enabled, it is recommended that implementations * When FEATURE_SECURE_PROCESSING is enabled, it is recommended that implementations
* restrict external connections by default, though this may cause problems for applications * restrict external connections by default, though this may cause problems for applications
* that process XML/XSD/XSL with external references. * that process XML/XSD/XSL with external references.
* </blockquote> * </blockquote>
* </p>
* *
* <p> * <p>
* <b>Granting all access:</b> the keyword "all" grants permission to all protocols. * <b>Granting all access:</b> the keyword "all" grants permission to all protocols.
* </p> *
* <p> * <p>
* <b>System Property:</b> The value of this property can be set or overridden by * <b>System Property:</b> The value of this property can be set or overridden by
* system property {@code javax.xml.accessExternalDTD}. * system property {@code javax.xml.accessExternalDTD}.
* </p> *
* *
* <p> * <p>
* <b>jaxp.properties:</b> This configuration file is in standard * <b>jaxp.properties:</b> This configuration file is in standard
@ -252,11 +249,8 @@ public final class XMLConstants {
* directory of the Java installation. If the file exists and the system * directory of the Java installation. If the file exists and the system
* property is specified, its value will be used to override the default * property is specified, its value will be used to override the default
* of the property. * of the property.
* </p>
* *
* <p>
* *
* </p>
* @since 1.7 * @since 1.7
*/ */
public static final String ACCESS_EXTERNAL_DTD = "http://javax.xml.XMLConstants/property/accessExternalDTD"; public static final String ACCESS_EXTERNAL_DTD = "http://javax.xml.XMLConstants/property/accessExternalDTD";
@ -270,7 +264,7 @@ public final class XMLConstants {
* due to the restriction of this property, a runtime exception that is specific * due to the restriction of this property, a runtime exception that is specific
* to the context is thrown. In the case of {@link javax.xml.validation.SchemaFactory} * to the context is thrown. In the case of {@link javax.xml.validation.SchemaFactory}
* for example, org.xml.sax.SAXException is thrown. * for example, org.xml.sax.SAXException is thrown.
* </p> *
* <p> * <p>
* <b>Value:</b> a list of protocols separated by comma. A protocol is the scheme portion of a * <b>Value:</b> a list of protocols separated by comma. A protocol is the scheme portion of a
* {@link java.net.URI}, or in the case of the JAR protocol, "jar" plus the scheme portion * {@link java.net.URI}, or in the case of the JAR protocol, "jar" plus the scheme portion
@ -290,9 +284,8 @@ public final class XMLConstants {
* Examples of protocols are file, http, jar:file. * Examples of protocols are file, http, jar:file.
* *
* </blockquote> * </blockquote>
*</p>
* *
*<p> * <p>
* <b>Default value:</b> The default value is implementation specific and therefore not specified. * <b>Default value:</b> The default value is implementation specific and therefore not specified.
* The following options are provided for consideration: * The following options are provided for consideration:
* <blockquote> * <blockquote>
@ -300,20 +293,18 @@ public final class XMLConstants {
* <LI>an empty string to deny all access to external references;</LI> * <LI>an empty string to deny all access to external references;</LI>
* <LI>a specific protocol, such as file, to give permission to only the protocol;</LI> * <LI>a specific protocol, such as file, to give permission to only the protocol;</LI>
* <LI>the keyword "all" to grant permission to all protocols.</LI> * <LI>the keyword "all" to grant permission to all protocols.</LI>
*</UL><br> * </UL><br>
* When FEATURE_SECURE_PROCESSING is enabled, it is recommended that implementations * When FEATURE_SECURE_PROCESSING is enabled, it is recommended that implementations
* restrict external connections by default, though this may cause problems for applications * restrict external connections by default, though this may cause problems for applications
* that process XML/XSD/XSL with external references. * that process XML/XSD/XSL with external references.
* </blockquote> * </blockquote>
* </p> *
* <p> * <p>
* <b>Granting all access:</b> the keyword "all" grants permission to all protocols. * <b>Granting all access:</b> the keyword "all" grants permission to all protocols.
* </p>
* *
* <p> * <p>
* <b>System Property:</b> The value of this property can be set or overridden by * <b>System Property:</b> The value of this property can be set or overridden by
* system property {@code javax.xml.accessExternalSchema} * system property {@code javax.xml.accessExternalSchema}
* </p>
* *
* <p> * <p>
* <b>jaxp.properties:</b> This configuration file is in standard * <b>jaxp.properties:</b> This configuration file is in standard
@ -323,12 +314,11 @@ public final class XMLConstants {
* of the property. * of the property.
* *
* @since 1.7 * @since 1.7
* </p>
*/ */
public static final String ACCESS_EXTERNAL_SCHEMA = "http://javax.xml.XMLConstants/property/accessExternalSchema"; public static final String ACCESS_EXTERNAL_SCHEMA = "http://javax.xml.XMLConstants/property/accessExternalSchema";
/** /**
* <p>Property: accessExternalStylesheet</p> * Property: accessExternalStylesheet
* *
* <p> * <p>
* Restrict access to the protocols specified for external references set by the * Restrict access to the protocols specified for external references set by the
@ -338,7 +328,7 @@ public final class XMLConstants {
* {@link javax.xml.transform.Transformer} for example, * {@link javax.xml.transform.Transformer} for example,
* {@link javax.xml.transform.TransformerConfigurationException} * {@link javax.xml.transform.TransformerConfigurationException}
* will be thrown by the {@link javax.xml.transform.TransformerFactory}. * will be thrown by the {@link javax.xml.transform.TransformerFactory}.
* </p> *
* <p> * <p>
* <b>Value:</b> a list of protocols separated by comma. A protocol is the scheme portion of a * <b>Value:</b> a list of protocols separated by comma. A protocol is the scheme portion of a
* {@link java.net.URI}, or in the case of the JAR protocol, "jar" plus the scheme portion * {@link java.net.URI}, or in the case of the JAR protocol, "jar" plus the scheme portion
@ -358,9 +348,8 @@ public final class XMLConstants {
* Examples of protocols are file, http, jar:file. * Examples of protocols are file, http, jar:file.
* *
* </blockquote> * </blockquote>
*</p>
* *
*<p> * <p>
* <b>Default value:</b> The default value is implementation specific and therefore not specified. * <b>Default value:</b> The default value is implementation specific and therefore not specified.
* The following options are provided for consideration: * The following options are provided for consideration:
* <blockquote> * <blockquote>
@ -368,20 +357,18 @@ public final class XMLConstants {
* <LI>an empty string to deny all access to external references;</LI> * <LI>an empty string to deny all access to external references;</LI>
* <LI>a specific protocol, such as file, to give permission to only the protocol;</LI> * <LI>a specific protocol, such as file, to give permission to only the protocol;</LI>
* <LI>the keyword "all" to grant permission to all protocols.</LI> * <LI>the keyword "all" to grant permission to all protocols.</LI>
*</UL><br> * </UL><br>
* When FEATURE_SECURE_PROCESSING is enabled, it is recommended that implementations * When FEATURE_SECURE_PROCESSING is enabled, it is recommended that implementations
* restrict external connections by default, though this may cause problems for applications * restrict external connections by default, though this may cause problems for applications
* that process XML/XSD/XSL with external references. * that process XML/XSD/XSL with external references.
* </blockquote> * </blockquote>
* </p> *
* <p> * <p>
* <b>Granting all access:</b> the keyword "all" grants permission to all protocols. * <b>Granting all access:</b> the keyword "all" grants permission to all protocols.
* </p>
* *
* <p> * <p>
* <b>System Property:</b> The value of this property can be set or overridden by * <b>System Property:</b> The value of this property can be set or overridden by
* system property {@code javax.xml.accessExternalStylesheet} * system property {@code javax.xml.accessExternalStylesheet}
* </p>
* *
* <p> * <p>
* <b>jaxp.properties:</b> This configuration file is in standard * <b>jaxp.properties:</b> This configuration file is in standard

475
jaxp/src/java.xml/share/classes/javax/xml/datatype/DatatypeFactory.java
View file

@ -32,11 +32,10 @@ import java.util.regex.Matcher;
import java.util.regex.Pattern; import java.util.regex.Pattern;
/** /**
* Factory that creates new <code>javax.xml.datatype</code> <code>Object</code>s that map XML to/from Java <code>Object</code>s. * Factory that creates new {@code javax.xml.datatype} {@code Object}s that map XML to/from Java {@code Object}s.
* <p> * <p>
* A new instance of the {@code DatatypeFactory} is created through the {@link #newInstance()} method * A new instance of the {@code DatatypeFactory} is created through the {@link #newInstance()} method
* that uses the following implementation resolution mechanisms to determine an implementation: * that uses the following implementation resolution mechanisms to determine an implementation:
* <p>
* <ol> * <ol>
* <li> * <li>
* If the system property specified by {@link #DATATYPEFACTORY_PROPERTY}, "{@code javax.xml.datatype.DatatypeFactory}", * If the system property specified by {@link #DATATYPEFACTORY_PROPERTY}, "{@code javax.xml.datatype.DatatypeFactory}",
@ -89,9 +88,9 @@ import java.util.regex.Pattern;
public abstract class DatatypeFactory { public abstract class DatatypeFactory {
/** /**
* <p>Default property name as defined in JSR 206: Java(TM) API for XML Processing (JAXP) 1.3.</p> * Default property name as defined in JSR 206: Java(TM) API for XML Processing (JAXP) 1.3.
* *
* <p>Default value is {@code javax.xml.datatype.DatatypeFactory}.</p> * <p>Default value is {@code javax.xml.datatype.DatatypeFactory}.
*/ */
public static final String DATATYPEFACTORY_PROPERTY = public static final String DATATYPEFACTORY_PROPERTY =
// We use a String constant here, rather than calling // We use a String constant here, rather than calling
@ -100,16 +99,15 @@ public abstract class DatatypeFactory {
"javax.xml.datatype.DatatypeFactory"; "javax.xml.datatype.DatatypeFactory";
/** /**
* <p>Default implementation class name as defined in * Default implementation class name as defined in
* <em>JSR 206: Java(TM) API for XML Processing (JAXP) 1.3</em>.</p> * <em>JSR 206: Java(TM) API for XML Processing (JAXP) 1.3</em>.
* *
* <p>Implementers should specify the name of an appropriate class * <p>Implementers should specify the name of an appropriate class
* to be instantiated if no other implementation resolution mechanism * to be instantiated if no other implementation resolution mechanism
* succeeds.</p> * succeeds.
* *
* <p>Users should not refer to this field; it is intended only to * <p>Users should not refer to this field; it is intended only to
* document a factory implementation detail. * document a factory implementation detail.
* </p>
*/ */
public static final String DATATYPEFACTORY_IMPLEMENTATION_CLASS = public static final String DATATYPEFACTORY_IMPLEMENTATION_CLASS =
// We use new String() here to prevent javadoc from generating // We use new String() here to prevent javadoc from generating
@ -130,18 +128,18 @@ public abstract class DatatypeFactory {
Pattern.compile("[^YM]*[DT].*"); Pattern.compile("[^YM]*[DT].*");
/** /**
* <p>Protected constructor to prevent instantiation outside of package.</p> * Protected constructor to prevent instantiation outside of package.
* *
* <p>Use {@link #newInstance()} to create a {@code DatatypeFactory}.</p> * <p>Use {@link #newInstance()} to create a {@code DatatypeFactory}.
*/ */
protected DatatypeFactory() { protected DatatypeFactory() {
} }
/** /**
* <p>Obtain a new instance of a {@code DatatypeFactory}.</p> * Obtain a new instance of a {@code DatatypeFactory}.
* *
* <p>The implementation resolution mechanisms are <a href="#DatatypeFactory.newInstance">defined</a> in this * <p>The implementation resolution mechanisms are <a href="#DatatypeFactory.newInstance">defined</a> in this
* <code>Class</code>'s documentation.</p> * {@code Class}'s documentation.
* *
* @return New instance of a {@code DatatypeFactory} * @return New instance of a {@code DatatypeFactory}
* *
@ -161,33 +159,33 @@ public abstract class DatatypeFactory {
} }
/** /**
* <p>Obtain a new instance of a {@code DatatypeFactory} from class name. * Obtain a new instance of a {@code DatatypeFactory} from class name.
* This function is useful when there are multiple providers in the classpath. * This function is useful when there are multiple providers in the classpath.
* It gives more control to the application as it can specify which provider * It gives more control to the application as it can specify which provider
* should be loaded.</p> * should be loaded.
* *
* <p>Once an application has obtained a reference to a {@code DatatypeFactory} * <p>Once an application has obtained a reference to a {@code DatatypeFactory}
* it can use the factory to configure and obtain datatype instances.</P> * it can use the factory to configure and obtain datatype instances.
* *
* *
* <h2>Tip for Trouble-shooting</h2> * <h2>Tip for Trouble-shooting</h2>
* <p>Setting the <code>jaxp.debug</code> system property will cause * <p>Setting the {@code jaxp.debug} system property will cause
* this method to print a lot of debug messages * this method to print a lot of debug messages
* to <code>System.err</code> about what it is doing and where it is looking at.</p> * to {@code System.err} about what it is doing and where it is looking at.
* *
* <p> If you have problems try:</p> * <p> If you have problems try:
* <pre> * <pre>
* java -Djaxp.debug=1 YourProgram .... * java -Djaxp.debug=1 YourProgram ....
* </pre> * </pre>
* *
* @param factoryClassName fully qualified factory class name that provides implementation of {@code javax.xml.datatype.DatatypeFactory}. * @param factoryClassName fully qualified factory class name that provides implementation of {@code javax.xml.datatype.DatatypeFactory}.
* *
* @param classLoader <code>ClassLoader</code> used to load the factory class. If <code>null</code> * @param classLoader {@code ClassLoader} used to load the factory class. If {@code null}
* current <code>Thread</code>'s context classLoader is used to load the factory class. * current {@code Thread}'s context classLoader is used to load the factory class.
* *
* @return New instance of a {@code DatatypeFactory} * @return New instance of a {@code DatatypeFactory}
* *
* @throws DatatypeConfigurationException if <code>factoryClassName</code> is <code>null</code>, or * @throws DatatypeConfigurationException if {@code factoryClassName} is {@code null}, or
* the factory class cannot be loaded, instantiated. * the factory class cannot be loaded, instantiated.
* *
* @see #newInstance() * @see #newInstance()
@ -201,11 +199,11 @@ public abstract class DatatypeFactory {
} }
/** /**
* <p>Obtain a new instance of a <code>Duration</code> * Obtain a new instance of a {@code Duration}
* specifying the <code>Duration</code> as its string representation, "PnYnMnDTnHnMnS", * specifying the {@code Duration} as its string representation, "PnYnMnDTnHnMnS",
* as defined in XML Schema 1.0 section 3.2.6.1.</p> * as defined in XML Schema 1.0 section 3.2.6.1.
* *
* <p>XML Schema Part 2: Datatypes, 3.2.6 duration, defines <code>duration</code> as:</p> * <p>XML Schema Part 2: Datatypes, 3.2.6 duration, defines {@code duration} as:
* <blockquote> * <blockquote>
* duration represents a duration of time. * duration represents a duration of time.
* The value space of duration is a six-dimensional space where the coordinates designate the * The value space of duration is a six-dimensional space where the coordinates designate the
@ -213,28 +211,28 @@ public abstract class DatatypeFactory {
* These components are ordered in their significance by their order of appearance i.e. as * These components are ordered in their significance by their order of appearance i.e. as
* year, month, day, hour, minute, and second. * year, month, day, hour, minute, and second.
* </blockquote> * </blockquote>
* <p>All six values are set and available from the created {@link Duration}</p> * <p>All six values are set and available from the created {@link Duration}
* *
* <p>The XML Schema specification states that values can be of an arbitrary size. * <p>The XML Schema specification states that values can be of an arbitrary size.
* Implementations may chose not to or be incapable of supporting arbitrarily large and/or small values. * Implementations may chose not to or be incapable of supporting arbitrarily large and/or small values.
* An {@link UnsupportedOperationException} will be thrown with a message indicating implementation limits * An {@link UnsupportedOperationException} will be thrown with a message indicating implementation limits
* if implementation capacities are exceeded.</p> * if implementation capacities are exceeded.
* *
* @param lexicalRepresentation <code>String</code> representation of a <code>Duration</code>. * @param lexicalRepresentation {@code String} representation of a {@code Duration}.
* *
* @return New <code>Duration</code> created from parsing the <code>lexicalRepresentation</code>. * @return New {@code Duration} created from parsing the {@code lexicalRepresentation}.
* *
* @throws IllegalArgumentException If <code>lexicalRepresentation</code> is not a valid representation of a <code>Duration</code>. * @throws IllegalArgumentException If {@code lexicalRepresentation} is not a valid representation of a {@code Duration}.
* @throws UnsupportedOperationException If implementation cannot support requested values. * @throws UnsupportedOperationException If implementation cannot support requested values.
* @throws NullPointerException if <code>lexicalRepresentation</code> is <code>null</code>. * @throws NullPointerException if {@code lexicalRepresentation} is {@code null}.
*/ */
public abstract Duration newDuration(final String lexicalRepresentation); public abstract Duration newDuration(final String lexicalRepresentation);
/** /**
* <p>Obtain a new instance of a <code>Duration</code> * Obtain a new instance of a {@code Duration}
* specifying the <code>Duration</code> as milliseconds.</p> * specifying the {@code Duration} as milliseconds.
* *
* <p>XML Schema Part 2: Datatypes, 3.2.6 duration, defines <code>duration</code> as:</p> * <p>XML Schema Part 2: Datatypes, 3.2.6 duration, defines {@code duration} as:
* <blockquote> * <blockquote>
* duration represents a duration of time. * duration represents a duration of time.
* The value space of duration is a six-dimensional space where the coordinates designate the * The value space of duration is a six-dimensional space where the coordinates designate the
@ -243,8 +241,8 @@ public abstract class DatatypeFactory {
* year, month, day, hour, minute, and second. * year, month, day, hour, minute, and second.
* </blockquote> * </blockquote>
* <p>All six values are set by computing their values from the specified milliseconds * <p>All six values are set by computing their values from the specified milliseconds
* and are available using the <code>get</code> methods of the created {@link Duration}. * and are available using the {@code get} methods of the created {@link Duration}.
* The values conform to and are defined by:</p> * The values conform to and are defined by:
* <ul> * <ul>
* <li>ISO 8601:2000(E) Section 5.5.3.2 Alternative format</li> * <li>ISO 8601:2000(E) Section 5.5.3.2 Alternative format</li>
* <li><a href="http://www.w3.org/TR/xmlschema-2/#isoformats"> * <li><a href="http://www.w3.org/TR/xmlschema-2/#isoformats">
@ -259,38 +257,38 @@ public abstract class DatatypeFactory {
* {@link java.util.Calendar#DATE} = 1, etc. * {@link java.util.Calendar#DATE} = 1, etc.
* This is important as there are variations in the Gregorian Calendar, * This is important as there are variations in the Gregorian Calendar,
* e.g. leap years have different days in the month = {@link java.util.Calendar#FEBRUARY} * e.g. leap years have different days in the month = {@link java.util.Calendar#FEBRUARY}
* so the result of {@link Duration#getMonths()} and {@link Duration#getDays()} can be influenced.</p> * so the result of {@link Duration#getMonths()} and {@link Duration#getDays()} can be influenced.
* *
* @param durationInMilliSeconds Duration in milliseconds to create. * @param durationInMilliSeconds Duration in milliseconds to create.
* *
* @return New <code>Duration</code> representing <code>durationInMilliSeconds</code>. * @return New {@code Duration} representing {@code durationInMilliSeconds}.
*/ */
public abstract Duration newDuration(final long durationInMilliSeconds); public abstract Duration newDuration(final long durationInMilliSeconds);
/** /**
* <p>Obtain a new instance of a <code>Duration</code> * Obtain a new instance of a {@code Duration}
* specifying the <code>Duration</code> as isPositive, years, months, days, hours, minutes, seconds.</p> * specifying the {@code Duration} as isPositive, years, months, days, hours, minutes, seconds.
* *
* <p>The XML Schema specification states that values can be of an arbitrary size. * <p>The XML Schema specification states that values can be of an arbitrary size.
* Implementations may chose not to or be incapable of supporting arbitrarily large and/or small values. * Implementations may chose not to or be incapable of supporting arbitrarily large and/or small values.
* An {@link UnsupportedOperationException} will be thrown with a message indicating implementation limits * An {@link UnsupportedOperationException} will be thrown with a message indicating implementation limits
* if implementation capacities are exceeded.</p> * if implementation capacities are exceeded.
* *
* <p>A <code>null</code> value indicates that field is not set.</p> * <p>A {@code null} value indicates that field is not set.
* *
* @param isPositive Set to <code>false</code> to create a negative duration. When the length * @param isPositive Set to {@code false} to create a negative duration. When the length
* of the duration is zero, this parameter will be ignored. * of the duration is zero, this parameter will be ignored.
* @param years of this <code>Duration</code> * @param years of this {@code Duration}
* @param months of this <code>Duration</code> * @param months of this {@code Duration}
* @param days of this <code>Duration</code> * @param days of this {@code Duration}
* @param hours of this <code>Duration</code> * @param hours of this {@code Duration}
* @param minutes of this <code>Duration</code> * @param minutes of this {@code Duration}
* @param seconds of this <code>Duration</code> * @param seconds of this {@code Duration}
* *
* @return New <code>Duration</code> created from the specified values. * @return New {@code Duration} created from the specified values.
* *
* @throws IllegalArgumentException If the values are not a valid representation of a * @throws IllegalArgumentException If the values are not a valid representation of a
* <code>Duration</code>: if all the fields (years, months, ...) are null or * {@code Duration}: if all the fields (years, months, ...) are null or
* if any of the fields is negative. * if any of the fields is negative.
* @throws UnsupportedOperationException If implementation cannot support requested values. * @throws UnsupportedOperationException If implementation cannot support requested values.
*/ */
@ -304,24 +302,24 @@ public abstract class DatatypeFactory {
final BigDecimal seconds); final BigDecimal seconds);
/** /**
* <p>Obtain a new instance of a <code>Duration</code> * Obtain a new instance of a {@code Duration}
* specifying the <code>Duration</code> as isPositive, years, months, days, hours, minutes, seconds.</p> * specifying the {@code Duration} as isPositive, years, months, days, hours, minutes, seconds.
* *
* <p>A {@link DatatypeConstants#FIELD_UNDEFINED} value indicates that field is not set.</p> * <p>A {@link DatatypeConstants#FIELD_UNDEFINED} value indicates that field is not set.
* *
* @param isPositive Set to <code>false</code> to create a negative duration. When the length * @param isPositive Set to {@code false} to create a negative duration. When the length
* of the duration is zero, this parameter will be ignored. * of the duration is zero, this parameter will be ignored.
* @param years of this <code>Duration</code> * @param years of this {@code Duration}
* @param months of this <code>Duration</code> * @param months of this {@code Duration}
* @param days of this <code>Duration</code> * @param days of this {@code Duration}
* @param hours of this <code>Duration</code> * @param hours of this {@code Duration}
* @param minutes of this <code>Duration</code> * @param minutes of this {@code Duration}
* @param seconds of this <code>Duration</code> * @param seconds of this {@code Duration}
* *
* @return New <code>Duration</code> created from the specified values. * @return New {@code Duration} created from the specified values.
* *
* @throws IllegalArgumentException If the values are not a valid representation of a * @throws IllegalArgumentException If the values are not a valid representation of a
* <code>Duration</code>: if any of the fields is negative. * {@code Duration}: if any of the fields is negative.
* *
* @see #newDuration( * @see #newDuration(
* boolean isPositive, * boolean isPositive,
@ -371,28 +369,30 @@ public abstract class DatatypeFactory {
} }
/** /**
* <p>Create a <code>Duration</code> of type <code>xdt:dayTimeDuration</code> by parsing its <code>String</code> representation, * Create a {@code Duration} of type {@code xdt:dayTimeDuration}
* by parsing its {@code String} representation,
* "<em>PnDTnHnMnS</em>", <a href="http://www.w3.org/TR/xpath-datamodel#dayTimeDuration"> * "<em>PnDTnHnMnS</em>", <a href="http://www.w3.org/TR/xpath-datamodel#dayTimeDuration">
* XQuery 1.0 and XPath 2.0 Data Model, xdt:dayTimeDuration</a>.</p> * XQuery 1.0 and XPath 2.0 Data Model, xdt:dayTimeDuration</a>.
* *
* <p>The datatype <code>xdt:dayTimeDuration</code> is a subtype of <code>xs:duration</code> * <p>The datatype {@code xdt:dayTimeDuration} is a subtype of {@code xs:duration}
* whose lexical representation contains only day, hour, minute, and second components. * whose lexical representation contains only day, hour, minute, and second components.
* This datatype resides in the namespace <code>http://www.w3.org/2003/11/xpath-datatypes</code>.</p> * This datatype resides in the namespace {@code http://www.w3.org/2003/11/xpath-datatypes}.
* *
* <p>All four values are set and available from the created {@link Duration}</p> * <p>All four values are set and available from the created {@link Duration}
* *
* <p>The XML Schema specification states that values can be of an arbitrary size. * <p>The XML Schema specification states that values can be of an arbitrary size.
* Implementations may chose not to or be incapable of supporting arbitrarily large and/or small values. * Implementations may chose not to or be incapable of supporting arbitrarily large and/or small values.
* An {@link UnsupportedOperationException} will be thrown with a message indicating implementation limits * An {@link UnsupportedOperationException} will be thrown with a message indicating implementation limits
* if implementation capacities are exceeded.</p> * if implementation capacities are exceeded.
* *
* @param lexicalRepresentation Lexical representation of a duration. * @param lexicalRepresentation Lexical representation of a duration.
* *
* @return New <code>Duration</code> created using the specified <code>lexicalRepresentation</code>. * @return New {@code Duration} created using the specified {@code lexicalRepresentation}.
* *
* @throws IllegalArgumentException If <code>lexicalRepresentation</code> is not a valid representation of a <code>Duration</code> expressed only in terms of days and time. * @throws IllegalArgumentException If {@code lexicalRepresentation} is
* not a valid representation of a {@code Duration} expressed only in terms of days and time.
* @throws UnsupportedOperationException If implementation cannot support requested values. * @throws UnsupportedOperationException If implementation cannot support requested values.
* @throws NullPointerException If <code>lexicalRepresentation</code> is <code>null</code>. * @throws NullPointerException If {@code lexicalRepresentation} is {@code null}.
*/ */
public Duration newDurationDayTime(final String lexicalRepresentation) { public Duration newDurationDayTime(final String lexicalRepresentation) {
// lexicalRepresentation must be non-null // lexicalRepresentation must be non-null
@ -415,17 +415,18 @@ public abstract class DatatypeFactory {
} }
/** /**
* <p>Create a <code>Duration</code> of type <code>xdt:dayTimeDuration</code> using the specified milliseconds as defined in * Create a {@code Duration} of type {@code xdt:dayTimeDuration}
* using the specified milliseconds as defined in
* <a href="http://www.w3.org/TR/xpath-datamodel#dayTimeDuration"> * <a href="http://www.w3.org/TR/xpath-datamodel#dayTimeDuration">
* XQuery 1.0 and XPath 2.0 Data Model, xdt:dayTimeDuration</a>.</p> * XQuery 1.0 and XPath 2.0 Data Model, xdt:dayTimeDuration</a>.
* *
* <p>The datatype <code>xdt:dayTimeDuration</code> is a subtype of <code>xs:duration</code> * <p>The datatype {@code xdt:dayTimeDuration} is a subtype of {@code xs:duration}
* whose lexical representation contains only day, hour, minute, and second components. * whose lexical representation contains only day, hour, minute, and second components.
* This datatype resides in the namespace <code>http://www.w3.org/2003/11/xpath-datatypes</code>.</p> * This datatype resides in the namespace {@code http://www.w3.org/2003/11/xpath-datatypes}.
* *
* <p>All four values are set by computing their values from the specified milliseconds * <p>All four values are set by computing their values from the specified milliseconds
* and are available using the <code>get</code> methods of the created {@link Duration}. * and are available using the {@code get} methods of the created {@link Duration}.
* The values conform to and are defined by:</p> * The values conform to and are defined by:
* <ul> * <ul>
* <li>ISO 8601:2000(E) Section 5.5.3.2 Alternative format</li> * <li>ISO 8601:2000(E) Section 5.5.3.2 Alternative format</li>
* <li><a href="http://www.w3.org/TR/xmlschema-2/#isoformats"> * <li><a href="http://www.w3.org/TR/xmlschema-2/#isoformats">
@ -440,13 +441,13 @@ public abstract class DatatypeFactory {
* {@link java.util.Calendar#DATE} = 1, etc. * {@link java.util.Calendar#DATE} = 1, etc.
* This is important as there are variations in the Gregorian Calendar, * This is important as there are variations in the Gregorian Calendar,
* e.g. leap years have different days in the month = {@link java.util.Calendar#FEBRUARY} * e.g. leap years have different days in the month = {@link java.util.Calendar#FEBRUARY}
* so the result of {@link Duration#getDays()} can be influenced.</p> * so the result of {@link Duration#getDays()} can be influenced.
* *
* <p>Any remaining milliseconds after determining the day, hour, minute and second are discarded.</p> * <p>Any remaining milliseconds after determining the day, hour, minute and second are discarded.
* *
* @param durationInMilliseconds Milliseconds of <code>Duration</code> to create. * @param durationInMilliseconds Milliseconds of {@code Duration} to create.
* *
* @return New <code>Duration</code> created with the specified <code>durationInMilliseconds</code>. * @return New {@code Duration} created with the specified {@code durationInMilliseconds}.
* *
* @see <a href="http://www.w3.org/TR/xpath-datamodel#dayTimeDuration"> * @see <a href="http://www.w3.org/TR/xpath-datamodel#dayTimeDuration">
* XQuery 1.0 and XPath 2.0 Data Model, xdt:dayTimeDuration</a> * XQuery 1.0 and XPath 2.0 Data Model, xdt:dayTimeDuration</a>
@ -457,34 +458,34 @@ public abstract class DatatypeFactory {
} }
/** /**
* <p>Create a <code>Duration</code> of type <code>xdt:dayTimeDuration</code> using the specified * Create a {@code Duration} of type {@code xdt:dayTimeDuration} using the specified
* <code>day</code>, <code>hour</code>, <code>minute</code> and <code>second</code> as defined in * {@code day}, {@code hour}, {@code minute} and {@code second} as defined in
* <a href="http://www.w3.org/TR/xpath-datamodel#dayTimeDuration"> * <a href="http://www.w3.org/TR/xpath-datamodel#dayTimeDuration">
* XQuery 1.0 and XPath 2.0 Data Model, xdt:dayTimeDuration</a>.</p> * XQuery 1.0 and XPath 2.0 Data Model, xdt:dayTimeDuration</a>.
* *
* <p>The datatype <code>xdt:dayTimeDuration</code> is a subtype of <code>xs:duration</code> * <p>The datatype {@code xdt:dayTimeDuration} is a subtype of {@code xs:duration}
* whose lexical representation contains only day, hour, minute, and second components. * whose lexical representation contains only day, hour, minute, and second components.
* This datatype resides in the namespace <code>http://www.w3.org/2003/11/xpath-datatypes</code>.</p> * This datatype resides in the namespace {@code http://www.w3.org/2003/11/xpath-datatypes}.
* *
* <p>The XML Schema specification states that values can be of an arbitrary size. * <p>The XML Schema specification states that values can be of an arbitrary size.
* Implementations may chose not to or be incapable of supporting arbitrarily large and/or small values. * Implementations may chose not to or be incapable of supporting arbitrarily large and/or small values.
* An {@link UnsupportedOperationException} will be thrown with a message indicating implementation limits * An {@link UnsupportedOperationException} will be thrown with a message indicating implementation limits
* if implementation capacities are exceeded.</p> * if implementation capacities are exceeded.
* *
* <p>A <code>null</code> value indicates that field is not set.</p> * <p>A {@code null} value indicates that field is not set.
* *
* @param isPositive Set to <code>false</code> to create a negative duration. When the length * @param isPositive Set to {@code false} to create a negative duration. When the length
* of the duration is zero, this parameter will be ignored. * of the duration is zero, this parameter will be ignored.
* @param day Day of <code>Duration</code>. * @param day Day of {@code Duration}.
* @param hour Hour of <code>Duration</code>. * @param hour Hour of {@code Duration}.
* @param minute Minute of <code>Duration</code>. * @param minute Minute of {@code Duration}.
* @param second Second of <code>Duration</code>. * @param second Second of {@code Duration}.
* *
* @return New <code>Duration</code> created with the specified <code>day</code>, <code>hour</code>, <code>minute</code> * @return New {@code Duration} created with the specified {@code day}, {@code hour}, {@code minute}
* and <code>second</code>. * and {@code second}.
* *
* @throws IllegalArgumentException If the values are not a valid representation of a * @throws IllegalArgumentException If the values are not a valid representation of a
* <code>Duration</code>: if all the fields (day, hour, ...) are null or * {@code Duration}: if all the fields (day, hour, ...) are null or
* if any of the fields is negative. * if any of the fields is negative.
* @throws UnsupportedOperationException If implementation cannot support requested values. * @throws UnsupportedOperationException If implementation cannot support requested values.
*/ */
@ -507,29 +508,29 @@ public abstract class DatatypeFactory {
} }
/** /**
* <p>Create a <code>Duration</code> of type <code>xdt:dayTimeDuration</code> using the specified * Create a {@code Duration} of type {@code xdt:dayTimeDuration} using the specified
* <code>day</code>, <code>hour</code>, <code>minute</code> and <code>second</code> as defined in * {@code day}, {@code hour}, {@code minute} and {@code second} as defined in
* <a href="http://www.w3.org/TR/xpath-datamodel#dayTimeDuration"> * <a href="http://www.w3.org/TR/xpath-datamodel#dayTimeDuration">
* XQuery 1.0 and XPath 2.0 Data Model, xdt:dayTimeDuration</a>.</p> * XQuery 1.0 and XPath 2.0 Data Model, xdt:dayTimeDuration</a>.
* *
* <p>The datatype <code>xdt:dayTimeDuration</code> is a subtype of <code>xs:duration</code> * <p>The datatype {@code xdt:dayTimeDuration} is a subtype of {@code xs:duration}
* whose lexical representation contains only day, hour, minute, and second components. * whose lexical representation contains only day, hour, minute, and second components.
* This datatype resides in the namespace <code>http://www.w3.org/2003/11/xpath-datatypes</code>.</p> * This datatype resides in the namespace {@code http://www.w3.org/2003/11/xpath-datatypes}.
* *
* <p>A {@link DatatypeConstants#FIELD_UNDEFINED} value indicates that field is not set.</p> * <p>A {@link DatatypeConstants#FIELD_UNDEFINED} value indicates that field is not set.
* *
* @param isPositive Set to <code>false</code> to create a negative duration. When the length * @param isPositive Set to {@code false} to create a negative duration. When the length
* of the duration is zero, this parameter will be ignored. * of the duration is zero, this parameter will be ignored.
* @param day Day of <code>Duration</code>. * @param day Day of {@code Duration}.
* @param hour Hour of <code>Duration</code>. * @param hour Hour of {@code Duration}.
* @param minute Minute of <code>Duration</code>. * @param minute Minute of {@code Duration}.
* @param second Second of <code>Duration</code>. * @param second Second of {@code Duration}.
* *
* @return New <code>Duration</code> created with the specified <code>day</code>, <code>hour</code>, <code>minute</code> * @return New {@code Duration} created with the specified {@code day}, {@code hour}, {@code minute}
* and <code>second</code>. * and {@code second}.
* *
* @throws IllegalArgumentException If the values are not a valid representation of a * @throws IllegalArgumentException If the values are not a valid representation of a
* <code>Duration</code>: if any of the fields (day, hour, ...) is negative. * {@code Duration}: if any of the fields (day, hour, ...) is negative.
*/ */
public Duration newDurationDayTime( public Duration newDurationDayTime(
final boolean isPositive, final boolean isPositive,
@ -548,28 +549,30 @@ public abstract class DatatypeFactory {
} }
/** /**
* <p>Create a <code>Duration</code> of type <code>xdt:yearMonthDuration</code> by parsing its <code>String</code> representation, * Create a {@code Duration} of type {@code xdt:yearMonthDuration}
* by parsing its {@code String} representation,
* "<em>PnYnM</em>", <a href="http://www.w3.org/TR/xpath-datamodel#yearMonthDuration"> * "<em>PnYnM</em>", <a href="http://www.w3.org/TR/xpath-datamodel#yearMonthDuration">
* XQuery 1.0 and XPath 2.0 Data Model, xdt:yearMonthDuration</a>.</p> * XQuery 1.0 and XPath 2.0 Data Model, xdt:yearMonthDuration</a>.
* *
* <p>The datatype <code>xdt:yearMonthDuration</code> is a subtype of <code>xs:duration</code> * <p>The datatype {@code xdt:yearMonthDuration} is a subtype of {@code xs:duration}
* whose lexical representation contains only year and month components. * whose lexical representation contains only year and month components.
* This datatype resides in the namespace {@link javax.xml.XMLConstants#W3C_XPATH_DATATYPE_NS_URI}.</p> * This datatype resides in the namespace {@link javax.xml.XMLConstants#W3C_XPATH_DATATYPE_NS_URI}.
* *
* <p>Both values are set and available from the created {@link Duration}</p> * <p>Both values are set and available from the created {@link Duration}
* *
* <p>The XML Schema specification states that values can be of an arbitrary size. * <p>The XML Schema specification states that values can be of an arbitrary size.
* Implementations may chose not to or be incapable of supporting arbitrarily large and/or small values. * Implementations may chose not to or be incapable of supporting
* An {@link UnsupportedOperationException} will be thrown with a message indicating implementation limits * arbitrarily large and/or small values. An {@link UnsupportedOperationException}
* if implementation capacities are exceeded.</p> * will be thrown with a message indicating implementation limits
* if implementation capacities are exceeded.
* *
* @param lexicalRepresentation Lexical representation of a duration. * @param lexicalRepresentation Lexical representation of a duration.
* *
* @return New <code>Duration</code> created using the specified <code>lexicalRepresentation</code>. * @return New {@code Duration} created using the specified {@code lexicalRepresentation}.
* *
* @throws IllegalArgumentException If <code>lexicalRepresentation</code> is not a valid representation of a <code>Duration</code> expressed only in terms of years and months. * @throws IllegalArgumentException If {@code lexicalRepresentation} is not a valid representation of a {@code Duration} expressed only in terms of years and months.
* @throws UnsupportedOperationException If implementation cannot support requested values. * @throws UnsupportedOperationException If implementation cannot support requested values.
* @throws NullPointerException If <code>lexicalRepresentation</code> is <code>null</code>. * @throws NullPointerException If {@code lexicalRepresentation} is {@code null}.
*/ */
public Duration newDurationYearMonth( public Duration newDurationYearMonth(
final String lexicalRepresentation) { final String lexicalRepresentation) {
@ -594,17 +597,18 @@ public abstract class DatatypeFactory {
} }
/** /**
* <p>Create a <code>Duration</code> of type <code>xdt:yearMonthDuration</code> using the specified milliseconds as defined in * Create a {@code Duration} of type {@code xdt:yearMonthDuration}
* using the specified milliseconds as defined in
* <a href="http://www.w3.org/TR/xpath-datamodel#yearMonthDuration"> * <a href="http://www.w3.org/TR/xpath-datamodel#yearMonthDuration">
* XQuery 1.0 and XPath 2.0 Data Model, xdt:yearMonthDuration</a>.</p> * XQuery 1.0 and XPath 2.0 Data Model, xdt:yearMonthDuration</a>.
* *
* <p>The datatype <code>xdt:yearMonthDuration</code> is a subtype of <code>xs:duration</code> * <p>The datatype {@code xdt:yearMonthDuration} is a subtype of {@code xs:duration}
* whose lexical representation contains only year and month components. * whose lexical representation contains only year and month components.
* This datatype resides in the namespace {@link javax.xml.XMLConstants#W3C_XPATH_DATATYPE_NS_URI}.</p> * This datatype resides in the namespace {@link javax.xml.XMLConstants#W3C_XPATH_DATATYPE_NS_URI}.
* *
* <p>Both values are set by computing their values from the specified milliseconds * <p>Both values are set by computing their values from the specified milliseconds
* and are available using the <code>get</code> methods of the created {@link Duration}. * and are available using the {@code get} methods of the created {@link Duration}.
* The values conform to and are defined by:</p> * The values conform to and are defined by:
* <ul> * <ul>
* <li>ISO 8601:2000(E) Section 5.5.3.2 Alternative format</li> * <li>ISO 8601:2000(E) Section 5.5.3.2 Alternative format</li>
* <li><a href="http://www.w3.org/TR/xmlschema-2/#isoformats"> * <li><a href="http://www.w3.org/TR/xmlschema-2/#isoformats">
@ -619,13 +623,13 @@ public abstract class DatatypeFactory {
* {@link java.util.Calendar#DATE} = 1, etc. * {@link java.util.Calendar#DATE} = 1, etc.
* This is important as there are variations in the Gregorian Calendar, * This is important as there are variations in the Gregorian Calendar,
* e.g. leap years have different days in the month = {@link java.util.Calendar#FEBRUARY} * e.g. leap years have different days in the month = {@link java.util.Calendar#FEBRUARY}
* so the result of {@link Duration#getMonths()} can be influenced.</p> * so the result of {@link Duration#getMonths()} can be influenced.
* *
* <p>Any remaining milliseconds after determining the year and month are discarded.</p> * <p>Any remaining milliseconds after determining the year and month are discarded.
* *
* @param durationInMilliseconds Milliseconds of <code>Duration</code> to create. * @param durationInMilliseconds Milliseconds of {@code Duration} to create.
* *
* @return New <code>Duration</code> created using the specified <code>durationInMilliseconds</code>. * @return New {@code Duration} created using the specified {@code durationInMilliseconds}.
*/ */
public Duration newDurationYearMonth( public Duration newDurationYearMonth(
final long durationInMilliseconds) { final long durationInMilliseconds) {
@ -646,27 +650,27 @@ public abstract class DatatypeFactory {
} }
/** /**
* <p>Create a <code>Duration</code> of type <code>xdt:yearMonthDuration</code> using the specified * Create a {@code Duration} of type {@code xdt:yearMonthDuration} using the specified
* <code>year</code> and <code>month</code> as defined in * {@code year} and {@code month} as defined in
* <a href="http://www.w3.org/TR/xpath-datamodel#yearMonthDuration"> * <a href="http://www.w3.org/TR/xpath-datamodel#yearMonthDuration">
* XQuery 1.0 and XPath 2.0 Data Model, xdt:yearMonthDuration</a>.</p> * XQuery 1.0 and XPath 2.0 Data Model, xdt:yearMonthDuration</a>.
* *
* <p>The XML Schema specification states that values can be of an arbitrary size. * <p>The XML Schema specification states that values can be of an arbitrary size.
* Implementations may chose not to or be incapable of supporting arbitrarily large and/or small values. * Implementations may chose not to or be incapable of supporting arbitrarily large and/or small values.
* An {@link UnsupportedOperationException} will be thrown with a message indicating implementation limits * An {@link UnsupportedOperationException} will be thrown with a message indicating implementation limits
* if implementation capacities are exceeded.</p> * if implementation capacities are exceeded.
* *
* <p>A <code>null</code> value indicates that field is not set.</p> * <p>A {@code null} value indicates that field is not set.
* *
* @param isPositive Set to <code>false</code> to create a negative duration. When the length * @param isPositive Set to {@code false} to create a negative duration. When the length
* of the duration is zero, this parameter will be ignored. * of the duration is zero, this parameter will be ignored.
* @param year Year of <code>Duration</code>. * @param year Year of {@code Duration}.
* @param month Month of <code>Duration</code>. * @param month Month of {@code Duration}.
* *
* @return New <code>Duration</code> created using the specified <code>year</code> and <code>month</code>. * @return New {@code Duration} created using the specified {@code year} and {@code month}.
* *
* @throws IllegalArgumentException If the values are not a valid representation of a * @throws IllegalArgumentException If the values are not a valid representation of a
* <code>Duration</code>: if all of the fields (year, month) are null or * {@code Duration}: if all of the fields (year, month) are null or
* if any of the fields is negative. * if any of the fields is negative.
* @throws UnsupportedOperationException If implementation cannot support requested values. * @throws UnsupportedOperationException If implementation cannot support requested values.
*/ */
@ -687,22 +691,22 @@ public abstract class DatatypeFactory {
} }
/** /**
* <p>Create a <code>Duration</code> of type <code>xdt:yearMonthDuration</code> using the specified * Create a {@code Duration} of type {@code xdt:yearMonthDuration} using the specified
* <code>year</code> and <code>month</code> as defined in * {@code year} and {@code month} as defined in
* <a href="http://www.w3.org/TR/xpath-datamodel#yearMonthDuration"> * <a href="http://www.w3.org/TR/xpath-datamodel#yearMonthDuration">
* XQuery 1.0 and XPath 2.0 Data Model, xdt:yearMonthDuration</a>.</p> * XQuery 1.0 and XPath 2.0 Data Model, xdt:yearMonthDuration</a>.
* *
* <p>A {@link DatatypeConstants#FIELD_UNDEFINED} value indicates that field is not set.</p> * <p>A {@link DatatypeConstants#FIELD_UNDEFINED} value indicates that field is not set.
* *
* @param isPositive Set to <code>false</code> to create a negative duration. When the length * @param isPositive Set to {@code false} to create a negative duration. When the length
* of the duration is zero, this parameter will be ignored. * of the duration is zero, this parameter will be ignored.
* @param year Year of <code>Duration</code>. * @param year Year of {@code Duration}.
* @param month Month of <code>Duration</code>. * @param month Month of {@code Duration}.
* *
* @return New <code>Duration</code> created using the specified <code>year</code> and <code>month</code>. * @return New {@code Duration} created using the specified {@code year} and {@code month}.
* *
* @throws IllegalArgumentException If the values are not a valid representation of a * @throws IllegalArgumentException If the values are not a valid representation of a
* <code>Duration</code>: if any of the fields (year, month) is negative. * {@code Duration}: if any of the fields (year, month) is negative.
*/ */
public Duration newDurationYearMonth( public Duration newDurationYearMonth(
final boolean isPositive, final boolean isPositive,
@ -716,44 +720,44 @@ public abstract class DatatypeFactory {
} }
/** /**
* <p>Create a new instance of an <code>XMLGregorianCalendar</code>.</p> * Create a new instance of an {@code XMLGregorianCalendar}.
* *
* <p>All date/time datatype fields set to {@link DatatypeConstants#FIELD_UNDEFINED} or null.</p> * <p>All date/time datatype fields set to {@link DatatypeConstants#FIELD_UNDEFINED} or null.
* *
* @return New <code>XMLGregorianCalendar</code> with all date/time datatype fields set to * @return New {@code XMLGregorianCalendar} with all date/time datatype fields set to
* {@link DatatypeConstants#FIELD_UNDEFINED} or null. * {@link DatatypeConstants#FIELD_UNDEFINED} or null.
*/ */
public abstract XMLGregorianCalendar newXMLGregorianCalendar(); public abstract XMLGregorianCalendar newXMLGregorianCalendar();
/** /**
* <p>Create a new XMLGregorianCalendar by parsing the String as a lexical representation.</p> * Create a new XMLGregorianCalendar by parsing the String as a lexical representation.
* *
* <p>Parsing the lexical string representation is defined in * <p>Parsing the lexical string representation is defined in
* <a href="http://www.w3.org/TR/xmlschema-2/#dateTime-order">XML Schema 1.0 Part 2, Section 3.2.[7-14].1, * <a href="http://www.w3.org/TR/xmlschema-2/#dateTime-order">XML Schema 1.0 Part 2, Section 3.2.[7-14].1,
* <em>Lexical Representation</em>.</a></p> * <em>Lexical Representation</em>.</a>
* *
* <p>The string representation may not have any leading and trailing whitespaces.</p> * <p>The string representation may not have any leading and trailing whitespaces.
* *
* <p>The parsing is done field by field so that * <p>The parsing is done field by field so that
* the following holds for any lexically correct String x:</p> * the following holds for any lexically correct String x:
* <pre> * <pre>
* newXMLGregorianCalendar(x).toXMLFormat().equals(x) * newXMLGregorianCalendar(x).toXMLFormat().equals(x)
* </pre> * </pre>
* <p>Except for the noted lexical/canonical representation mismatches * <p>Except for the noted lexical/canonical representation mismatches
* listed in <a href="http://www.w3.org/2001/05/xmlschema-errata#e2-45"> * listed in <a href="http://www.w3.org/2001/05/xmlschema-errata#e2-45">
* XML Schema 1.0 errata, Section 3.2.7.2</a>.</p> * XML Schema 1.0 errata, Section 3.2.7.2</a>.
* *
* @param lexicalRepresentation Lexical representation of one the eight XML Schema date/time datatypes. * @param lexicalRepresentation Lexical representation of one the eight XML Schema date/time datatypes.
* *
* @return <code>XMLGregorianCalendar</code> created from the <code>lexicalRepresentation</code>. * @return {@code XMLGregorianCalendar} created from the {@code lexicalRepresentation}.
* *
* @throws IllegalArgumentException If the <code>lexicalRepresentation</code> is not a valid <code>XMLGregorianCalendar</code>. * @throws IllegalArgumentException If the {@code lexicalRepresentation} is not a valid {@code XMLGregorianCalendar}.
* @throws NullPointerException If <code>lexicalRepresentation</code> is <code>null</code>. * @throws NullPointerException If {@code lexicalRepresentation} is {@code null}.
*/ */
public abstract XMLGregorianCalendar newXMLGregorianCalendar(final String lexicalRepresentation); public abstract XMLGregorianCalendar newXMLGregorianCalendar(final String lexicalRepresentation);
/** /**
* <p>Create an <code>XMLGregorianCalendar</code> from a {@link GregorianCalendar}.</p> * Create an {@code XMLGregorianCalendar} from a {@link GregorianCalendar}.
* *
* <table border="2" rules="all" cellpadding="2"> * <table border="2" rules="all" cellpadding="2">
* <thead> * <thead>
@ -764,30 +768,30 @@ public abstract class DatatypeFactory {
* </th> * </th>
* </tr> * </tr>
* <tr> * <tr>
* <th><code>java.util.GregorianCalendar</code> field</th> * <th>{@code java.util.GregorianCalendar} field</th>
* <th><code>javax.xml.datatype.XMLGregorianCalendar</code> field</th> * <th>{@code javax.xml.datatype.XMLGregorianCalendar} field</th>
* </tr> * </tr>
* </thead> * </thead>
* <tbody> * <tbody>
* <tr> * <tr>
* <td><code>ERA == GregorianCalendar.BC ? -YEAR : YEAR</code></td> * <td>{@code ERA == GregorianCalendar.BC ? -YEAR : YEAR}</td>
* <td>{@link XMLGregorianCalendar#setYear(int year)}</td> * <td>{@link XMLGregorianCalendar#setYear(int year)}</td>
* </tr> * </tr>
* <tr> * <tr>
* <td><code>MONTH + 1</code></td> * <td>{@code MONTH + 1}</td>
* <td>{@link XMLGregorianCalendar#setMonth(int month)}</td> * <td>{@link XMLGregorianCalendar#setMonth(int month)}</td>
* </tr> * </tr>
* <tr> * <tr>
* <td><code>DAY_OF_MONTH</code></td> * <td>{@code DAY_OF_MONTH}</td>
* <td>{@link XMLGregorianCalendar#setDay(int day)}</td> * <td>{@link XMLGregorianCalendar#setDay(int day)}</td>
* </tr> * </tr>
* <tr> * <tr>
* <td><code>HOUR_OF_DAY, MINUTE, SECOND, MILLISECOND</code></td> * <td>{@code HOUR_OF_DAY, MINUTE, SECOND, MILLISECOND}</td>
* <td>{@link XMLGregorianCalendar#setTime(int hour, int minute, int second, BigDecimal fractional)}</td> * <td>{@link XMLGregorianCalendar#setTime(int hour, int minute, int second, BigDecimal fractional)}</td>
* </tr> * </tr>
* <tr> * <tr>
* <td> * <td>
* <code>(ZONE_OFFSET + DST_OFFSET) / (60*1000)</code><br/> * {@code (ZONE_OFFSET + DST_OFFSET) / (60*1000)}<br>
* <em>(in minutes)</em> * <em>(in minutes)</em>
* </td> * </td>
* <td>{@link XMLGregorianCalendar#setTimezone(int offset)}<sup><em>*</em></sup> * <td>{@link XMLGregorianCalendar#setTimezone(int offset)}<sup><em>*</em></sup>
@ -796,49 +800,50 @@ public abstract class DatatypeFactory {
* </tbody> * </tbody>
* </table> * </table>
* <p><em>*</em>conversion loss of information. It is not possible to represent * <p><em>*</em>conversion loss of information. It is not possible to represent
* a <code>java.util.GregorianCalendar</code> daylight savings timezone id in the * a {@code java.util.GregorianCalendar} daylight savings timezone id in the
* XML Schema 1.0 date/time datatype representation.</p> * XML Schema 1.0 date/time datatype representation.
* *
* <p>To compute the return value's <code>TimeZone</code> field, * <p>To compute the return value's {@code TimeZone} field,
* <ul> * <ul>
* <li>when <code>this.getTimezone() != FIELD_UNDEFINED</code>, * <li>when {@code this.getTimezone() != FIELD_UNDEFINED},
* create a <code>java.util.TimeZone</code> with a custom timezone id * create a {@code java.util.TimeZone} with a custom timezone id
* using the <code>this.getTimezone()</code>.</li> * using the {@code this.getTimezone()}.</li>
* <li>else use the <code>GregorianCalendar</code> default timezone value * <li>else use the {@code GregorianCalendar} default timezone value
* for the host is defined as specified by * for the host is defined as specified by
* <code>java.util.TimeZone.getDefault()</code>.</li></p> * {@code java.util.TimeZone.getDefault()}.</li>
* </ul>
* *
* @param cal <code>java.util.GregorianCalendar</code> used to create <code>XMLGregorianCalendar</code> * @param cal {@code java.util.GregorianCalendar} used to create {@code XMLGregorianCalendar}
* *
* @return <code>XMLGregorianCalendar</code> created from <code>java.util.GregorianCalendar</code> * @return {@code XMLGregorianCalendar} created from {@code java.util.GregorianCalendar}
* *
* @throws NullPointerException If <code>cal</code> is <code>null</code>. * @throws NullPointerException If {@code cal} is {@code null}.
*/ */
public abstract XMLGregorianCalendar newXMLGregorianCalendar(final GregorianCalendar cal); public abstract XMLGregorianCalendar newXMLGregorianCalendar(final GregorianCalendar cal);
/** /**
* <p>Constructor allowing for complete value spaces allowed by * Constructor allowing for complete value spaces allowed by
* W3C XML Schema 1.0 recommendation for xsd:dateTime and related * W3C XML Schema 1.0 recommendation for xsd:dateTime and related
* builtin datatypes. Note that <code>year</code> parameter supports * builtin datatypes. Note that {@code year} parameter supports
* arbitrarily large numbers and fractionalSecond has infinite * arbitrarily large numbers and fractionalSecond has infinite
* precision.</p> * precision.
* *
* <p>A <code>null</code> value indicates that field is not set.</p> * <p>A {@code null} value indicates that field is not set.
* *
* @param year of <code>XMLGregorianCalendar</code> to be created. * @param year of {@code XMLGregorianCalendar} to be created.
* @param month of <code>XMLGregorianCalendar</code> to be created. * @param month of {@code XMLGregorianCalendar} to be created.
* @param day of <code>XMLGregorianCalendar</code> to be created. * @param day of {@code XMLGregorianCalendar} to be created.
* @param hour of <code>XMLGregorianCalendar</code> to be created. * @param hour of {@code XMLGregorianCalendar} to be created.
* @param minute of <code>XMLGregorianCalendar</code> to be created. * @param minute of {@code XMLGregorianCalendar} to be created.
* @param second of <code>XMLGregorianCalendar</code> to be created. * @param second of {@code XMLGregorianCalendar} to be created.
* @param fractionalSecond of <code>XMLGregorianCalendar</code> to be created. * @param fractionalSecond of {@code XMLGregorianCalendar} to be created.
* @param timezone of <code>XMLGregorianCalendar</code> to be created. * @param timezone of {@code XMLGregorianCalendar} to be created.
* *
* @return <code>XMLGregorianCalendar</code> created from specified values. * @return {@code XMLGregorianCalendar} created from specified values.
* *
* @throws IllegalArgumentException If any individual parameter's value is outside the maximum value constraint for the field * @throws IllegalArgumentException If any individual parameter's value is outside the maximum value constraint for the field
* as determined by the Date/Time Data Mapping table in {@link XMLGregorianCalendar} * as determined by the Date/Time Data Mapping table in {@link XMLGregorianCalendar}
* or if the composite values constitute an invalid <code>XMLGregorianCalendar</code> instance * or if the composite values constitute an invalid {@code XMLGregorianCalendar} instance
* as determined by {@link XMLGregorianCalendar#isValid()}. * as determined by {@link XMLGregorianCalendar#isValid()}.
*/ */
public abstract XMLGregorianCalendar newXMLGregorianCalendar( public abstract XMLGregorianCalendar newXMLGregorianCalendar(
@ -852,29 +857,29 @@ public abstract class DatatypeFactory {
final int timezone); final int timezone);
/** /**
* <p>Constructor of value spaces that a * Constructor of value spaces that a
* <code>java.util.GregorianCalendar</code> instance would need to convert to an * {@code java.util.GregorianCalendar} instance would need to convert to an
* <code>XMLGregorianCalendar</code> instance.</p> * {@code XMLGregorianCalendar} instance.
* *
* <p><code>XMLGregorianCalendar eon</code> and * <p>{@code XMLGregorianCalendar eon} and
* <code>fractionalSecond</code> are set to <code>null</code></p> * {@code fractionalSecond} are set to {@code null}
* *
* <p>A {@link DatatypeConstants#FIELD_UNDEFINED} value indicates that field is not set.</p> * <p>A {@link DatatypeConstants#FIELD_UNDEFINED} value indicates that field is not set.
* *
* @param year of <code>XMLGregorianCalendar</code> to be created. * @param year of {@code XMLGregorianCalendar} to be created.
* @param month of <code>XMLGregorianCalendar</code> to be created. * @param month of {@code XMLGregorianCalendar} to be created.
* @param day of <code>XMLGregorianCalendar</code> to be created. * @param day of {@code XMLGregorianCalendar} to be created.
* @param hour of <code>XMLGregorianCalendar</code> to be created. * @param hour of {@code XMLGregorianCalendar} to be created.
* @param minute of <code>XMLGregorianCalendar</code> to be created. * @param minute of {@code XMLGregorianCalendar} to be created.
* @param second of <code>XMLGregorianCalendar</code> to be created. * @param second of {@code XMLGregorianCalendar} to be created.
* @param millisecond of <code>XMLGregorianCalendar</code> to be created. * @param millisecond of {@code XMLGregorianCalendar} to be created.
* @param timezone of <code>XMLGregorianCalendar</code> to be created. * @param timezone of {@code XMLGregorianCalendar} to be created.
* *
* @return <code>XMLGregorianCalendar</code> created from specified values. * @return {@code XMLGregorianCalendar} created from specified values.
* *
* @throws IllegalArgumentException If any individual parameter's value is outside the maximum value constraint for the field * @throws IllegalArgumentException If any individual parameter's value is outside the maximum value constraint for the field
* as determined by the Date/Time Data Mapping table in {@link XMLGregorianCalendar} * as determined by the Date/Time Data Mapping table in {@link XMLGregorianCalendar}
* or if the composite values constitute an invalid <code>XMLGregorianCalendar</code> instance * or if the composite values constitute an invalid {@code XMLGregorianCalendar} instance
* as determined by {@link XMLGregorianCalendar#isValid()}. * as determined by {@link XMLGregorianCalendar#isValid()}.
*/ */
public XMLGregorianCalendar newXMLGregorianCalendar( public XMLGregorianCalendar newXMLGregorianCalendar(
@ -918,26 +923,26 @@ public abstract class DatatypeFactory {
} }
/** /**
* <p>Create a Java representation of XML Schema builtin datatype <code>date</code> or <code>g*</code>.</p> * Create a Java representation of XML Schema builtin datatype {@code date} or {@code g*}.
* *
* <p>For example, an instance of <code>gYear</code> can be created invoking this factory * <p>For example, an instance of {@code gYear} can be created invoking this factory
* with <code>month</code> and <code>day</code> parameters set to * with {@code month} and {@code day} parameters set to
* {@link DatatypeConstants#FIELD_UNDEFINED}.</p> * {@link DatatypeConstants#FIELD_UNDEFINED}.
* *
* <p>A {@link DatatypeConstants#FIELD_UNDEFINED} value indicates that field is not set.</p> * <p>A {@link DatatypeConstants#FIELD_UNDEFINED} value indicates that field is not set.
* *
* @param year of <code>XMLGregorianCalendar</code> to be created. * @param year of {@code XMLGregorianCalendar} to be created.
* @param month of <code>XMLGregorianCalendar</code> to be created. * @param month of {@code XMLGregorianCalendar} to be created.
* @param day of <code>XMLGregorianCalendar</code> to be created. * @param day of {@code XMLGregorianCalendar} to be created.
* @param timezone offset in minutes. {@link DatatypeConstants#FIELD_UNDEFINED} indicates optional field is not set. * @param timezone offset in minutes. {@link DatatypeConstants#FIELD_UNDEFINED} indicates optional field is not set.
* *
* @return <code>XMLGregorianCalendar</code> created from parameter values. * @return {@code XMLGregorianCalendar} created from parameter values.
* *
* @see DatatypeConstants#FIELD_UNDEFINED * @see DatatypeConstants#FIELD_UNDEFINED
* *
* @throws IllegalArgumentException If any individual parameter's value is outside the maximum value constraint for the field * @throws IllegalArgumentException If any individual parameter's value is outside the maximum value constraint for the field
* as determined by the Date/Time Data Mapping table in {@link XMLGregorianCalendar} * as determined by the Date/Time Data Mapping table in {@link XMLGregorianCalendar}
* or if the composite values constitute an invalid <code>XMLGregorianCalendar</code> instance * or if the composite values constitute an invalid {@code XMLGregorianCalendar} instance
* as determined by {@link XMLGregorianCalendar#isValid()}. * as determined by {@link XMLGregorianCalendar#isValid()}.
*/ */
public XMLGregorianCalendar newXMLGregorianCalendarDate( public XMLGregorianCalendar newXMLGregorianCalendarDate(
@ -958,20 +963,20 @@ public abstract class DatatypeFactory {
} }
/** /**
* <p>Create a Java instance of XML Schema builtin datatype <code>time</code>.</p> * Create a Java instance of XML Schema builtin datatype {@code time}.
* *
* <p>A {@link DatatypeConstants#FIELD_UNDEFINED} value indicates that field is not set.</p> * <p>A {@link DatatypeConstants#FIELD_UNDEFINED} value indicates that field is not set.
* *
* @param hours number of hours * @param hours number of hours
* @param minutes number of minutes * @param minutes number of minutes
* @param seconds number of seconds * @param seconds number of seconds
* @param timezone offset in minutes. {@link DatatypeConstants#FIELD_UNDEFINED} indicates optional field is not set. * @param timezone offset in minutes. {@link DatatypeConstants#FIELD_UNDEFINED} indicates optional field is not set.
* *
* @return <code>XMLGregorianCalendar</code> created from parameter values. * @return {@code XMLGregorianCalendar} created from parameter values.
* *
* @throws IllegalArgumentException If any individual parameter's value is outside the maximum value constraint for the field * @throws IllegalArgumentException If any individual parameter's value is outside the maximum value constraint for the field
* as determined by the Date/Time Data Mapping table in {@link XMLGregorianCalendar} * as determined by the Date/Time Data Mapping table in {@link XMLGregorianCalendar}
* or if the composite values constitute an invalid <code>XMLGregorianCalendar</code> instance * or if the composite values constitute an invalid {@code XMLGregorianCalendar} instance
* as determined by {@link XMLGregorianCalendar#isValid()}. * as determined by {@link XMLGregorianCalendar#isValid()}.
* *
* @see DatatypeConstants#FIELD_UNDEFINED * @see DatatypeConstants#FIELD_UNDEFINED
@ -994,24 +999,24 @@ public abstract class DatatypeFactory {
} }
/** /**
* <p>Create a Java instance of XML Schema builtin datatype time.</p> * Create a Java instance of XML Schema builtin datatype time.
* *
* <p>A <code>null</code> value indicates that field is not set.</p> * <p>A {@code null} value indicates that field is not set.
* <p>A {@link DatatypeConstants#FIELD_UNDEFINED} value indicates that field is not set.</p> * <p>A {@link DatatypeConstants#FIELD_UNDEFINED} value indicates that field is not set.
* *
* @param hours number of hours * @param hours number of hours
* @param minutes number of minutes * @param minutes number of minutes
* @param seconds number of seconds * @param seconds number of seconds
* @param fractionalSecond value of <code>null</code> indicates that this optional field is not set. * @param fractionalSecond value of {@code null} indicates that this optional field is not set.
* @param timezone offset in minutes. {@link DatatypeConstants#FIELD_UNDEFINED} indicates optional field is not set. * @param timezone offset in minutes. {@link DatatypeConstants#FIELD_UNDEFINED} indicates optional field is not set.
* *
* @return <code>XMLGregorianCalendar</code> created from parameter values. * @return {@code XMLGregorianCalendar} created from parameter values.
* *
* @see DatatypeConstants#FIELD_UNDEFINED * @see DatatypeConstants#FIELD_UNDEFINED
* *
* @throws IllegalArgumentException If any individual parameter's value is outside the maximum value constraint for the field * @throws IllegalArgumentException If any individual parameter's value is outside the maximum value constraint for the field
* as determined by the Date/Time Data Mapping table in {@link XMLGregorianCalendar} * as determined by the Date/Time Data Mapping table in {@link XMLGregorianCalendar}
* or if the composite values constitute an invalid <code>XMLGregorianCalendar</code> instance * or if the composite values constitute an invalid {@code XMLGregorianCalendar} instance
* as determined by {@link XMLGregorianCalendar#isValid()}. * as determined by {@link XMLGregorianCalendar#isValid()}.
*/ */
public XMLGregorianCalendar newXMLGregorianCalendarTime( public XMLGregorianCalendar newXMLGregorianCalendarTime(
@ -1033,9 +1038,9 @@ public abstract class DatatypeFactory {
} }
/** /**
* <p>Create a Java instance of XML Schema builtin datatype time.</p> * Create a Java instance of XML Schema builtin datatype time.
* *
* <p>A {@link DatatypeConstants#FIELD_UNDEFINED} value indicates that field is not set.</p> * <p>A {@link DatatypeConstants#FIELD_UNDEFINED} value indicates that field is not set.
* *
* @param hours number of hours * @param hours number of hours
* @param minutes number of minutes * @param minutes number of minutes
@ -1043,13 +1048,13 @@ public abstract class DatatypeFactory {
* @param milliseconds number of milliseconds * @param milliseconds number of milliseconds
* @param timezone offset in minutes. {@link DatatypeConstants#FIELD_UNDEFINED} indicates optional field is not set. * @param timezone offset in minutes. {@link DatatypeConstants#FIELD_UNDEFINED} indicates optional field is not set.
* *
* @return <code>XMLGregorianCalendar</code> created from parameter values. * @return {@code XMLGregorianCalendar} created from parameter values.
* *
* @see DatatypeConstants#FIELD_UNDEFINED * @see DatatypeConstants#FIELD_UNDEFINED
* *
* @throws IllegalArgumentException If any individual parameter's value is outside the maximum value constraint for the field * @throws IllegalArgumentException If any individual parameter's value is outside the maximum value constraint for the field
* as determined by the Date/Time Data Mapping table in {@link XMLGregorianCalendar} * as determined by the Date/Time Data Mapping table in {@link XMLGregorianCalendar}
* or if the composite values constitute an invalid <code>XMLGregorianCalendar</code> instance * or if the composite values constitute an invalid {@code XMLGregorianCalendar} instance
* as determined by {@link XMLGregorianCalendar#isValid()}. * as determined by {@link XMLGregorianCalendar#isValid()}.
*/ */
public XMLGregorianCalendar newXMLGregorianCalendarTime( public XMLGregorianCalendar newXMLGregorianCalendarTime(

318
jaxp/src/java.xml/share/classes/javax/xml/datatype/Duration.java
View file

@ -35,37 +35,37 @@ import javax.xml.namespace.QName;
/** /**
* <p>Immutable representation of a time span as defined in * <p>Immutable representation of a time span as defined in
* the W3C XML Schema 1.0 specification.</p> * the W3C XML Schema 1.0 specification.
* *
* <p>A Duration object represents a period of Gregorian time, * <p>A Duration object represents a period of Gregorian time,
* which consists of six fields (years, months, days, hours, * which consists of six fields (years, months, days, hours,
* minutes, and seconds) plus a sign (+/-) field.</p> * minutes, and seconds) plus a sign (+/-) field.
* *
* <p>The first five fields have non-negative (>=0) integers or null * <p>The first five fields have non-negative ({@literal >=}0) integers or null
* (which represents that the field is not set), * (which represents that the field is not set),
* and the seconds field has a non-negative decimal or null. * and the seconds field has a non-negative decimal or null.
* A negative sign indicates a negative duration.</p> * A negative sign indicates a negative duration.
* *
* <p>This class provides a number of methods that make it easy * <p>This class provides a number of methods that make it easy
* to use for the duration datatype of XML Schema 1.0 with * to use for the duration datatype of XML Schema 1.0 with
* the errata.</p> * the errata.
* *
* <h2>Order relationship</h2> * <h2>Order relationship</h2>
* <p>Duration objects only have partial order, where two values A and B * <p>Duration objects only have partial order, where two values A and B
* maybe either:</p> * maybe either:
* <ol> * <ol>
* <li>A&lt;B (A is shorter than B) * <li>A{@literal <}B (A is shorter than B)
* <li>A&gt;B (A is longer than B) * <li>A{@literal >}B (A is longer than B)
* <li>A==B (A and B are of the same duration) * <li>A==B (A and B are of the same duration)
* <li>A&lt;>B (Comparison between A and B is indeterminate) * <li>A{@literal <>}B (Comparison between A and B is indeterminate)
* </ol> * </ol>
* *
* <p>For example, 30 days cannot be meaningfully compared to one month. * <p>For example, 30 days cannot be meaningfully compared to one month.
* The {@link #compare(Duration duration)} method implements this * The {@link #compare(Duration duration)} method implements this
* relationship.</p> * relationship.
* *
* <p>See the {@link #isLongerThan(Duration)} method for details about * <p>See the {@link #isLongerThan(Duration)} method for details about
* the order relationship among <code>Duration</code> objects.</p> * the order relationship among {@code Duration} objects.
* *
* <h2>Operations over Duration</h2> * <h2>Operations over Duration</h2>
* <p>This class provides a set of basic arithmetic operations, such * <p>This class provides a set of basic arithmetic operations, such
@ -73,20 +73,20 @@ import javax.xml.namespace.QName;
* Because durations don't have total order, an operation could * Because durations don't have total order, an operation could
* fail for some combinations of operations. For example, you cannot * fail for some combinations of operations. For example, you cannot
* subtract 15 days from 1 month. See the javadoc of those methods * subtract 15 days from 1 month. See the javadoc of those methods
* for detailed conditions where this could happen.</p> * for detailed conditions where this could happen.
* *
* <p>Also, division of a duration by a number is not provided because * <p>Also, division of a duration by a number is not provided because
* the <code>Duration</code> class can only deal with finite precision * the {@code Duration} class can only deal with finite precision
* decimal numbers. For example, one cannot represent 1 sec divided by 3.</p> * decimal numbers. For example, one cannot represent 1 sec divided by 3.
* *
* <p>However, you could substitute a division by 3 with multiplying * <p>However, you could substitute a division by 3 with multiplying
* by numbers such as 0.3 or 0.333.</p> * by numbers such as 0.3 or 0.333.
* *
* <h2>Range of allowed values</h2> * <h2>Range of allowed values</h2>
* <p> * <p>
* Because some operations of <code>Duration</code> rely on {@link Calendar} * Because some operations of {@code Duration} rely on {@link Calendar}
* even though {@link Duration} can hold very large or very small values, * even though {@link Duration} can hold very large or very small values,
* some of the methods may not work correctly on such <code>Duration</code>s. * some of the methods may not work correctly on such {@code Duration}s.
* The impacted methods document their dependency on {@link Calendar}. * The impacted methods document their dependency on {@link Calendar}.
* *
* @author <a href="mailto:Joseph.Fialli@Sun.COM">Joseph Fialli</a> * @author <a href="mailto:Joseph.Fialli@Sun.COM">Joseph Fialli</a>
@ -99,7 +99,7 @@ import javax.xml.namespace.QName;
public abstract class Duration { public abstract class Duration {
/** /**
* <p>Debugging <code>true</code> or <code>false</code>.</p> * Debugging {@code true} or {@code false}.
*/ */
private static final boolean DEBUG = true; private static final boolean DEBUG = true;
@ -107,24 +107,24 @@ public abstract class Duration {
* Default no-arg constructor. * Default no-arg constructor.
* *
* <p>Note: Always use the {@link DatatypeFactory} to * <p>Note: Always use the {@link DatatypeFactory} to
* construct an instance of <code>Duration</code>. * construct an instance of {@code Duration}.
* The constructor on this class cannot be guaranteed to * The constructor on this class cannot be guaranteed to
* produce an object with a consistent state and may be * produce an object with a consistent state and may be
* removed in the future.</p> * removed in the future.
*/ */
public Duration() { public Duration() {
} }
/** /**
* <p>Return the name of the XML Schema date/time type that this instance * Return the name of the XML Schema date/time type that this instance
* maps to. Type is computed based on fields that are set, * maps to. Type is computed based on fields that are set,
* i.e. {@link #isSet(DatatypeConstants.Field field)} == <code>true</code>.</p> * i.e. {@link #isSet(DatatypeConstants.Field field)} == {@code true}.
* *
* <table border="2" rules="all" cellpadding="2"> * <table border="2" rules="all" cellpadding="2">
* <thead> * <thead>
* <tr> * <tr>
* <th align="center" colspan="7"> * <th align="center" colspan="7">
* Required fields for XML Schema 1.0 Date/Time Datatypes.<br/> * Required fields for XML Schema 1.0 Date/Time Datatypes.<br>
* <i>(timezone is optional for all date/time datatypes)</i> * <i>(timezone is optional for all date/time datatypes)</i>
* </th> * </th>
* </tr> * </tr>
@ -238,16 +238,16 @@ public abstract class Duration {
public abstract int getSign(); public abstract int getSign();
/** /**
* <p>Get the years value of this <code>Duration</code> as an <code>int</code> or <code>0</code> if not present.</p> * Get the years value of this {@code Duration} as an {@code int} or {@code 0} if not present.
* *
* <p><code>getYears()</code> is a convenience method for * <p>{@code getYears()} is a convenience method for
* {@link #getField(DatatypeConstants.Field field) getField(DatatypeConstants.YEARS)}.</p> * {@link #getField(DatatypeConstants.Field field) getField(DatatypeConstants.YEARS)}.
* *
* <p>As the return value is an <code>int</code>, an incorrect value will be returned for <code>Duration</code>s * <p>As the return value is an {@code int}, an incorrect value will be returned for {@code Duration}s
* with years that go beyond the range of an <code>int</code>. * with years that go beyond the range of an {@code int}.
* Use {@link #getField(DatatypeConstants.Field field) getField(DatatypeConstants.YEARS)} to avoid possible loss of precision.</p> * Use {@link #getField(DatatypeConstants.Field field) getField(DatatypeConstants.YEARS)} to avoid possible loss of precision.
* *
* @return If the years field is present, return its value as an <code>int</code>, else return <code>0</code>. * @return If the years field is present, return its value as an {@code int}, else return {@code 0}.
*/ */
public int getYears() { public int getYears() {
return getField(DatatypeConstants.YEARS).intValue(); return getField(DatatypeConstants.YEARS).intValue();
@ -260,7 +260,7 @@ public abstract class Duration {
* This method works just like {@link #getYears()} except * This method works just like {@link #getYears()} except
* that this method works on the MONTHS field. * that this method works on the MONTHS field.
* *
* @return Months of this <code>Duration</code>. * @return Months of this {@code Duration}.
*/ */
public int getMonths() { public int getMonths() {
return getField(DatatypeConstants.MONTHS).intValue(); return getField(DatatypeConstants.MONTHS).intValue();
@ -273,7 +273,7 @@ public abstract class Duration {
* This method works just like {@link #getYears()} except * This method works just like {@link #getYears()} except
* that this method works on the DAYS field. * that this method works on the DAYS field.
* *
* @return Days of this <code>Duration</code>. * @return Days of this {@code Duration}.
*/ */
public int getDays() { public int getDays() {
return getField(DatatypeConstants.DAYS).intValue(); return getField(DatatypeConstants.DAYS).intValue();
@ -286,7 +286,7 @@ public abstract class Duration {
* This method works just like {@link #getYears()} except * This method works just like {@link #getYears()} except
* that this method works on the HOURS field. * that this method works on the HOURS field.
* *
* @return Hours of this <code>Duration</code>. * @return Hours of this {@code Duration}.
* *
*/ */
public int getHours() { public int getHours() {
@ -300,7 +300,7 @@ public abstract class Duration {
* This method works just like {@link #getYears()} except * This method works just like {@link #getYears()} except
* that this method works on the MINUTES field. * that this method works on the MINUTES field.
* *
* @return Minutes of this <code>Duration</code>. * @return Minutes of this {@code Duration}.
* *
*/ */
public int getMinutes() { public int getMinutes() {
@ -323,32 +323,32 @@ public abstract class Duration {
} }
/** /**
* <p>Returns the length of the duration in milli-seconds.</p> * Returns the length of the duration in milli-seconds.
* *
* <p>If the seconds field carries more digits than milli-second order, * <p>If the seconds field carries more digits than milli-second order,
* those will be simply discarded (or in other words, rounded to zero.) * those will be simply discarded (or in other words, rounded to zero.)
* For example, for any Calendar value <code>x</code>,</p> * For example, for any Calendar value {@code x},
* <pre> * <pre>
* <code>new Duration("PT10.00099S").getTimeInMills(x) == 10000</code>. * {@code new Duration("PT10.00099S").getTimeInMills(x) == 10000}
* <code>new Duration("-PT10.00099S").getTimeInMills(x) == -10000</code>. * {@code new Duration("-PT10.00099S").getTimeInMills(x) == -10000}
* </pre> * </pre>
* *
* <p> * <p>
* Note that this method uses the {@link #addTo(Calendar)} method, * Note that this method uses the {@link #addTo(Calendar)} method,
* which may work incorrectly with <code>Duration</code> objects with * which may work incorrectly with {@code Duration} objects with
* very large values in its fields. See the {@link #addTo(Calendar)} * very large values in its fields. See the {@link #addTo(Calendar)}
* method for details. * method for details.
* *
* @param startInstant * @param startInstant
* The length of a month/year varies. The <code>startInstant</code> is * The length of a month/year varies. The {@code startInstant} is
* used to disambiguate this variance. Specifically, this method * used to disambiguate this variance. Specifically, this method
* returns the difference between <code>startInstant</code> and * returns the difference between {@code startInstant} and
* <code>startInstant+duration</code> * {@code startInstant+duration}
* *
* @return milliseconds between <code>startInstant</code> and * @return milliseconds between {@code startInstant} and
* <code>startInstant</code> plus this <code>Duration</code> * {@code startInstant} plus this {@code Duration}
* *
* @throws NullPointerException if <code>startInstant</code> parameter * @throws NullPointerException if {@code startInstant} parameter
* is null. * is null.
* *
*/ */
@ -360,33 +360,33 @@ public abstract class Duration {
} }
/** /**
* <p>Returns the length of the duration in milli-seconds.</p> * Returns the length of the duration in milli-seconds.
* *
* <p>If the seconds field carries more digits than milli-second order, * <p>If the seconds field carries more digits than milli-second order,
* those will be simply discarded (or in other words, rounded to zero.) * those will be simply discarded (or in other words, rounded to zero.)
* For example, for any <code>Date</code> value <code>x</code>,</p> * For example, for any {@code Date} value {@code x},
* <pre> * <pre>
* <code>new Duration("PT10.00099S").getTimeInMills(x) == 10000</code>. * {@code new Duration("PT10.00099S").getTimeInMills(x) == 10000}
* <code>new Duration("-PT10.00099S").getTimeInMills(x) == -10000</code>. * {@code new Duration("-PT10.00099S").getTimeInMills(x) == -10000}
* </pre> * </pre>
* *
* <p> * <p>
* Note that this method uses the {@link #addTo(Date)} method, * Note that this method uses the {@link #addTo(Date)} method,
* which may work incorrectly with <code>Duration</code> objects with * which may work incorrectly with {@code Duration} objects with
* very large values in its fields. See the {@link #addTo(Date)} * very large values in its fields. See the {@link #addTo(Date)}
* method for details. * method for details.
* *
* @param startInstant * @param startInstant
* The length of a month/year varies. The <code>startInstant</code> is * The length of a month/year varies. The {@code startInstant} is
* used to disambiguate this variance. Specifically, this method * used to disambiguate this variance. Specifically, this method
* returns the difference between <code>startInstant</code> and * returns the difference between {@code startInstant} and
* <code>startInstant+duration</code>. * {@code startInstant+duration}.
* *
* @throws NullPointerException * @throws NullPointerException
* If the startInstant parameter is null. * If the startInstant parameter is null.
* *
* @return milliseconds between <code>startInstant</code> and * @return milliseconds between {@code startInstant} and
* <code>startInstant</code> plus this <code>Duration</code> * {@code startInstant} plus this {@code Duration}
* *
* @see #getTimeInMillis(Calendar) * @see #getTimeInMillis(Calendar)
*/ */
@ -418,7 +418,7 @@ public abstract class Duration {
* returns a {@link java.math.BigInteger} object. For SECONDS, this * returns a {@link java.math.BigInteger} object. For SECONDS, this
* method returns a {@link java.math.BigDecimal}. * method returns a {@link java.math.BigDecimal}.
* *
* @throws NullPointerException If the <code>field</code> is <code>null</code>. * @throws NullPointerException If the {@code field} is {@code null}.
*/ */
public abstract Number getField(final DatatypeConstants.Field field); public abstract Number getField(final DatatypeConstants.Field field);
@ -440,9 +440,9 @@ public abstract class Duration {
public abstract boolean isSet(final DatatypeConstants.Field field); public abstract boolean isSet(final DatatypeConstants.Field field);
/** /**
* <p>Computes a new duration whose value is <code>this+rhs</code>.</p> * Computes a new duration whose value is {@code this+rhs}.
* *
* <p>For example,</p> * <p>For example,
* <pre> * <pre>
* "1 day" + "-3 days" = "-2 days" * "1 day" + "-3 days" = "-2 days"
* "1 year" + "1 day" = "1 year and 1 day" * "1 year" + "1 day" = "1 year and 1 day"
@ -453,28 +453,28 @@ public abstract class Duration {
* *
* <p>Since there's no way to meaningfully subtract 1 day from 1 month, * <p>Since there's no way to meaningfully subtract 1 day from 1 month,
* there are cases where the operation fails in * there are cases where the operation fails in
* {@link IllegalStateException}.</p> * {@link IllegalStateException}.
* *
* <p> * <p>
* Formally, the computation is defined as follows.</p> * Formally, the computation is defined as follows.
* <p> * <p>
* Firstly, we can assume that two <code>Duration</code>s to be added * Firstly, we can assume that two {@code Duration}s to be added
* are both positive without losing generality (i.e., * are both positive without losing generality (i.e.,
* <code>(-X)+Y=Y-X</code>, <code>X+(-Y)=X-Y</code>, * {@code (-X)+Y=Y-X}, {@code X+(-Y)=X-Y},
* <code>(-X)+(-Y)=-(X+Y)</code>) * {@code (-X)+(-Y)=-(X+Y)})
* *
* <p> * <p>
* Addition of two positive <code>Duration</code>s are simply defined as * Addition of two positive {@code Duration}s are simply defined as
* field by field addition where missing fields are treated as 0. * field by field addition where missing fields are treated as 0.
* <p> * <p>
* A field of the resulting <code>Duration</code> will be unset if and * A field of the resulting {@code Duration} will be unset if and
* only if respective fields of two input <code>Duration</code>s are unset. * only if respective fields of two input {@code Duration}s are unset.
* <p> * <p>
* Note that <code>lhs.add(rhs)</code> will be always successful if * Note that {@code lhs.add(rhs)} will be always successful if
* <code>lhs.signum()*rhs.signum()!=-1</code> or both of them are * {@code lhs.signum()*rhs.signum()!=-1} or both of them are
* normalized.</p> * normalized.
* *
* @param rhs <code>Duration</code> to add to this <code>Duration</code> * @param rhs {@code Duration} to add to this {@code Duration}
* *
* @return * @return
* non-null valid Duration object. * non-null valid Duration object.
@ -501,25 +501,22 @@ public abstract class Duration {
* uses int to hold values, there are cases where this method * uses int to hold values, there are cases where this method
* won't work correctly (for example if values of fields * won't work correctly (for example if values of fields
* exceed the range of int.) * exceed the range of int.)
* </p>
* *
* <p> * <p>
* Also, since this duration class is a Gregorian duration, this * Also, since this duration class is a Gregorian duration, this
* method will not work correctly if the given {@link Calendar} * method will not work correctly if the given {@link Calendar}
* object is based on some other calendar systems. * object is based on some other calendar systems.
* </p>
* *
* <p> * <p>
* Any fractional parts of this <code>Duration</code> object * Any fractional parts of this {@code Duration} object
* beyond milliseconds will be simply ignored. For example, if * beyond milliseconds will be simply ignored. For example, if
* this duration is "P1.23456S", then 1 is added to SECONDS, * this duration is "P1.23456S", then 1 is added to SECONDS,
* 234 is added to MILLISECONDS, and the rest will be unused. * 234 is added to MILLISECONDS, and the rest will be unused.
* </p>
* *
* <p> * <p>
* Note that because {@link Calendar#add(int, int)} is using * Note that because {@link Calendar#add(int, int)} is using
* <code>int</code>, <code>Duration</code> with values beyond the * {@code int}, {@code Duration} with values beyond the
* range of <code>int</code> in its fields * range of {@code int} in its fields
* will cause overflow/underflow to the given {@link Calendar}. * will cause overflow/underflow to the given {@link Calendar}.
* {@link XMLGregorianCalendar#add(Duration)} provides the same * {@link XMLGregorianCalendar#add(Duration)} provides the same
* basic operation as this method while avoiding * basic operation as this method while avoiding
@ -571,9 +568,9 @@ public abstract class Duration {
} }
/** /**
* <p>Computes a new duration whose value is <code>this-rhs</code>.</p> * Computes a new duration whose value is {@code this-rhs}.
* *
* <p>For example:</p> * <p>For example:
* <pre> * <pre>
* "1 day" - "-3 days" = "4 days" * "1 day" - "-3 days" = "4 days"
* "1 year" - "1 day" = IllegalStateException * "1 year" - "1 day" = IllegalStateException
@ -583,31 +580,31 @@ public abstract class Duration {
* </pre> * </pre>
* *
* <p>Since there's no way to meaningfully subtract 1 day from 1 month, * <p>Since there's no way to meaningfully subtract 1 day from 1 month,
* there are cases where the operation fails in {@link IllegalStateException}.</p> * there are cases where the operation fails in {@link IllegalStateException}.
* *
* <p>Formally the computation is defined as follows. * <p>Formally the computation is defined as follows.
* First, we can assume that two <code>Duration</code>s are both positive * First, we can assume that two {@code Duration}s are both positive
* without losing generality. (i.e., * without losing generality. (i.e.,
* <code>(-X)-Y=-(X+Y)</code>, <code>X-(-Y)=X+Y</code>, * {@code (-X)-Y=-(X+Y)}, {@code X-(-Y)=X+Y},
* <code>(-X)-(-Y)=-(X-Y)</code>)</p> * {@code (-X)-(-Y)=-(X-Y)})
* *
* <p>Then two durations are subtracted field by field. * <p>Then two durations are subtracted field by field.
* If the sign of any non-zero field <code>F</code> is different from * If the sign of any non-zero field {@code F} is different from
* the sign of the most significant field, * the sign of the most significant field,
* 1 (if <code>F</code> is negative) or -1 (otherwise) * 1 (if {@code F} is negative) or -1 (otherwise)
* will be borrowed from the next bigger unit of <code>F</code>.</p> * will be borrowed from the next bigger unit of {@code F}.
* *
* <p>This process is repeated until all the non-zero fields have * <p>This process is repeated until all the non-zero fields have
* the same sign.</p> * the same sign.
* *
* <p>If a borrow occurs in the days field (in other words, if * <p>If a borrow occurs in the days field (in other words, if
* the computation needs to borrow 1 or -1 month to compensate * the computation needs to borrow 1 or -1 month to compensate
* days), then the computation fails by throwing an * days), then the computation fails by throwing an
* {@link IllegalStateException}.</p> * {@link IllegalStateException}.
* *
* @param rhs <code>Duration</code> to subtract from this <code>Duration</code>. * @param rhs {@code Duration} to subtract from this {@code Duration}.
* *
* @return New <code>Duration</code> created from subtracting <code>rhs</code> from this <code>Duration</code>. * @return New {@code Duration} created from subtracting {@code rhs} from this {@code Duration}.
* *
* @throws IllegalStateException * @throws IllegalStateException
* If two durations cannot be meaningfully subtracted. For * If two durations cannot be meaningfully subtracted. For
@ -624,18 +621,18 @@ public abstract class Duration {
} }
/** /**
* <p>Computes a new duration whose value is <code>factor</code> times * Computes a new duration whose value is {@code factor} times
* longer than the value of this duration.</p> * longer than the value of this duration.
* *
* <p>This method is provided for the convenience. * <p>This method is provided for the convenience.
* It is functionally equivalent to the following code:</p> * It is functionally equivalent to the following code:
* <pre> * <pre>
* multiply(new BigDecimal(String.valueOf(factor))) * multiply(new BigDecimal(String.valueOf(factor)))
* </pre> * </pre>
* *
* @param factor Factor times longer of new <code>Duration</code> to create. * @param factor Factor times longer of new {@code Duration} to create.
* *
* @return New <code>Duration</code> that is <code>factor</code>times longer than this <code>Duration</code>. * @return New {@code Duration} that is {@code factor}times longer than this {@code Duration}.
* *
* @see #multiply(BigDecimal) * @see #multiply(BigDecimal)
*/ */
@ -644,7 +641,7 @@ public abstract class Duration {
} }
/** /**
* Computes a new duration whose value is <code>factor</code> times * Computes a new duration whose value is {@code factor} times
* longer than the value of this duration. * longer than the value of this duration.
* *
* <p> * <p>
@ -656,7 +653,7 @@ public abstract class Duration {
* </pre> * </pre>
* *
* <p> * <p>
* Since the <code>Duration</code> class is immutable, this method * Since the {@code Duration} class is immutable, this method
* doesn't change the value of this object. It simply computes * doesn't change the value of this object. It simply computes
* a new Duration object and returns it. * a new Duration object and returns it.
* *
@ -671,7 +668,7 @@ public abstract class Duration {
* When fractions of month cannot be meaningfully carried down * When fractions of month cannot be meaningfully carried down
* to days, or year to months, this will cause an * to days, or year to months, this will cause an
* {@link IllegalStateException} to be thrown. * {@link IllegalStateException} to be thrown.
* For example if you multiple one month by 0.5.</p> * For example if you multiple one month by 0.5.
* *
* <p> * <p>
* To avoid {@link IllegalStateException}, use * To avoid {@link IllegalStateException}, use
@ -681,39 +678,39 @@ public abstract class Duration {
* @param factor to multiply by * @param factor to multiply by
* *
* @return * @return
* returns a non-null valid <code>Duration</code> object * returns a non-null valid {@code Duration} object
* *
* @throws IllegalStateException if operation produces fraction in * @throws IllegalStateException if operation produces fraction in
* the months field. * the months field.
* *
* @throws NullPointerException if the <code>factor</code> parameter is * @throws NullPointerException if the {@code factor} parameter is
* <code>null</code>. * {@code null}.
* *
*/ */
public abstract Duration multiply(final BigDecimal factor); public abstract Duration multiply(final BigDecimal factor);
/** /**
* Returns a new <code>Duration</code> object whose * Returns a new {@code Duration} object whose
* value is <code>-this</code>. * value is {@code -this}.
* *
* <p> * <p>
* Since the <code>Duration</code> class is immutable, this method * Since the {@code Duration} class is immutable, this method
* doesn't change the value of this object. It simply computes * doesn't change the value of this object. It simply computes
* a new Duration object and returns it. * a new Duration object and returns it.
* *
* @return * @return
* always return a non-null valid <code>Duration</code> object. * always return a non-null valid {@code Duration} object.
*/ */
public abstract Duration negate(); public abstract Duration negate();
/** /**
* <p>Converts the years and months fields into the days field * Converts the years and months fields into the days field
* by using a specific time instant as the reference point.</p> * by using a specific time instant as the reference point.
* *
* <p>For example, duration of one month normalizes to 31 days * <p>For example, duration of one month normalizes to 31 days
* given the start time instance "July 8th 2003, 17:40:32".</p> * given the start time instance "July 8th 2003, 17:40:32".
* *
* <p>Formally, the computation is done as follows:</p> * <p>Formally, the computation is done as follows:
* <ol> * <ol>
* <li>the given Calendar object is cloned</li> * <li>the given Calendar object is cloned</li>
* <li>the years, months and days fields will be added to the {@link Calendar} object * <li>the years, months and days fields will be added to the {@link Calendar} object
@ -725,37 +722,37 @@ public abstract class Duration {
* Duration object.</li> * Duration object.</li>
* </ol> * </ol>
* *
* <p>Note that since the Calendar class uses <code>int</code> to * <p>Note that since the Calendar class uses {@code int} to
* hold the value of year and month, this method may produce * hold the value of year and month, this method may produce
* an unexpected result if this duration object holds * an unexpected result if this duration object holds
* a very large value in the years or months fields.</p> * a very large value in the years or months fields.
* *
* @param startTimeInstant <code>Calendar</code> reference point. * @param startTimeInstant {@code Calendar} reference point.
* *
* @return <code>Duration</code> of years and months of this <code>Duration</code> as days. * @return {@code Duration} of years and months of this {@code Duration} as days.
* *
* @throws NullPointerException If the startTimeInstant parameter is null. * @throws NullPointerException If the startTimeInstant parameter is null.
*/ */
public abstract Duration normalizeWith(final Calendar startTimeInstant); public abstract Duration normalizeWith(final Calendar startTimeInstant);
/** /**
* <p>Partial order relation comparison with this <code>Duration</code> instance.</p> * Partial order relation comparison with this {@code Duration} instance.
* *
* <p>Comparison result must be in accordance with * <p>Comparison result must be in accordance with
* <a href="http://www.w3.org/TR/xmlschema-2/#duration-order">W3C XML Schema 1.0 Part 2, Section 3.2.7.6.2, * <a href="http://www.w3.org/TR/xmlschema-2/#duration-order">W3C XML Schema 1.0 Part 2, Section 3.2.7.6.2,
* <i>Order relation on duration</i></a>.</p> * <i>Order relation on duration</i></a>.
* *
* <p>Return:</p> * <p>Return:
* <ul> * <ul>
* <li>{@link DatatypeConstants#LESSER} if this <code>Duration</code> is shorter than <code>duration</code> parameter</li> * <li>{@link DatatypeConstants#LESSER} if this {@code Duration} is shorter than {@code duration} parameter</li>
* <li>{@link DatatypeConstants#EQUAL} if this <code>Duration</code> is equal to <code>duration</code> parameter</li> * <li>{@link DatatypeConstants#EQUAL} if this {@code Duration} is equal to {@code duration} parameter</li>
* <li>{@link DatatypeConstants#GREATER} if this <code>Duration</code> is longer than <code>duration</code> parameter</li> * <li>{@link DatatypeConstants#GREATER} if this {@code Duration} is longer than {@code duration} parameter</li>
* <li>{@link DatatypeConstants#INDETERMINATE} if a conclusive partial order relation cannot be determined</li> * <li>{@link DatatypeConstants#INDETERMINATE} if a conclusive partial order relation cannot be determined</li>
* </ul> * </ul>
* *
* @param duration to compare * @param duration to compare
* *
* @return the relationship between <code>this</code> <code>Duration</code>and <code>duration</code> parameter as * @return the relationship between {@code this Duration} and {@code duration} parameter as
* {@link DatatypeConstants#LESSER}, {@link DatatypeConstants#EQUAL}, {@link DatatypeConstants#GREATER} * {@link DatatypeConstants#LESSER}, {@link DatatypeConstants#EQUAL}, {@link DatatypeConstants#GREATER}
* or {@link DatatypeConstants#INDETERMINATE}. * or {@link DatatypeConstants#INDETERMINATE}.
* *
@ -763,7 +760,7 @@ public abstract class Duration {
* cannot reasonably process the request, e.g. W3C XML Schema allows for * cannot reasonably process the request, e.g. W3C XML Schema allows for
* arbitrarily large/small/precise values, the request may be beyond the * arbitrarily large/small/precise values, the request may be beyond the
* implementations capability. * implementations capability.
* @throws NullPointerException if <code>duration</code> is <code>null</code>. * @throws NullPointerException if {@code duration} is {@code null}.
* *
* @see #isShorterThan(Duration) * @see #isShorterThan(Duration)
* @see #isLongerThan(Duration) * @see #isLongerThan(Duration)
@ -771,23 +768,23 @@ public abstract class Duration {
public abstract int compare(final Duration duration); public abstract int compare(final Duration duration);
/** /**
* <p>Checks if this duration object is strictly longer than * Checks if this duration object is strictly longer than
* another <code>Duration</code> object.</p> * another {@code Duration} object.
* *
* <p>Duration X is "longer" than Y if and only if X>Y * <p>Duration X is "longer" than Y if and only if X {@literal >} Y
* as defined in the section 3.2.6.2 of the XML Schema 1.0 * as defined in the section 3.2.6.2 of the XML Schema 1.0
* specification.</p> * specification.
* *
* <p>For example, "P1D" (one day) > "PT12H" (12 hours) and * <p>For example, "P1D" (one day) {@literal >} "PT12H" (12 hours) and
* "P2Y" (two years) > "P23M" (23 months).</p> * "P2Y" (two years) {@literal >} "P23M" (23 months).
* *
* @param duration <code>Duration</code> to test this <code>Duration</code> against. * @param duration {@code Duration} to test this {@code Duration} against.
* *
* @throws UnsupportedOperationException If the underlying implementation * @throws UnsupportedOperationException If the underlying implementation
* cannot reasonably process the request, e.g. W3C XML Schema allows for * cannot reasonably process the request, e.g. W3C XML Schema allows for
* arbitrarily large/small/precise values, the request may be beyond the * arbitrarily large/small/precise values, the request may be beyond the
* implementations capability. * implementations capability.
* @throws NullPointerException If <code>duration</code> is null. * @throws NullPointerException If {@code duration} is null.
* *
* @return * @return
* true if the duration represented by this object * true if the duration represented by this object
@ -801,19 +798,19 @@ public abstract class Duration {
} }
/** /**
* <p>Checks if this duration object is strictly shorter than * Checks if this duration object is strictly shorter than
* another <code>Duration</code> object.</p> * another {@code Duration} object.
* *
* @param duration <code>Duration</code> to test this <code>Duration</code> against. * @param duration {@code Duration} to test this {@code Duration} against.
* *
* @return <code>true</code> if <code>duration</code> parameter is shorter than this <code>Duration</code>, * @return {@code true} if {@code duration} parameter is shorter than this {@code Duration},
* else <code>false</code>. * else {@code false}.
* *
* @throws UnsupportedOperationException If the underlying implementation * @throws UnsupportedOperationException If the underlying implementation
* cannot reasonably process the request, e.g. W3C XML Schema allows for * cannot reasonably process the request, e.g. W3C XML Schema allows for
* arbitrarily large/small/precise values, the request may be beyond the * arbitrarily large/small/precise values, the request may be beyond the
* implementations capability. * implementations capability.
* @throws NullPointerException if <code>duration</code> is null. * @throws NullPointerException if {@code duration} is null.
* *
* @see #isLongerThan(Duration duration) * @see #isLongerThan(Duration duration)
* @see #compare(Duration duration) * @see #compare(Duration duration)
@ -823,19 +820,19 @@ public abstract class Duration {
} }
/** /**
* <p>Checks if this duration object has the same duration * Checks if this duration object has the same duration
* as another <code>Duration</code> object.</p> * as another {@code Duration} object.
* *
* <p>For example, "P1D" (1 day) is equal to "PT24H" (24 hours).</p> * <p>For example, "P1D" (1 day) is equal to "PT24H" (24 hours).
* *
* <p>Duration X is equal to Y if and only if time instant * <p>Duration X is equal to Y if and only if time instant
* t+X and t+Y are the same for all the test time instants * t+X and t+Y are the same for all the test time instants
* specified in the section 3.2.6.2 of the XML Schema 1.0 * specified in the section 3.2.6.2 of the XML Schema 1.0
* specification.</p> * specification.
* *
* <p>Note that there are cases where two <code>Duration</code>s are * <p>Note that there are cases where two {@code Duration}s are
* "incomparable" to each other, like one month and 30 days. * "incomparable" to each other, like one month and 30 days.
* For example,</p> * For example,
* <pre> * <pre>
* !new Duration("P1M").isShorterThan(new Duration("P30D")) * !new Duration("P1M").isShorterThan(new Duration("P30D"))
* !new Duration("P1M").isLongerThan(new Duration("P30D")) * !new Duration("P1M").isLongerThan(new Duration("P30D"))
@ -843,14 +840,14 @@ public abstract class Duration {
* </pre> * </pre>
* *
* @param duration * @param duration
* The object to compare this <code>Duration</code> against. * The object to compare this {@code Duration} against.
* *
* @return * @return
* <code>true</code> if this duration is the same length as * {@code true} if this duration is the same length as
* <code>duration</code>. * {@code duration}.
* <code>false</code> if <code>duration</code> is <code>null</code>, * {@code false} if {@code duration} is {@code null},
* is not a * is not a
* <code>Duration</code> object, * {@code Duration} object,
* or its length is different from this duration. * or its length is different from this duration.
* *
* @throws UnsupportedOperationException If the underlying implementation * @throws UnsupportedOperationException If the underlying implementation
@ -877,18 +874,19 @@ public abstract class Duration {
public abstract int hashCode(); public abstract int hashCode();
/** /**
* <p>Returns a <code>String</code> representation of this <code>Duration</code> <code>Object</code>.</p> * Returns a {@code String} representation of this {@code Duration Object}.
* *
* <p>The result is formatted according to the XML Schema 1.0 spec and can be always parsed back later into the * <p>The result is formatted according to the XML Schema 1.0 spec
* equivalent <code>Duration</code> <code>Object</code> by {@link DatatypeFactory#newDuration(String lexicalRepresentation)}.</p> * and can be always parsed back later into the
* equivalent {@code Duration Object} by {@link DatatypeFactory#newDuration(String lexicalRepresentation)}.
* *
* <p>Formally, the following holds for any <code>Duration</code> * <p>Formally, the following holds for any {@code Duration}
* <code>Object</code> x:</p> * {@code Object} x:
* <pre> * <pre>
* new Duration(x.toString()).equals(x) * new Duration(x.toString()).equals(x)
* </pre> * </pre>
* *
* @return A non-<code>null</code> valid <code>String</code> representation of this <code>Duration</code>. * @return A non-{@code null} valid {@code String} representation of this {@code Duration}.
*/ */
public String toString() { public String toString() {
@ -934,14 +932,14 @@ public abstract class Duration {
} }
/** /**
* <p>Turns {@link BigDecimal} to a string representation.</p> * Turns {@link BigDecimal} to a string representation.
* *
* <p>Due to a behavior change in the {@link BigDecimal#toString()} * <p>Due to a behavior change in the {@link BigDecimal#toString()}
* method in JDK1.5, this had to be implemented here.</p> * method in JDK1.5, this had to be implemented here.
* *
* @param bd <code>BigDecimal</code> to format as a <code>String</code> * @param bd {@code BigDecimal} to format as a {@code String}
* *
* @return <code>String</code> representation of <code>BigDecimal</code> * @return {@code String} representation of {@code BigDecimal}
*/ */
private String toString(BigDecimal bd) { private String toString(BigDecimal bd) {
String intString = bd.unscaledValue().toString(); String intString = bd.unscaledValue().toString();
@ -972,15 +970,15 @@ public abstract class Duration {
/** /**
* <p>Calls the {@link Calendar#getTimeInMillis} method. * Calls the {@link Calendar#getTimeInMillis} method.
* Prior to JDK1.4, this method was protected and therefore * Prior to JDK1.4, this method was protected and therefore
* cannot be invoked directly.</p> * cannot be invoked directly.
* *
* <p>TODO: In future, this should be replaced by <code>cal.getTimeInMillis()</code>.</p> * <p>TODO: In future, this should be replaced by {@code cal.getTimeInMillis()}.
* *
* @param cal <code>Calendar</code> to get time in milliseconds. * @param cal {@code Calendar} to get time in milliseconds.
* *
* @return Milliseconds of <code>cal</code>. * @return Milliseconds of {@code cal}.
*/ */
private static long getCalendarTimeInMillis(final Calendar cal) { private static long getCalendarTimeInMillis(final Calendar cal) {
return cal.getTime().getTime(); return cal.getTime().getTime();

417
jaxp/src/java.xml/share/classes/javax/xml/datatype/XMLGregorianCalendar.java
View file

@ -43,17 +43,17 @@ import java.util.GregorianCalendar;
* {@link DatatypeConstants#GMONTH}, and * {@link DatatypeConstants#GMONTH}, and
* {@link DatatypeConstants#GDAY} * {@link DatatypeConstants#GDAY}
* defined in the XML Namespace * defined in the XML Namespace
* <code>"http://www.w3.org/2001/XMLSchema"</code>. * {@code "http://www.w3.org/2001/XMLSchema"}.
* These datatypes are normatively defined in * These datatypes are normatively defined in
* <a href="http://www.w3.org/TR/xmlschema-2/#dateTime">W3C XML Schema 1.0 Part 2, Section 3.2.7-14</a>.</p> * <a href="http://www.w3.org/TR/xmlschema-2/#dateTime">W3C XML Schema 1.0 Part 2, Section 3.2.7-14</a>.
* *
* <p>The table below defines the mapping between XML Schema 1.0 * <p>The table below defines the mapping between XML Schema 1.0
* date/time datatype fields and this class' fields. It also summarizes * date/time datatype fields and this class' fields. It also summarizes
* the value constraints for the date and time fields defined in * the value constraints for the date and time fields defined in
* <a href="http://www.w3.org/TR/xmlschema-2/#isoformats">W3C XML Schema 1.0 Part 2, Appendix D, * <a href="http://www.w3.org/TR/xmlschema-2/#isoformats">W3C XML Schema 1.0 Part 2, Appendix D,
* <i>ISO 8601 Date and Time Formats</i></a>.</p> * <i>ISO 8601 Date and Time Formats</i></a>.
* *
* <a name="datetimefieldmapping"/> * <a name="datetimefieldmapping"></a>
* <table border="2" rules="all" cellpadding="2"> * <table border="2" rules="all" cellpadding="2">
* <thead> * <thead>
* <tr> * <tr>
@ -64,22 +64,22 @@ import java.util.GregorianCalendar;
* </thead> * </thead>
* <tbody> * <tbody>
* <tr> * <tr>
* <th>XML Schema 1.0<br/> * <th>XML Schema 1.0<br>
* datatype<br/> * datatype<br>
* field</th> * field</th>
* <th>Related<br/>XMLGregorianCalendar<br/>Accessor(s)</th> * <th>Related<br>XMLGregorianCalendar<br>Accessor(s)</th>
* <th>Value Range</th> * <th>Value Range</th>
* </tr> * </tr>
* <tr> * <tr>
* <td><a name="datetimefield-year"/>year</td> * <td><a name="datetimefield-year">year</a></td>
* <td> {@link #getYear()} + {@link #getEon()} or<br/> * <td> {@link #getYear()} + {@link #getEon()} or<br>
* {@link #getEonAndYear} * {@link #getEonAndYear}
* </td> * </td>
* <td> <code>getYear()</code> is a value between -(10^9-1) to (10^9)-1 * <td> {@code getYear()} is a value between -(10^9-1) to (10^9)-1
* or {@link DatatypeConstants#FIELD_UNDEFINED}.<br/> * or {@link DatatypeConstants#FIELD_UNDEFINED}.<br>
* {@link #getEon()} is high order year value in billion of years.<br/> * {@link #getEon()} is high order year value in billion of years.<br>
* <code>getEon()</code> has values greater than or equal to (10^9) or less than or equal to -(10^9). * {@code getEon()} has values greater than or equal to (10^9) or less than or equal to -(10^9).
* A value of null indicates field is undefined.</br> * A value of null indicates field is undefined.<br>
* Given that <a href="http://www.w3.org/2001/05/xmlschema-errata#e2-63">XML Schema 1.0 errata</a> states that the year zero * Given that <a href="http://www.w3.org/2001/05/xmlschema-errata#e2-63">XML Schema 1.0 errata</a> states that the year zero
* will be a valid lexical value in a future version of XML Schema, * will be a valid lexical value in a future version of XML Schema,
* this class allows the year field to be set to zero. Otherwise, * this class allows the year field to be set to zero. Otherwise,
@ -89,20 +89,20 @@ import java.util.GregorianCalendar;
* </td> * </td>
* </tr> * </tr>
* <tr> * <tr>
* <td><a name="datetimefield-month"/>month</td> * <td><a name="datetimefield-month">month</a></td>
* <td> {@link #getMonth()} </td> * <td> {@link #getMonth()} </td>
* <td> 1 to 12 or {@link DatatypeConstants#FIELD_UNDEFINED} </td> * <td> 1 to 12 or {@link DatatypeConstants#FIELD_UNDEFINED} </td>
* </tr> * </tr>
* <tr> * <tr>
* <td><a name="datetimefield-day"/>day</td> * <td><a name="datetimefield-day">day</a></td>
* <td> {@link #getDay()} </td> * <td> {@link #getDay()} </td>
* <td> Independent of month, max range is 1 to 31 or {@link DatatypeConstants#FIELD_UNDEFINED}.<br/> * <td> Independent of month, max range is 1 to 31 or {@link DatatypeConstants#FIELD_UNDEFINED}.<br>
* The normative value constraint stated relative to month * The normative value constraint stated relative to month
* field's value is in <a href="http://www.w3.org/TR/xmlschema-2/#isoformats">W3C XML Schema 1.0 Part 2, Appendix D</a>. * field's value is in <a href="http://www.w3.org/TR/xmlschema-2/#isoformats">W3C XML Schema 1.0 Part 2, Appendix D</a>.
* </td> * </td>
* </tr> * </tr>
* <tr> * <tr>
* <td><a name="datetimefield-hour"/>hour</td> * <td><a name="datetimefield-hour">hour</a></td>
* <td>{@link #getHour()}</td> * <td>{@link #getHour()}</td>
* <td> * <td>
* 0 to 23 or {@link DatatypeConstants#FIELD_UNDEFINED}. * 0 to 23 or {@link DatatypeConstants#FIELD_UNDEFINED}.
@ -114,28 +114,28 @@ import java.util.GregorianCalendar;
* </td> * </td>
* </tr> * </tr>
* <tr> * <tr>
* <td><a name="datetimefield-minute"/>minute</td> * <td><a name="datetimefield-minute">minute</a></td>
* <td> {@link #getMinute()} </td> * <td> {@link #getMinute()} </td>
* <td> 0 to 59 or {@link DatatypeConstants#FIELD_UNDEFINED} </td> * <td> 0 to 59 or {@link DatatypeConstants#FIELD_UNDEFINED} </td>
* </tr> * </tr>
* <tr> * <tr>
* <td><a name="datetimefield-second"/>second</td> * <td><a name="datetimefield-second">second</a></td>
* <td> * <td>
* {@link #getSecond()} + {@link #getMillisecond()}/1000 or<br/> * {@link #getSecond()} + {@link #getMillisecond()}/1000 or<br>
* {@link #getSecond()} + {@link #getFractionalSecond()} * {@link #getSecond()} + {@link #getFractionalSecond()}
* </td> * </td>
* <td> * <td>
* {@link #getSecond()} from 0 to 60 or {@link DatatypeConstants#FIELD_UNDEFINED}.<br/> * {@link #getSecond()} from 0 to 60 or {@link DatatypeConstants#FIELD_UNDEFINED}.<br>
* <i>(Note: 60 only allowable for leap second.)</i><br/> * <i>(Note: 60 only allowable for leap second.)</i><br>
* {@link #getFractionalSecond()} allows for infinite precision over the range from 0.0 to 1.0 when * {@link #getFractionalSecond()} allows for infinite precision over the range from 0.0 to 1.0 when
* the {@link #getSecond()} is defined.<br/> * the {@link #getSecond()} is defined.<br>
* <code>FractionalSecond</code> is optional and has a value of <code>null</code> when it is undefined.<br /> * {@code FractionalSecond} is optional and has a value of {@code null} when it is undefined.<br>
* {@link #getMillisecond()} is the convenience * {@link #getMillisecond()} is the convenience
* millisecond precision of value of {@link #getFractionalSecond()}. * millisecond precision of value of {@link #getFractionalSecond()}.
* </td> * </td>
* </tr> * </tr>
* <tr> * <tr>
* <td><a name="datetimefield-timezone"/>timezone</td> * <td><a name="datetimefield-timezone">timezone</a></td>
* <td> {@link #getTimezone()} </td> * <td> {@link #getTimezone()} </td>
* <td> Number of minutes or {@link DatatypeConstants#FIELD_UNDEFINED}. * <td> Number of minutes or {@link DatatypeConstants#FIELD_UNDEFINED}.
* Value range from -14 hours (-14 * 60 minutes) to 14 hours (14 * 60 minutes). * Value range from -14 hours (-14 * 60 minutes) to 14 hours (14 * 60 minutes).
@ -145,14 +145,13 @@ import java.util.GregorianCalendar;
* </table> * </table>
* *
* <p>All maximum value space constraints listed for the fields in the table * <p>All maximum value space constraints listed for the fields in the table
* above are checked by factory methods, @{link DatatypeFactory}, * above are checked by factory methods, {@link DatatypeFactory},
* setter methods and parse methods of * setter methods and parse methods of
* this class. <code>IllegalArgumentException</code> is thrown when a * this class. {@code IllegalArgumentException} is thrown when a
* parameter's value is outside the value constraint for the field or * parameter's value is outside the value constraint for the field or
* if the composite * if the composite
* values constitute an invalid XMLGregorianCalendar instance (for example, if * values constitute an invalid XMLGregorianCalendar instance (for example, if
* the 31st of June is specified). * the 31st of June is specified).
* </p>
* *
* <p>The following operations are defined for this class: * <p>The following operations are defined for this class:
* <ul> * <ul>
@ -169,7 +168,6 @@ import java.util.GregorianCalendar;
* W3C XML Schema 1.0 Part 2, Appendix E, <i>Adding durations to dateTimes</i></a>. * W3C XML Schema 1.0 Part 2, Appendix E, <i>Adding durations to dateTimes</i></a>.
* </li> * </li>
* </ul> * </ul>
* </p>
* *
* @author <a href="mailto:Joseph.Fialli@Sun.com">Joseph Fialli</a> * @author <a href="mailto:Joseph.Fialli@Sun.com">Joseph Fialli</a>
* @author <a href="mailto:Kohsuke.Kawaguchi@Sun.com">Kohsuke Kawaguchi</a> * @author <a href="mailto:Kohsuke.Kawaguchi@Sun.com">Kohsuke Kawaguchi</a>
@ -187,26 +185,26 @@ public abstract class XMLGregorianCalendar
* Default no-arg constructor. * Default no-arg constructor.
* *
* <p>Note: Always use the {@link DatatypeFactory} to * <p>Note: Always use the {@link DatatypeFactory} to
* construct an instance of <code>XMLGregorianCalendar</code>. * construct an instance of {@code XMLGregorianCalendar}.
* The constructor on this class cannot be guaranteed to * The constructor on this class cannot be guaranteed to
* produce an object with a consistent state and may be * produce an object with a consistent state and may be
* removed in the future.</p> * removed in the future.
*/ */
public XMLGregorianCalendar() { public XMLGregorianCalendar() {
} }
/** /**
* <p>Unset all fields to undefined.</p> * Unset all fields to undefined.
* *
* <p>Set all int fields to {@link DatatypeConstants#FIELD_UNDEFINED} and reference fields * <p>Set all int fields to {@link DatatypeConstants#FIELD_UNDEFINED} and reference fields
* to null.</p> * to null.
*/ */
public abstract void clear(); public abstract void clear();
/** /**
* <p>Reset this <code>XMLGregorianCalendar</code> to its original values.</p> * Reset this {@code XMLGregorianCalendar} to its original values.
* *
* <p><code>XMLGregorianCalendar</code> is reset to the same values as when it was created with * <p>{@code XMLGregorianCalendar} is reset to the same values as when it was created with
* {@link DatatypeFactory#newXMLGregorianCalendar()}, * {@link DatatypeFactory#newXMLGregorianCalendar()},
* {@link DatatypeFactory#newXMLGregorianCalendar(String lexicalRepresentation)}, * {@link DatatypeFactory#newXMLGregorianCalendar(String lexicalRepresentation)},
* {@link DatatypeFactory#newXMLGregorianCalendar( * {@link DatatypeFactory#newXMLGregorianCalendar(
@ -250,83 +248,82 @@ public abstract class XMLGregorianCalendar
* int seconds, * int seconds,
* int milliseconds, * int milliseconds,
* int timezone)}. * int timezone)}.
* </p>
* *
* <p><code>reset()</code> is designed to allow the reuse of existing <code>XMLGregorianCalendar</code>s * <p>{@code reset()} is designed to allow the reuse of existing {@code XMLGregorianCalendar}s
* thus saving resources associated with the creation of new <code>XMLGregorianCalendar</code>s.</p> * thus saving resources associated with the creation of new {@code XMLGregorianCalendar}s.
*/ */
public abstract void reset(); public abstract void reset();
/** /**
* <p>Set low and high order component of XSD <code>dateTime</code> year field.</p> * Set low and high order component of XSD {@code dateTime} year field.
* *
* <p>Unset this field by invoking the setter with a parameter value of <code>null</code>.</p> * <p>Unset this field by invoking the setter with a parameter value of {@code null}.
* *
* @param year value constraints summarized in <a href="#datetimefield-year">year field of date/time field mapping table</a>. * @param year value constraints summarized in <a href="#datetimefield-year">year field of date/time field mapping table</a>.
* *
* @throws IllegalArgumentException if <code>year</code> parameter is * @throws IllegalArgumentException if {@code year} parameter is
* outside value constraints for the field as specified in * outside value constraints for the field as specified in
* <a href="#datetimefieldmapping">date/time field mapping table</a>. * <a href="#datetimefieldmapping">date/time field mapping table</a>.
*/ */
public abstract void setYear(BigInteger year); public abstract void setYear(BigInteger year);
/** /**
* <p>Set year of XSD <code>dateTime</code> year field.</p> * Set year of XSD {@code dateTime} year field.
* *
* <p>Unset this field by invoking the setter with a parameter value of * <p>Unset this field by invoking the setter with a parameter value of
* {@link DatatypeConstants#FIELD_UNDEFINED}.</p> * {@link DatatypeConstants#FIELD_UNDEFINED}.
* *
* <p>Note: if the absolute value of the <code>year</code> parameter * <p>Note: if the absolute value of the {@code year} parameter
* is less than 10^9, the eon component of the XSD year field is set to * is less than 10^9, the eon component of the XSD year field is set to
* <code>null</code> by this method.</p> * {@code null} by this method.
* *
* @param year value constraints are summarized in <a href="#datetimefield-year">year field of date/time field mapping table</a>. * @param year value constraints are summarized in <a href="#datetimefield-year">year field of date/time field mapping table</a>.
* If year is {@link DatatypeConstants#FIELD_UNDEFINED}, then eon is set to <code>null</code>. * If year is {@link DatatypeConstants#FIELD_UNDEFINED}, then eon is set to {@code null}.
*/ */
public abstract void setYear(int year); public abstract void setYear(int year);
/** /**
* <p>Set month.</p> * Set month.
* *
* <p>Unset this field by invoking the setter with a parameter value of {@link DatatypeConstants#FIELD_UNDEFINED}.</p> * <p>Unset this field by invoking the setter with a parameter value of {@link DatatypeConstants#FIELD_UNDEFINED}.
* *
* @param month value constraints summarized in <a href="#datetimefield-month">month field of date/time field mapping table</a>. * @param month value constraints summarized in <a href="#datetimefield-month">month field of date/time field mapping table</a>.
* *
* @throws IllegalArgumentException if <code>month</code> parameter is * @throws IllegalArgumentException if {@code month} parameter is
* outside value constraints for the field as specified in * outside value constraints for the field as specified in
* <a href="#datetimefieldmapping">date/time field mapping table</a>. * <a href="#datetimefieldmapping">date/time field mapping table</a>.
*/ */
public abstract void setMonth(int month); public abstract void setMonth(int month);
/** /**
* <p>Set days in month.</p> * Set days in month.
* *
* <p>Unset this field by invoking the setter with a parameter value of {@link DatatypeConstants#FIELD_UNDEFINED}.</p> * <p>Unset this field by invoking the setter with a parameter value of {@link DatatypeConstants#FIELD_UNDEFINED}.
* *
* @param day value constraints summarized in <a href="#datetimefield-day">day field of date/time field mapping table</a>. * @param day value constraints summarized in <a href="#datetimefield-day">day field of date/time field mapping table</a>.
* *
* @throws IllegalArgumentException if <code>day</code> parameter is * @throws IllegalArgumentException if {@code day} parameter is
* outside value constraints for the field as specified in * outside value constraints for the field as specified in
* <a href="#datetimefieldmapping">date/time field mapping table</a>. * <a href="#datetimefieldmapping">date/time field mapping table</a>.
*/ */
public abstract void setDay(int day); public abstract void setDay(int day);
/** /**
* <p>Set the number of minutes in the timezone offset.</p> * Set the number of minutes in the timezone offset.
* *
* <p>Unset this field by invoking the setter with a parameter value of {@link DatatypeConstants#FIELD_UNDEFINED}.</p> * <p>Unset this field by invoking the setter with a parameter value of {@link DatatypeConstants#FIELD_UNDEFINED}.
* *
* @param offset value constraints summarized in <a href="#datetimefield-timezone"> * @param offset value constraints summarized in <a href="#datetimefield-timezone">
* timezone field of date/time field mapping table</a>. * timezone field of date/time field mapping table</a>.
* *
* @throws IllegalArgumentException if <code>offset</code> parameter is * @throws IllegalArgumentException if {@code offset} parameter is
* outside value constraints for the field as specified in * outside value constraints for the field as specified in
* <a href="#datetimefieldmapping">date/time field mapping table</a>. * <a href="#datetimefieldmapping">date/time field mapping table</a>.
*/ */
public abstract void setTimezone(int offset); public abstract void setTimezone(int offset);
/** /**
* <p>Set time as one unit.</p> * Set time as one unit.
* *
* @param hour value constraints are summarized in * @param hour value constraints are summarized in
* <a href="#datetimefield-hour">hour field of date/time field mapping table</a>. * <a href="#datetimefield-hour">hour field of date/time field mapping table</a>.
@ -352,71 +349,71 @@ public abstract class XMLGregorianCalendar
} }
/** /**
* <p>Set hours.</p> * Set hours.
* *
* <p>Unset this field by invoking the setter with a parameter value of {@link DatatypeConstants#FIELD_UNDEFINED}.</p> * <p>Unset this field by invoking the setter with a parameter value of {@link DatatypeConstants#FIELD_UNDEFINED}.
* *
* @param hour value constraints summarized in <a href="#datetimefield-hour">hour field of date/time field mapping table</a>. * @param hour value constraints summarized in <a href="#datetimefield-hour">hour field of date/time field mapping table</a>.
* *
* @throws IllegalArgumentException if <code>hour</code> parameter is outside value constraints for the field as specified in * @throws IllegalArgumentException if {@code hour} parameter is outside value constraints for the field as specified in
* <a href="#datetimefieldmapping">date/time field mapping table</a>. * <a href="#datetimefieldmapping">date/time field mapping table</a>.
*/ */
public abstract void setHour(int hour); public abstract void setHour(int hour);
/** /**
* <p>Set minutes.</p> * Set minutes.
* *
* <p>Unset this field by invoking the setter with a parameter value of {@link DatatypeConstants#FIELD_UNDEFINED}.</p> * <p>Unset this field by invoking the setter with a parameter value of {@link DatatypeConstants#FIELD_UNDEFINED}.
* *
* @param minute value constraints summarized in <a href="#datetimefield-minute">minute field of date/time field mapping table</a>. * @param minute value constraints summarized in <a href="#datetimefield-minute">minute field of date/time field mapping table</a>.
* *
* @throws IllegalArgumentException if <code>minute</code> parameter is outside value constraints for the field as specified in * @throws IllegalArgumentException if {@code minute} parameter is outside value constraints for the field as specified in
* <a href="#datetimefieldmapping">date/time field mapping table</a>. * <a href="#datetimefieldmapping">date/time field mapping table</a>.
*/ */
public abstract void setMinute(int minute); public abstract void setMinute(int minute);
/** /**
* <p>Set seconds.</p> * Set seconds.
* *
* <p>Unset this field by invoking the setter with a parameter value of {@link DatatypeConstants#FIELD_UNDEFINED}.</p> * <p>Unset this field by invoking the setter with a parameter value of {@link DatatypeConstants#FIELD_UNDEFINED}.
* *
* @param second value constraints summarized in <a href="#datetimefield-second">second field of date/time field mapping table</a>. * @param second value constraints summarized in <a href="#datetimefield-second">second field of date/time field mapping table</a>.
* *
* @throws IllegalArgumentException if <code>second</code> parameter is outside value constraints for the field as specified in * @throws IllegalArgumentException if {@code second} parameter is outside value constraints for the field as specified in
* <a href="#datetimefieldmapping">date/time field mapping table</a>. * <a href="#datetimefieldmapping">date/time field mapping table</a>.
*/ */
public abstract void setSecond(int second); public abstract void setSecond(int second);
/** /**
* <p>Set milliseconds.</p> * Set milliseconds.
* *
* <p>Unset this field by invoking the setter with a parameter value of {@link DatatypeConstants#FIELD_UNDEFINED}.</p> * <p>Unset this field by invoking the setter with a parameter value of {@link DatatypeConstants#FIELD_UNDEFINED}.
* *
* @param millisecond value constraints summarized in * @param millisecond value constraints summarized in
* <a href="#datetimefield-second">second field of date/time field mapping table</a>. * <a href="#datetimefield-second">second field of date/time field mapping table</a>.
* *
* @throws IllegalArgumentException if <code>millisecond</code> parameter is outside value constraints for the field as specified * @throws IllegalArgumentException if {@code millisecond} parameter is outside value constraints for the field as specified
* in <a href="#datetimefieldmapping">date/time field mapping table</a>. * in <a href="#datetimefieldmapping">date/time field mapping table</a>.
*/ */
public abstract void setMillisecond(int millisecond); public abstract void setMillisecond(int millisecond);
/** /**
* <p>Set fractional seconds.</p> * Set fractional seconds.
* *
* <p>Unset this field by invoking the setter with a parameter value of <code>null</code>.</p> * <p>Unset this field by invoking the setter with a parameter value of {@code null}.
* *
* @param fractional value constraints summarized in * @param fractional value constraints summarized in
* <a href="#datetimefield-second">second field of date/time field mapping table</a>. * <a href="#datetimefield-second">second field of date/time field mapping table</a>.
* *
* @throws IllegalArgumentException if <code>fractional</code> parameter is outside value constraints for the field as specified * @throws IllegalArgumentException if {@code fractional} parameter is outside value constraints for the field as specified
* in <a href="#datetimefieldmapping">date/time field mapping table</a>. * in <a href="#datetimefieldmapping">date/time field mapping table</a>.
*/ */
public abstract void setFractionalSecond(BigDecimal fractional); public abstract void setFractionalSecond(BigDecimal fractional);
/** /**
* <p>Set time as one unit, including the optional infinite precision * Set time as one unit, including the optional infinite precision
* fractional seconds.</p> * fractional seconds.
* *
* @param hour value constraints are summarized in * @param hour value constraints are summarized in
* <a href="#datetimefield-hour">hour field of date/time field mapping table</a>. * <a href="#datetimefield-hour">hour field of date/time field mapping table</a>.
@ -424,7 +421,7 @@ public abstract class XMLGregorianCalendar
* <a href="#datetimefield-minute">minute field of date/time field mapping table</a>. * <a href="#datetimefield-minute">minute field of date/time field mapping table</a>.
* @param second value constraints are summarized in * @param second value constraints are summarized in
* <a href="#datetimefield-second">second field of date/time field mapping table</a>. * <a href="#datetimefield-second">second field of date/time field mapping table</a>.
* @param fractional value of <code>null</code> indicates this optional * @param fractional value of {@code null} indicates this optional
* field is not set. * field is not set.
* *
* @throws IllegalArgumentException if any parameter is * @throws IllegalArgumentException if any parameter is
@ -445,7 +442,7 @@ public abstract class XMLGregorianCalendar
/** /**
* <p>Set time as one unit, including optional milliseconds.</p> * Set time as one unit, including optional milliseconds.
* *
* @param hour value constraints are summarized in * @param hour value constraints are summarized in
* <a href="#datetimefield-hour">hour field of date/time field mapping table</a>. * <a href="#datetimefield-hour">hour field of date/time field mapping table</a>.
@ -469,13 +466,13 @@ public abstract class XMLGregorianCalendar
} }
/** /**
* <p>Return high order component for XML Schema 1.0 dateTime datatype field for * Return high order component for XML Schema 1.0 dateTime datatype field for
* <code>year</code>. * {@code year}.
* <code>null</code> if this optional part of the year field is not defined.</p> * {@code null} if this optional part of the year field is not defined.
* *
* <p>Value constraints for this value are summarized in * <p>Value constraints for this value are summarized in
* <a href="#datetimefield-year">year field of date/time field mapping table</a>.</p> * <a href="#datetimefield-year">year field of date/time field mapping table</a>.
* @return eon of this <code>XMLGregorianCalendar</code>. The value * @return eon of this {@code XMLGregorianCalendar}. The value
* returned is an integer multiple of 10^9. * returned is an integer multiple of 10^9.
* *
* @see #getYear() * @see #getYear()
@ -484,13 +481,13 @@ public abstract class XMLGregorianCalendar
public abstract BigInteger getEon(); public abstract BigInteger getEon();
/** /**
* <p>Return low order component for XML Schema 1.0 dateTime datatype field for * Return low order component for XML Schema 1.0 dateTime datatype field for
* <code>year</code> or {@link DatatypeConstants#FIELD_UNDEFINED}.</p> * {@code year} or {@link DatatypeConstants#FIELD_UNDEFINED}.
* *
* <p>Value constraints for this value are summarized in * <p>Value constraints for this value are summarized in
* <a href="#datetimefield-year">year field of date/time field mapping table</a>.</p> * <a href="#datetimefield-year">year field of date/time field mapping table</a>.
* *
* @return year of this <code>XMLGregorianCalendar</code>. * @return year of this {@code XMLGregorianCalendar}.
* *
* @see #getEon() * @see #getEon()
* @see #getEonAndYear() * @see #getEonAndYear()
@ -498,16 +495,16 @@ public abstract class XMLGregorianCalendar
public abstract int getYear(); public abstract int getYear();
/** /**
* <p>Return XML Schema 1.0 dateTime datatype field for * Return XML Schema 1.0 dateTime datatype field for
* <code>year</code>.</p> * {@code year}.
* *
* <p>Value constraints for this value are summarized in * <p>Value constraints for this value are summarized in
* <a href="#datetimefield-year">year field of date/time field mapping table</a>.</p> * <a href="#datetimefield-year">year field of date/time field mapping table</a>.
* *
* @return sum of <code>eon</code> and <code>BigInteger.valueOf(year)</code> * @return sum of {@code eon} and {@code BigInteger.valueOf(year)}
* when both fields are defined. When only <code>year</code> is defined, * when both fields are defined. When only {@code year} is defined,
* return it. When both <code>eon</code> and <code>year</code> are not * return it. When both {@code eon} and {@code year} are not
* defined, return <code>null</code>. * defined, return {@code null}.
* *
* @see #getEon() * @see #getEon()
* @see #getYear() * @see #getYear()
@ -515,21 +512,21 @@ public abstract class XMLGregorianCalendar
public abstract BigInteger getEonAndYear(); public abstract BigInteger getEonAndYear();
/** /**
* <p>Return number of month or {@link DatatypeConstants#FIELD_UNDEFINED}.</p> * Return number of month or {@link DatatypeConstants#FIELD_UNDEFINED}.
* *
* <p>Value constraints for this value are summarized in * <p>Value constraints for this value are summarized in
* <a href="#datetimefield-month">month field of date/time field mapping table</a>.</p> * <a href="#datetimefield-month">month field of date/time field mapping table</a>.
* *
* @return year of this <code>XMLGregorianCalendar</code>. * @return year of this {@code XMLGregorianCalendar}.
* *
*/ */
public abstract int getMonth(); public abstract int getMonth();
/** /**
* Return day in month or {@link DatatypeConstants#FIELD_UNDEFINED}.</p> * Return day in month or {@link DatatypeConstants#FIELD_UNDEFINED}.
* *
* <p>Value constraints for this value are summarized in * <p>Value constraints for this value are summarized in
* <a href="#datetimefield-day">day field of date/time field mapping table</a>.</p> * <a href="#datetimefield-day">day field of date/time field mapping table</a>.
* *
* @see #setDay(int) * @see #setDay(int)
*/ */
@ -540,7 +537,7 @@ public abstract class XMLGregorianCalendar
* {@link DatatypeConstants#FIELD_UNDEFINED} if this optional field is not defined. * {@link DatatypeConstants#FIELD_UNDEFINED} if this optional field is not defined.
* *
* <p>Value constraints for this value are summarized in * <p>Value constraints for this value are summarized in
* <a href="#datetimefield-timezone">timezone field of date/time field mapping table</a>.</p> * <a href="#datetimefield-timezone">timezone field of date/time field mapping table</a>.
* *
* @see #setTimezone(int) * @see #setTimezone(int)
*/ */
@ -551,34 +548,34 @@ public abstract class XMLGregorianCalendar
* Returns {@link DatatypeConstants#FIELD_UNDEFINED} if this field is not defined. * Returns {@link DatatypeConstants#FIELD_UNDEFINED} if this field is not defined.
* *
* <p>Value constraints for this value are summarized in * <p>Value constraints for this value are summarized in
* <a href="#datetimefield-hour">hour field of date/time field mapping table</a>.</p> * <a href="#datetimefield-hour">hour field of date/time field mapping table</a>.
* @see #setTime(int, int, int) * @see #setTime(int, int, int)
*/ */
public abstract int getHour(); public abstract int getHour();
/** /**
* Return minutes or {@link DatatypeConstants#FIELD_UNDEFINED}.</p> * Return minutes or {@link DatatypeConstants#FIELD_UNDEFINED}.
* Returns {@link DatatypeConstants#FIELD_UNDEFINED} if this field is not defined. * Returns {@link DatatypeConstants#FIELD_UNDEFINED} if this field is not defined.
* *
* <p>Value constraints for this value are summarized in * <p>Value constraints for this value are summarized in
* <a href="#datetimefield-minute">minute field of date/time field mapping table</a>.</p> * <a href="#datetimefield-minute">minute field of date/time field mapping table</a>.
* @see #setTime(int, int, int) * @see #setTime(int, int, int)
*/ */
public abstract int getMinute(); public abstract int getMinute();
/** /**
* <p>Return seconds or {@link DatatypeConstants#FIELD_UNDEFINED}.</p> * Return seconds or {@link DatatypeConstants#FIELD_UNDEFINED}.
* *
* <p>Returns {@link DatatypeConstants#FIELD_UNDEFINED} if this field is not defined. * <p>Returns {@link DatatypeConstants#FIELD_UNDEFINED} if this field is not defined.
* When this field is not defined, the optional xs:dateTime * When this field is not defined, the optional xs:dateTime
* fractional seconds field, represented by * fractional seconds field, represented by
* {@link #getFractionalSecond()} and {@link #getMillisecond()}, * {@link #getFractionalSecond()} and {@link #getMillisecond()},
* must not be defined.</p> * must not be defined.
* *
* <p>Value constraints for this value are summarized in * <p>Value constraints for this value are summarized in
* <a href="#datetimefield-second">second field of date/time field mapping table</a>.</p> * <a href="#datetimefield-second">second field of date/time field mapping table</a>.
* *
* @return Second of this <code>XMLGregorianCalendar</code>. * @return Second of this {@code XMLGregorianCalendar}.
* *
* @see #getFractionalSecond() * @see #getFractionalSecond()
* @see #getMillisecond() * @see #getMillisecond()
@ -587,20 +584,20 @@ public abstract class XMLGregorianCalendar
public abstract int getSecond(); public abstract int getSecond();
/** /**
* <p>Return millisecond precision of {@link #getFractionalSecond()}.</p> * Return millisecond precision of {@link #getFractionalSecond()}.
* *
* <p>This method represents a convenience accessor to infinite * <p>This method represents a convenience accessor to infinite
* precision fractional second value returned by * precision fractional second value returned by
* {@link #getFractionalSecond()}. The returned value is the rounded * {@link #getFractionalSecond()}. The returned value is the rounded
* down to milliseconds value of * down to milliseconds value of
* {@link #getFractionalSecond()}. When {@link #getFractionalSecond()} * {@link #getFractionalSecond()}. When {@link #getFractionalSecond()}
* returns <code>null</code>, this method must return * returns {@code null}, this method must return
* {@link DatatypeConstants#FIELD_UNDEFINED}.</p> * {@link DatatypeConstants#FIELD_UNDEFINED}.
* *
* <p>Value constraints for this value are summarized in * <p>Value constraints for this value are summarized in
* <a href="#datetimefield-second">second field of date/time field mapping table</a>.</p> * <a href="#datetimefield-second">second field of date/time field mapping table</a>.
* *
* @return Millisecond of this <code>XMLGregorianCalendar</code>. * @return Millisecond of this {@code XMLGregorianCalendar}.
* *
* @see #getFractionalSecond() * @see #getFractionalSecond()
* @see #setTime(int, int, int) * @see #setTime(int, int, int)
@ -618,18 +615,18 @@ public abstract class XMLGregorianCalendar
} }
/** /**
* <p>Return fractional seconds.</p> * Return fractional seconds.
* *
* <p><code>null</code> is returned when this optional field is not defined.</p> * <p>{@code null} is returned when this optional field is not defined.
* *
* <p>Value constraints are detailed in * <p>Value constraints are detailed in
* <a href="#datetimefield-second">second field of date/time field mapping table</a>.</p> * <a href="#datetimefield-second">second field of date/time field mapping table</a>.
* *
* <p>This optional field can only have a defined value when the * <p>This optional field can only have a defined value when the
* xs:dateTime second field, represented by {@link #getSecond()}, * xs:dateTime second field, represented by {@link #getSecond()},
* does not return {@link DatatypeConstants#FIELD_UNDEFINED}.</p> * does not return {@link DatatypeConstants#FIELD_UNDEFINED}.
* *
* @return fractional seconds of this <code>XMLGregorianCalendar</code>. * @return fractional seconds of this {@code XMLGregorianCalendar}.
* *
* @see #getSecond() * @see #getSecond()
* @see #setTime(int, int, int, BigDecimal) * @see #setTime(int, int, int, BigDecimal)
@ -638,51 +635,51 @@ public abstract class XMLGregorianCalendar
// comparisons // comparisons
/** /**
* <p>Compare two instances of W3C XML Schema 1.0 date/time datatypes * Compare two instances of W3C XML Schema 1.0 date/time datatypes
* according to partial order relation defined in * according to partial order relation defined in
* <a href="http://www.w3.org/TR/xmlschema-2/#dateTime-order">W3C XML Schema 1.0 Part 2, Section 3.2.7.3, * <a href="http://www.w3.org/TR/xmlschema-2/#dateTime-order">W3C XML Schema 1.0 Part 2, Section 3.2.7.3,
* <i>Order relation on dateTime</i></a>.</p> * <i>Order relation on dateTime</i></a>.
* *
* <p><code>xsd:dateTime</code> datatype field mapping to accessors of * <p>{@code xsd:dateTime} datatype field mapping to accessors of
* this class are defined in * this class are defined in
* <a href="#datetimefieldmapping">date/time field mapping table</a>.</p> * <a href="#datetimefieldmapping">date/time field mapping table</a>.
* *
* @param xmlGregorianCalendar Instance of <code>XMLGregorianCalendar</code> to compare * @param xmlGregorianCalendar Instance of {@code XMLGregorianCalendar} to compare
* *
* @return The relationship between <code>this</code> <code>XMLGregorianCalendar</code> and * @return The relationship between {@code this} {@code XMLGregorianCalendar} and
* the specified <code>xmlGregorianCalendar</code> as * the specified {@code xmlGregorianCalendar} as
* {@link DatatypeConstants#LESSER}, * {@link DatatypeConstants#LESSER},
* {@link DatatypeConstants#EQUAL}, * {@link DatatypeConstants#EQUAL},
* {@link DatatypeConstants#GREATER} or * {@link DatatypeConstants#GREATER} or
* {@link DatatypeConstants#INDETERMINATE}. * {@link DatatypeConstants#INDETERMINATE}.
* *
* @throws NullPointerException if <code>xmlGregorianCalendar</code> is null. * @throws NullPointerException if {@code xmlGregorianCalendar} is null.
*/ */
public abstract int compare(XMLGregorianCalendar xmlGregorianCalendar); public abstract int compare(XMLGregorianCalendar xmlGregorianCalendar);
/** /**
* <p>Normalize this instance to UTC.</p> * Normalize this instance to UTC.
* *
* <p>2000-03-04T23:00:00+03:00 normalizes to 2000-03-04T20:00:00Z</p> * <p>2000-03-04T23:00:00+03:00 normalizes to 2000-03-04T20:00:00Z
* <p>Implements W3C XML Schema Part 2, Section 3.2.7.3 (A).</p> * <p>Implements W3C XML Schema Part 2, Section 3.2.7.3 (A).
* *
* @return <code>this</code> <code>XMLGregorianCalendar</code> normalized to UTC. * @return {@code this} {@code XMLGregorianCalendar} normalized to UTC.
*/ */
public abstract XMLGregorianCalendar normalize(); public abstract XMLGregorianCalendar normalize();
/** /**
* <p>Compares this calendar to the specified object. The result is * Compares this calendar to the specified object. The result is
* <code>true</code> if and only if the argument is not null and is an * {@code true} if and only if the argument is not null and is an
* <code>XMLGregorianCalendar</code> object that represents the same * {@code XMLGregorianCalendar} object that represents the same
* instant in time as this object.</p> * instant in time as this object.
* *
* @param obj to compare. * @param obj to compare.
* *
* @return <code>true</code> when <code>obj</code> is an instance of * @return {@code true} when {@code obj} is an instance of
* <code>XMLGregorianCalendar</code> and * {@code XMLGregorianCalendar} and
* {@link #compare(XMLGregorianCalendar obj)} * {@link #compare(XMLGregorianCalendar obj)}
* returns {@link DatatypeConstants#EQUAL}, * returns {@link DatatypeConstants#EQUAL},
* otherwise <code>false</code>. * otherwise {@code false}.
*/ */
public boolean equals(Object obj) { public boolean equals(Object obj) {
@ -693,7 +690,7 @@ public abstract class XMLGregorianCalendar
} }
/** /**
* <p>Returns a hash code consistent with the definition of the equals method.</p> * Returns a hash code consistent with the definition of the equals method.
* *
* @return hash code of this object. * @return hash code of this object.
*/ */
@ -721,15 +718,15 @@ public abstract class XMLGregorianCalendar
} }
/** /**
* <p>Return the lexical representation of <code>this</code> instance. * Return the lexical representation of {@code this} instance.
* The format is specified in * The format is specified in
* <a href="http://www.w3.org/TR/xmlschema-2/#dateTime-order">XML Schema 1.0 Part 2, Section 3.2.[7-14].1, * <a href="http://www.w3.org/TR/xmlschema-2/#dateTime-order">XML Schema 1.0 Part 2, Section 3.2.[7-14].1,
* <i>Lexical Representation</i>".</a></p> * <i>Lexical Representation</i>".</a>
* *
* <p>Specific target lexical representation format is determined by * <p>Specific target lexical representation format is determined by
* {@link #getXMLSchemaType()}.</p> * {@link #getXMLSchemaType()}.
* *
* @return XML, as <code>String</code>, representation of this <code>XMLGregorianCalendar</code> * @return XML, as {@code String}, representation of this {@code XMLGregorianCalendar}
* *
* @throws IllegalStateException if the combination of set fields * @throws IllegalStateException if the combination of set fields
* does not match one of the eight defined XML Schema builtin date/time datatypes. * does not match one of the eight defined XML Schema builtin date/time datatypes.
@ -737,14 +734,14 @@ public abstract class XMLGregorianCalendar
public abstract String toXMLFormat(); public abstract String toXMLFormat();
/** /**
* <p>Return the name of the XML Schema date/time type that this instance * Return the name of the XML Schema date/time type that this instance
* maps to. Type is computed based on fields that are set.</p> * maps to. Type is computed based on fields that are set.
* *
* <table border="2" rules="all" cellpadding="2"> * <table border="2" rules="all" cellpadding="2">
* <thead> * <thead>
* <tr> * <tr>
* <th align="center" colspan="7"> * <th align="center" colspan="7">
* Required fields for XML Schema 1.0 Date/Time Datatypes.<br/> * Required fields for XML Schema 1.0 Date/Time Datatypes.<br>
* <i>(timezone is optional for all date/time datatypes)</i> * <i>(timezone is optional for all date/time datatypes)</i>
* </th> * </th>
* </tr> * </tr>
@ -850,11 +847,11 @@ public abstract class XMLGregorianCalendar
public abstract QName getXMLSchemaType(); public abstract QName getXMLSchemaType();
/** /**
* <p>Returns a <code>String</code> representation of this <code>XMLGregorianCalendar</code> <code>Object</code>.</p> * Returns a {@code String} representation of this {@code XMLGregorianCalendar} {@code Object}.
* *
* <p>The result is a lexical representation generated by {@link #toXMLFormat()}.</p> * <p>The result is a lexical representation generated by {@link #toXMLFormat()}.
* *
* @return A non-<code>null</code> valid <code>String</code> representation of this <code>XMLGregorianCalendar</code>. * @return A non-{@code null} valid {@code String} representation of this {@code XMLGregorianCalendar}.
* *
* @throws IllegalStateException if the combination of set fields * @throws IllegalStateException if the combination of set fields
* does not match one of the eight defined XML Schema builtin date/time datatypes. * does not match one of the eight defined XML Schema builtin date/time datatypes.
@ -867,89 +864,89 @@ public abstract class XMLGregorianCalendar
} }
/** /**
* Validate instance by <code>getXMLSchemaType()</code> constraints. * Validate instance by {@code getXMLSchemaType()} constraints.
* @return true if data values are valid. * @return true if data values are valid.
*/ */
public abstract boolean isValid(); public abstract boolean isValid();
/** /**
* <p>Add <code>duration</code> to this instance.</p> * Add {@code duration} to this instance.
* *
* <p>The computation is specified in * <p>The computation is specified in
* <a href="http://www.w3.org/TR/xmlschema-2/#adding-durations-to-dateTimes">XML Schema 1.0 Part 2, Appendix E, * <a href="http://www.w3.org/TR/xmlschema-2/#adding-durations-to-dateTimes">XML Schema 1.0 Part 2, Appendix E,
* <i>Adding durations to dateTimes</i>></a>. * <i>Adding durations to dateTimes</i></a>.
* <a href="#datetimefieldmapping">date/time field mapping table</a> * <a href="#datetimefieldmapping">date/time field mapping table</a>
* defines the mapping from XML Schema 1.0 <code>dateTime</code> fields * defines the mapping from XML Schema 1.0 {@code dateTime} fields
* to this class' representation of those fields.</p> * to this class' representation of those fields.
* *
* @param duration Duration to add to this <code>XMLGregorianCalendar</code>. * @param duration Duration to add to this {@code XMLGregorianCalendar}.
* *
* @throws NullPointerException when <code>duration</code> parameter is <code>null</code>. * @throws NullPointerException when {@code duration} parameter is {@code null}.
*/ */
public abstract void add(Duration duration); public abstract void add(Duration duration);
/** /**
* <p>Convert this <code>XMLGregorianCalendar</code> to a {@link GregorianCalendar}.</p> * Convert this {@code XMLGregorianCalendar} to a {@link GregorianCalendar}.
* *
* <p>When <code>this</code> instance has an undefined field, this * <p>When {@code this} instance has an undefined field, this
* conversion relies on the <code>java.util.GregorianCalendar</code> default * conversion relies on the {@code java.util.GregorianCalendar} default
* for its corresponding field. A notable difference between * for its corresponding field. A notable difference between
* XML Schema 1.0 date/time datatypes and <code>java.util.GregorianCalendar</code> * XML Schema 1.0 date/time datatypes and {@code java.util.GregorianCalendar}
* is that Timezone value is optional for date/time datatypes and it is * is that Timezone value is optional for date/time datatypes and it is
* a required field for <code>java.util.GregorianCalendar</code>. See javadoc * a required field for {@code java.util.GregorianCalendar}. See javadoc
* for <code>java.util.TimeZone.getDefault()</code> on how the default * for {@code java.util.TimeZone.getDefault()} on how the default
* is determined. To explicitly specify the <code>TimeZone</code> * is determined. To explicitly specify the {@code TimeZone}
* instance, see * instance, see
* {@link #toGregorianCalendar(TimeZone, Locale, XMLGregorianCalendar)}.</p> * {@link #toGregorianCalendar(TimeZone, Locale, XMLGregorianCalendar)}.
* *
* <table border="2" rules="all" cellpadding="2"> * <table border="2" rules="all" cellpadding="2">
* <thead> * <thead>
* <tr> * <tr>
* <th align="center" colspan="2"> * <th align="center" colspan="2">
* Field by Field Conversion from this class to * Field by Field Conversion from this class to
* <code>java.util.GregorianCalendar</code> * {@code java.util.GregorianCalendar}
* </th> * </th>
* </tr> * </tr>
* </thead> * </thead>
* <tbody> * <tbody>
* <tr> * <tr>
* <td><code>java.util.GregorianCalendar</code> field</td> * <td>{@code java.util.GregorianCalendar} field</td>
* <td><code>javax.xml.datatype.XMLGregorianCalendar</code> field</td> * <td>{@code javax.xml.datatype.XMLGregorianCalendar} field</td>
* </tr> * </tr>
* <tr> * <tr>
* <td><code>ERA</code></td> * <td>{@code ERA}</td>
* <td>{@link #getEonAndYear()}<code>.signum() < 0 ? GregorianCalendar.BC : GregorianCalendar.AD</code></td> * <td>{@link #getEonAndYear()}{@code .signum() < 0 ? GregorianCalendar.BC : GregorianCalendar.AD}</td>
* </tr> * </tr>
* <tr> * <tr>
* <td><code>YEAR</code></td> * <td>{@code YEAR}</td>
* <td>{@link #getEonAndYear()}<code>.abs().intValue()</code><i>*</i></td> * <td>{@link #getEonAndYear()}{@code .abs().intValue()}<i>*</i></td>
* </tr> * </tr>
* <tr> * <tr>
* <td><code>MONTH</code></td> * <td>{@code MONTH}</td>
* <td>{@link #getMonth()} - {@link DatatypeConstants#JANUARY} + {@link GregorianCalendar#JANUARY}</td> * <td>{@link #getMonth()} - {@link DatatypeConstants#JANUARY} + {@link GregorianCalendar#JANUARY}</td>
* </tr> * </tr>
* <tr> * <tr>
* <td><code>DAY_OF_MONTH</code></td> * <td>{@code DAY_OF_MONTH}</td>
* <td>{@link #getDay()}</td> * <td>{@link #getDay()}</td>
* </tr> * </tr>
* <tr> * <tr>
* <td><code>HOUR_OF_DAY</code></td> * <td>{@code HOUR_OF_DAY}</td>
* <td>{@link #getHour()}</td> * <td>{@link #getHour()}</td>
* </tr> * </tr>
* <tr> * <tr>
* <td><code>MINUTE</code></td> * <td>{@code MINUTE}</td>
* <td>{@link #getMinute()}</td> * <td>{@link #getMinute()}</td>
* </tr> * </tr>
* <tr> * <tr>
* <td><code>SECOND</code></td> * <td>{@code SECOND}</td>
* <td>{@link #getSecond()}</td> * <td>{@link #getSecond()}</td>
* </tr> * </tr>
* <tr> * <tr>
* <td><code>MILLISECOND</code></td> * <td>{@code MILLISECOND}</td>
* <td>get millisecond order from {@link #getFractionalSecond()}<i>*</i> </td> * <td>get millisecond order from {@link #getFractionalSecond()}<i>*</i> </td>
* </tr> * </tr>
* <tr> * <tr>
* <td><code>GregorianCalendar.setTimeZone(TimeZone)</code></td> * <td>{@code GregorianCalendar.setTimeZone(TimeZone)}</td>
* <td>{@link #getTimezone()} formatted into Custom timezone id</td> * <td>{@link #getTimezone()} formatted into Custom timezone id</td>
* </tr> * </tr>
* </tbody> * </tbody>
@ -958,74 +955,74 @@ public abstract class XMLGregorianCalendar
* to source datatype having higher precision than target datatype. * to source datatype having higher precision than target datatype.
* *
* <p>To ensure consistency in conversion implementations, the new * <p>To ensure consistency in conversion implementations, the new
* <code>GregorianCalendar</code> should be instantiated in following * {@code GregorianCalendar} should be instantiated in following
* manner. * manner.
* <ul> * <ul>
* <li>Using <code>timeZone</code> value as defined above, create a new * <li>Using {@code timeZone} value as defined above, create a new
* <code>java.util.GregorianCalendar(timeZone,Locale.getDefault())</code>. * {@code java.util.GregorianCalendar(timeZone,Locale.getDefault())}.
* </li> * </li>
* <li>Initialize all GregorianCalendar fields by calling {@link java.util.GregorianCalendar#clear()}.</li> * <li>Initialize all GregorianCalendar fields by calling {@link java.util.GregorianCalendar#clear()}.</li>
* <li>Obtain a pure Gregorian Calendar by invoking * <li>Obtain a pure Gregorian Calendar by invoking
* <code>GregorianCalendar.setGregorianChange( * {@code GregorianCalendar.setGregorianChange(
* new Date(Long.MIN_VALUE))</code>.</li> * new Date(Long.MIN_VALUE))}.</li>
* <li>Its fields ERA, YEAR, MONTH, DAY_OF_MONTH, HOUR_OF_DAY, * <li>Its fields ERA, YEAR, MONTH, DAY_OF_MONTH, HOUR_OF_DAY,
* MINUTE, SECOND and MILLISECOND are set using the method * MINUTE, SECOND and MILLISECOND are set using the method
* <code>Calendar.set(int,int)</code></li> * {@code Calendar.set(int,int)}</li>
* </ul> * </ul>
* </p>
* *
* @see #toGregorianCalendar(java.util.TimeZone, java.util.Locale, XMLGregorianCalendar) * @see #toGregorianCalendar(java.util.TimeZone, java.util.Locale, XMLGregorianCalendar)
*/ */
public abstract GregorianCalendar toGregorianCalendar(); public abstract GregorianCalendar toGregorianCalendar();
/** /**
* <p>Convert this <code>XMLGregorianCalendar</code> along with provided parameters * Convert this {@code XMLGregorianCalendar} along with provided parameters
* to a {@link GregorianCalendar} instance.</p> * to a {@link GregorianCalendar} instance.
* *
* <p> Since XML Schema 1.0 date/time datetypes has no concept of * <p> Since XML Schema 1.0 date/time datetypes has no concept of
* timezone ids or daylight savings timezone ids, this conversion operation * timezone ids or daylight savings timezone ids, this conversion operation
* allows the user to explicitly specify one with * allows the user to explicitly specify one with
* <code>timezone</code> parameter.</p> * {@code timezone} parameter.
* *
* <p>To compute the return value's <code>TimeZone</code> field, * <p>To compute the return value's {@code TimeZone} field,
* <ul> * <ul>
* <li>when parameter <code>timeZone</code> is non-null, * <li>when parameter {@code timeZone} is non-null,
* it is the timezone field.</li> * it is the timezone field.</li>
* <li>else when <code>this.getTimezone() != FIELD_UNDEFINED</code>, * <li>else when {@code this.getTimezone() != FIELD_UNDEFINED},
* create a <code>java.util.TimeZone</code> with a custom timezone id * create a {@code java.util.TimeZone} with a custom timezone id
* using the <code>this.getTimezone()</code>.</li> * using the {@code this.getTimezone()}.</li>
* <li>else when <code>defaults.getTimezone() != FIELD_UNDEFINED</code>, * <li>else when {@code defaults.getTimezone() != FIELD_UNDEFINED},
* create a <code>java.util.TimeZone</code> with a custom timezone id * create a {@code java.util.TimeZone} with a custom timezone id
* using <code>defaults.getTimezone()</code>.</li> * using {@code defaults.getTimezone()}.</li>
* <li>else use the <code>GregorianCalendar</code> default timezone value * <li>else use the {@code GregorianCalendar} default timezone value
* for the host is defined as specified by * for the host is defined as specified by
* <code>java.util.TimeZone.getDefault()</code>.</li></p> * {@code java.util.TimeZone.getDefault()}.</li>
* </ul>
* *
* <p>To ensure consistency in conversion implementations, the new * <p>To ensure consistency in conversion implementations, the new
* <code>GregorianCalendar</code> should be instantiated in following * {@code GregorianCalendar} should be instantiated in following
* manner. * manner.
* <ul> * <ul>
* <li>Create a new <code>java.util.GregorianCalendar(TimeZone, * <li>Create a new {@code java.util.GregorianCalendar(TimeZone,
* Locale)</code> with TimeZone set as specified above and the * Locale)} with TimeZone set as specified above and the
* <code>Locale</code> parameter. * {@code Locale} parameter.
* </li> * </li>
* <li>Initialize all GregorianCalendar fields by calling {@link GregorianCalendar#clear()}</li> * <li>Initialize all GregorianCalendar fields by calling {@link GregorianCalendar#clear()}</li>
* <li>Obtain a pure Gregorian Calendar by invoking * <li>Obtain a pure Gregorian Calendar by invoking
* <code>GregorianCalendar.setGregorianChange( * {@code GregorianCalendar.setGregorianChange(
* new Date(Long.MIN_VALUE))</code>.</li> * new Date(Long.MIN_VALUE))}.</li>
* <li>Its fields ERA, YEAR, MONTH, DAY_OF_MONTH, HOUR_OF_DAY, * <li>Its fields ERA, YEAR, MONTH, DAY_OF_MONTH, HOUR_OF_DAY,
* MINUTE, SECOND and MILLISECOND are set using the method * MINUTE, SECOND and MILLISECOND are set using the method
* <code>Calendar.set(int,int)</code></li> * {@code Calendar.set(int,int)}</li>
* </ul> * </ul>
* *
* @param timezone provide Timezone. <code>null</code> is a legal value. * @param timezone provide Timezone. {@code null} is a legal value.
* @param aLocale provide explicit Locale. Use default GregorianCalendar locale if * @param aLocale provide explicit Locale. Use default GregorianCalendar locale if
* value is <code>null</code>. * value is {@code null}.
* @param defaults provide default field values to use when corresponding * @param defaults provide default field values to use when corresponding
* field for this instance is FIELD_UNDEFINED or null. * field for this instance is FIELD_UNDEFINED or null.
* If <code>defaults</code>is <code>null</code> or a field * If {@code defaults}is {@code null} or a field
* within the specified <code>defaults</code> is undefined, * within the specified {@code defaults} is undefined,
* just use <code>java.util.GregorianCalendar</code> defaults. * just use {@code java.util.GregorianCalendar} defaults.
* @return a java.util.GregorianCalendar conversion of this instance. * @return a java.util.GregorianCalendar conversion of this instance.
*/ */
public abstract GregorianCalendar toGregorianCalendar( public abstract GregorianCalendar toGregorianCalendar(
@ -1034,7 +1031,7 @@ public abstract class XMLGregorianCalendar
XMLGregorianCalendar defaults); XMLGregorianCalendar defaults);
/** /**
* <p>Returns a <code>java.util.TimeZone</code> for this class.</p> * Returns a {@code java.util.TimeZone} for this class.
* *
* <p>If timezone field is defined for this instance, * <p>If timezone field is defined for this instance,
* returns TimeZone initialized with custom timezone id * returns TimeZone initialized with custom timezone id
@ -1042,7 +1039,7 @@ public abstract class XMLGregorianCalendar
* try the defaultZoneoffset that was passed in. * try the defaultZoneoffset that was passed in.
* If defaultZoneoffset is FIELD_UNDEFINED, return * If defaultZoneoffset is FIELD_UNDEFINED, return
* default timezone for this host. * default timezone for this host.
* (Same default as java.util.GregorianCalendar).</p> * (Same default as java.util.GregorianCalendar).
* *
* @param defaultZoneoffset default zoneoffset if this zoneoffset is * @param defaultZoneoffset default zoneoffset if this zoneoffset is
* {@link DatatypeConstants#FIELD_UNDEFINED}. * {@link DatatypeConstants#FIELD_UNDEFINED}.
@ -1054,9 +1051,9 @@ public abstract class XMLGregorianCalendar
/** /**
* <p>Creates and returns a copy of this object.</p> * Creates and returns a copy of this object.
* *
* @return copy of this <code>Object</code> * @return copy of this {@code Object}
*/ */
public abstract Object clone(); public abstract Object clone();
} }

144
jaxp/src/java.xml/share/classes/javax/xml/namespace/NamespaceContext.java
View file

@ -28,44 +28,44 @@ package javax.xml.namespace;
import java.util.Iterator; import java.util.Iterator;
/** /**
* <p>Interface for read only XML Namespace context processing.</p> * Interface for read only XML Namespace context processing.
* *
* <p>An XML Namespace has the properties:</p> * <p>An XML Namespace has the properties:
* <ul> * <ul>
* <li>Namespace URI: * <li>Namespace URI:
* Namespace name expressed as a URI to which the prefix is bound</li> * Namespace name expressed as a URI to which the prefix is bound</li>
* <li>prefix: syntactically, this is the part of the attribute name * <li>prefix: syntactically, this is the part of the attribute name
* following the <code>XMLConstants.XMLNS_ATTRIBUTE</code> * following the {@code XMLConstants.XMLNS_ATTRIBUTE}
* ("xmlns") in the Namespace declaration</li> * ("xmlns") in the Namespace declaration</li>
* </ul> * </ul>
* <p>example: * <p>example:
* <code>&lt;element xmlns:prefix="http://Namespace-name-URI"&gt;</code></p> * {@code <element xmlns:prefix="http://Namespace-name-URI">}
* *
* <p>All <code>get*(*)</code> methods operate in the current scope * <p>All {@code get*(*)} methods operate in the current scope
* for Namespace URI and prefix resolution.</p> * for Namespace URI and prefix resolution.
* *
* <p>Note that a Namespace URI can be bound to * <p>Note that a Namespace URI can be bound to
* <strong>multiple</strong> prefixes in the current scope. This can * <strong>multiple</strong> prefixes in the current scope. This can
* occur when multiple <code>XMLConstants.XMLNS_ATTRIBUTE</code> * occur when multiple {@code XMLConstants.XMLNS_ATTRIBUTE}
* ("xmlns") Namespace declarations occur in the same Start-Tag and * ("xmlns") Namespace declarations occur in the same Start-Tag and
* refer to the same Namespace URI. e.g.<br /> * refer to the same Namespace URI. e.g.<br>
* <pre> * <pre> {@code
* &lt;element xmlns:prefix1="http://Namespace-name-URI" * <element xmlns:prefix1="http://Namespace-name-URI"
* xmlns:prefix2="http://Namespace-name-URI"&gt; * xmlns:prefix2="http://Namespace-name-URI"> }
* </pre> * </pre>
* This can also occur when the same Namespace URI is used in multiple * This can also occur when the same Namespace URI is used in multiple
* <code>XMLConstants.XMLNS_ATTRIBUTE</code> ("xmlns") Namespace * {@code XMLConstants.XMLNS_ATTRIBUTE} ("xmlns") Namespace
* declarations in the logical parent element hierarchy. e.g.<br /> * declarations in the logical parent element hierarchy. e.g.<br>
* <pre> * <pre> {@code
* &lt;parent xmlns:prefix1="http://Namespace-name-URI"> * <parent xmlns:prefix1="http://Namespace-name-URI">
* &lt;child xmlns:prefix2="http://Namespace-name-URI"&gt; * <child xmlns:prefix2="http://Namespace-name-URI">
* ... * ...
* &lt;/child&gt; * </child>
* &lt;/parent&gt; * </parent> }
* </pre></p> * </pre>
* *
* <p>A prefix can only be bound to a <strong>single</strong> * <p>A prefix can only be bound to a <strong>single</strong>
* Namespace URI in the current scope.</p> * Namespace URI in the current scope.
* *
* @author <a href="mailto:Jeff.Suttor@Sun.com">Jeff Suttor</a> * @author <a href="mailto:Jeff.Suttor@Sun.com">Jeff Suttor</a>
* @see javax.xml.XMLConstants * @see javax.xml.XMLConstants
@ -82,17 +82,17 @@ import java.util.Iterator;
public interface NamespaceContext { public interface NamespaceContext {
/** /**
* <p>Get Namespace URI bound to a prefix in the current scope.</p> * Get Namespace URI bound to a prefix in the current scope.
* *
* <p>When requesting a Namespace URI by prefix, the following * <p>When requesting a Namespace URI by prefix, the following
* table describes the returned Namespace URI value for all * table describes the returned Namespace URI value for all
* possible prefix values:</p> * possible prefix values:
* *
* <table border="2" rules="all" cellpadding="4"> * <table border="2" rules="all" cellpadding="4">
* <thead> * <thead>
* <tr> * <tr>
* <td align="center" colspan="2"> * <td align="center" colspan="2">
* <code>getNamespaceURI(prefix)</code> * {@code getNamespaceURI(prefix)}
* return value for specified prefixes * return value for specified prefixes
* </td> * </td>
* </tr> * </tr>
@ -103,9 +103,9 @@ public interface NamespaceContext {
* </thead> * </thead>
* <tbody> * <tbody>
* <tr> * <tr>
* <td><code>DEFAULT_NS_PREFIX</code> ("")</td> * <td>{@code DEFAULT_NS_PREFIX} ("")</td>
* <td>default Namespace URI in the current scope or * <td>default Namespace URI in the current scope or
* <code>{@link * <code> {@link
* javax.xml.XMLConstants#NULL_NS_URI XMLConstants.NULL_NS_URI("")} * javax.xml.XMLConstants#NULL_NS_URI XMLConstants.NULL_NS_URI("")}
* </code> * </code>
* when there is no default Namespace URI in the current scope</td> * when there is no default Namespace URI in the current scope</td>
@ -117,24 +117,24 @@ public interface NamespaceContext {
* <tr> * <tr>
* <td>unbound prefix</td> * <td>unbound prefix</td>
* <td> * <td>
* <code>{@link * <code> {@link
* javax.xml.XMLConstants#NULL_NS_URI XMLConstants.NULL_NS_URI("")} * javax.xml.XMLConstants#NULL_NS_URI XMLConstants.NULL_NS_URI("")}
* </code> * </code>
* </td> * </td>
* </tr> * </tr>
* <tr> * <tr>
* <td><code>XMLConstants.XML_NS_PREFIX</code> ("xml")</td> * <td>{@code XMLConstants.XML_NS_PREFIX} ("xml")</td>
* <td><code>XMLConstants.XML_NS_URI</code> * <td>{@code XMLConstants.XML_NS_URI}
* ("http://www.w3.org/XML/1998/namespace")</td> * ("http://www.w3.org/XML/1998/namespace")</td>
* </tr> * </tr>
* <tr> * <tr>
* <td><code>XMLConstants.XMLNS_ATTRIBUTE</code> ("xmlns")</td> * <td>{@code XMLConstants.XMLNS_ATTRIBUTE} ("xmlns")</td>
* <td><code>XMLConstants.XMLNS_ATTRIBUTE_NS_URI</code> * <td>{@code XMLConstants.XMLNS_ATTRIBUTE_NS_URI}
* ("http://www.w3.org/2000/xmlns/")</td> * ("http://www.w3.org/2000/xmlns/")</td>
* </tr> * </tr>
* <tr> * <tr>
* <td><code>null</code></td> * <td>{@code null}</td>
* <td><code>IllegalArgumentException</code> is thrown</td> * <td>{@code IllegalArgumentException} is thrown</td>
* </tr> * </tr>
* </tbody> * </tbody>
* </table> * </table>
@ -143,26 +143,26 @@ public interface NamespaceContext {
* *
* @return Namespace URI bound to prefix in the current scope * @return Namespace URI bound to prefix in the current scope
* *
* @throws IllegalArgumentException When <code>prefix</code> is * @throws IllegalArgumentException When {@code prefix} is
* <code>null</code> * {@code null}
*/ */
String getNamespaceURI(String prefix); String getNamespaceURI(String prefix);
/** /**
* <p>Get prefix bound to Namespace URI in the current scope.</p> * Get prefix bound to Namespace URI in the current scope.
* *
* <p>To get all prefixes bound to a Namespace URI in the current * <p>To get all prefixes bound to a Namespace URI in the current
* scope, use {@link #getPrefixes(String namespaceURI)}.</p> * scope, use {@link #getPrefixes(String namespaceURI)}.
* *
* <p>When requesting a prefix by Namespace URI, the following * <p>When requesting a prefix by Namespace URI, the following
* table describes the returned prefix value for all Namespace URI * table describes the returned prefix value for all Namespace URI
* values:</p> * values:
* *
* <table border="2" rules="all" cellpadding="4"> * <table border="2" rules="all" cellpadding="4">
* <thead> * <thead>
* <tr> * <tr>
* <th align="center" colspan="2"> * <th align="center" colspan="2">
* <code>getPrefix(namespaceURI)</code> return value for * {@code getPrefix(namespaceURI)} return value for
* specified Namespace URIs * specified Namespace URIs
* </th> * </th>
* </tr> * </tr>
@ -173,8 +173,8 @@ public interface NamespaceContext {
* </thead> * </thead>
* <tbody> * <tbody>
* <tr> * <tr>
* <td>&lt;default Namespace URI&gt;</td> * <td>{@code <default Namespace URI>}</td>
* <td><code>XMLConstants.DEFAULT_NS_PREFIX</code> ("") * <td>{@code XMLConstants.DEFAULT_NS_PREFIX} ("")
* </td> * </td>
* </tr> * </tr>
* <tr> * <tr>
@ -186,21 +186,21 @@ public interface NamespaceContext {
* </tr> * </tr>
* <tr> * <tr>
* <td>unbound Namespace URI</td> * <td>unbound Namespace URI</td>
* <td><code>null</code></td> * <td>{@code null}</td>
* </tr> * </tr>
* <tr> * <tr>
* <td><code>XMLConstants.XML_NS_URI</code> * <td>{@code XMLConstants.XML_NS_URI}
* ("http://www.w3.org/XML/1998/namespace")</td> * ("http://www.w3.org/XML/1998/namespace")</td>
* <td><code>XMLConstants.XML_NS_PREFIX</code> ("xml")</td> * <td>{@code XMLConstants.XML_NS_PREFIX} ("xml")</td>
* </tr> * </tr>
* <tr> * <tr>
* <td><code>XMLConstants.XMLNS_ATTRIBUTE_NS_URI</code> * <td>{@code XMLConstants.XMLNS_ATTRIBUTE_NS_URI}
* ("http://www.w3.org/2000/xmlns/")</td> * ("http://www.w3.org/2000/xmlns/")</td>
* <td><code>XMLConstants.XMLNS_ATTRIBUTE</code> ("xmlns")</td> * <td>{@code XMLConstants.XMLNS_ATTRIBUTE} ("xmlns")</td>
* </tr> * </tr>
* <tr> * <tr>
* <td><code>null</code></td> * <td>{@code null}</td>
* <td><code>IllegalArgumentException</code> is thrown</td> * <td>{@code IllegalArgumentException} is thrown</td>
* </tr> * </tr>
* </tbody> * </tbody>
* </table> * </table>
@ -209,32 +209,32 @@ public interface NamespaceContext {
* *
* @return prefix bound to Namespace URI in current context * @return prefix bound to Namespace URI in current context
* *
* @throws IllegalArgumentException When <code>namespaceURI</code> is * @throws IllegalArgumentException When {@code namespaceURI} is
* <code>null</code> * {@code null}
*/ */
String getPrefix(String namespaceURI); String getPrefix(String namespaceURI);
/** /**
* <p>Get all prefixes bound to a Namespace URI in the current * Get all prefixes bound to a Namespace URI in the current
* scope.</p> * scope.
* *
* <p>An Iterator over String elements is returned in an arbitrary, * <p>An Iterator over String elements is returned in an arbitrary,
* <strong>implementation dependent</strong>, order.</p> * <strong>implementation dependent</strong>, order.
* *
* <p><strong>The <code>Iterator</code> is * <p><strong>The {@code Iterator} is
* <em>not</em> modifiable. e.g. the * <em>not</em> modifiable. e.g. the
* <code>remove()</code> method will throw * {@code remove()} method will throw
* <code>UnsupportedOperationException</code>.</strong></p> * {@code UnsupportedOperationException}.</strong>
* *
* <p>When requesting prefixes by Namespace URI, the following * <p>When requesting prefixes by Namespace URI, the following
* table describes the returned prefixes value for all Namespace * table describes the returned prefixes value for all Namespace
* URI values:</p> * URI values:
* *
* <table border="2" rules="all" cellpadding="4"> * <table border="2" rules="all" cellpadding="4">
* <thead> * <thead>
* <tr> * <tr>
* <th align="center" colspan="2"><code> * <th align="center" colspan="2">{@code
* getPrefixes(namespaceURI)</code> return value for * getPrefixes(namespaceURI)} return value for
* specified Namespace URIs</th> * specified Namespace URIs</th>
* </tr> * </tr>
* <tr> * <tr>
@ -245,9 +245,9 @@ public interface NamespaceContext {
* <tbody> * <tbody>
* <tr> * <tr>
* <td>bound Namespace URI, * <td>bound Namespace URI,
* including the &lt;default Namespace URI&gt;</td> * including the {@code <default Namespace URI>}</td>
* <td> * <td>
* <code>Iterator</code> over prefixes bound to Namespace URI in * {@code Iterator} over prefixes bound to Namespace URI in
* the current scope in an arbitrary, * the current scope in an arbitrary,
* <strong>implementation dependent</strong>, * <strong>implementation dependent</strong>,
* order * order
@ -255,34 +255,34 @@ public interface NamespaceContext {
* </tr> * </tr>
* <tr> * <tr>
* <td>unbound Namespace URI</td> * <td>unbound Namespace URI</td>
* <td>empty <code>Iterator</code></td> * <td>empty {@code Iterator}</td>
* </tr> * </tr>
* <tr> * <tr>
* <td><code>XMLConstants.XML_NS_URI</code> * <td>{@code XMLConstants.XML_NS_URI}
* ("http://www.w3.org/XML/1998/namespace")</td> * ("http://www.w3.org/XML/1998/namespace")</td>
* <td><code>Iterator</code> with one element set to * <td>{@code Iterator} with one element set to
* <code>XMLConstants.XML_NS_PREFIX</code> ("xml")</td> * {@code XMLConstants.XML_NS_PREFIX} ("xml")</td>
* </tr> * </tr>
* <tr> * <tr>
* <td><code>XMLConstants.XMLNS_ATTRIBUTE_NS_URI</code> * <td>{@code XMLConstants.XMLNS_ATTRIBUTE_NS_URI}
* ("http://www.w3.org/2000/xmlns/")</td> * ("http://www.w3.org/2000/xmlns/")</td>
* <td><code>Iterator</code> with one element set to * <td>{@code Iterator} with one element set to
* <code>XMLConstants.XMLNS_ATTRIBUTE</code> ("xmlns")</td> * {@code XMLConstants.XMLNS_ATTRIBUTE} ("xmlns")</td>
* </tr> * </tr>
* <tr> * <tr>
* <td><code>null</code></td> * <td>{@code null}</td>
* <td><code>IllegalArgumentException</code> is thrown</td> * <td>{@code IllegalArgumentException} is thrown</td>
* </tr> * </tr>
* </tbody> * </tbody>
* </table> * </table>
* *
* @param namespaceURI URI of Namespace to lookup * @param namespaceURI URI of Namespace to lookup
* *
* @return <code>Iterator</code> for all prefixes bound to the * @return {@code Iterator} for all prefixes bound to the
* Namespace URI in the current scope * Namespace URI in the current scope
* *
* @throws IllegalArgumentException When <code>namespaceURI</code> is * @throws IllegalArgumentException When {@code namespaceURI} is
* <code>null</code> * {@code null}
*/ */
Iterator getPrefixes(String namespaceURI); Iterator getPrefixes(String namespaceURI);
} }

103
jaxp/src/java.xml/share/classes/javax/xml/parsers/DocumentBuilderFactory.java
View file

@ -47,8 +47,8 @@ public abstract class DocumentBuilderFactory {
private boolean coalescing = false; private boolean coalescing = false;
/** /**
* <p>Protected constructor to prevent instantiation. * Protected constructor to prevent instantiation.
* Use {@link #newInstance()}.</p> * Use {@link #newInstance()}.
*/ */
protected DocumentBuilderFactory () { protected DocumentBuilderFactory () {
} }
@ -60,7 +60,6 @@ public abstract class DocumentBuilderFactory {
* This method uses the following ordered lookup procedure to determine * This method uses the following ordered lookup procedure to determine
* the {@code DocumentBuilderFactory} implementation class to * the {@code DocumentBuilderFactory} implementation class to
* load: * load:
* <p>
* <ul> * <ul>
* <li> * <li>
* Use the {@code javax.xml.parsers.DocumentBuilderFactory} system * Use the {@code javax.xml.parsers.DocumentBuilderFactory} system
@ -131,7 +130,7 @@ public abstract class DocumentBuilderFactory {
} }
/** /**
* <p>Obtain a new instance of a {@code DocumentBuilderFactory} from class name. * Obtain a new instance of a {@code DocumentBuilderFactory} from class name.
* This function is useful when there are multiple providers in the classpath. * This function is useful when there are multiple providers in the classpath.
* It gives more control to the application as it can specify which provider * It gives more control to the application as it can specify which provider
* should be loaded. * should be loaded.
@ -143,21 +142,22 @@ public abstract class DocumentBuilderFactory {
* <h2>Tip for Trouble-shooting</h2> * <h2>Tip for Trouble-shooting</h2>
* <p>Setting the {@code jaxp.debug} system property will cause * <p>Setting the {@code jaxp.debug} system property will cause
* this method to print a lot of debug messages * this method to print a lot of debug messages
* to {@code System.err} about what it is doing and where it is looking at.</p> * to {@code System.err} about what it is doing and where it is looking at.
* *
* <p> If you have problems try:</p> * <p> If you have problems try:
* <pre> * <pre>
* java -Djaxp.debug=1 YourProgram .... * java -Djaxp.debug=1 YourProgram ....
* </pre> * </pre>
* *
* @param factoryClassName fully qualified factory class name that provides implementation of {@code javax.xml.parsers.DocumentBuilderFactory}. * @param factoryClassName fully qualified factory class name that provides
* implementation of {@code javax.xml.parsers.DocumentBuilderFactory}.
* *
* @param classLoader <code>ClassLoader</code> used to load the factory class. If <code>null</code> * @param classLoader {@code ClassLoader} used to load the factory class. If {@code null}
* current <code>Thread</code>'s context classLoader is used to load the factory class. * current {@code Thread}'s context classLoader is used to load the factory class.
* *
* @return New instance of a {@code DocumentBuilderFactory} * @return New instance of a {@code DocumentBuilderFactory}
* *
* @throws FactoryConfigurationError if <code>factoryClassName</code> is <code>null</code>, or * @throws FactoryConfigurationError if {@code factoryClassName} is {@code null}, or
* the factory class cannot be loaded, instantiated. * the factory class cannot be loaded, instantiated.
* *
* @see #newInstance() * @see #newInstance()
@ -187,7 +187,7 @@ public abstract class DocumentBuilderFactory {
/** /**
* Specifies that the parser produced by this code will * Specifies that the parser produced by this code will
* provide support for XML namespaces. By default the value of this is set * provide support for XML namespaces. By default the value of this is set
* to <code>false</code> * to {@code false}
* *
* @param awareness true if the parser produced will provide support * @param awareness true if the parser produced will provide support
* for XML namespaces; false otherwise. * for XML namespaces; false otherwise.
@ -200,7 +200,7 @@ public abstract class DocumentBuilderFactory {
/** /**
* Specifies that the parser produced by this code will * Specifies that the parser produced by this code will
* validate documents as they are parsed. By default the value of this * validate documents as they are parsed. By default the value of this
* is set to <code>false</code>. * is set to {@code false}.
* *
* <p> * <p>
* Note that "the validation" here means * Note that "the validation" here means
@ -208,15 +208,13 @@ public abstract class DocumentBuilderFactory {
* parser</a> as defined in the XML recommendation. * parser</a> as defined in the XML recommendation.
* In other words, it essentially just controls the DTD validation. * In other words, it essentially just controls the DTD validation.
* (except the legacy two properties defined in JAXP 1.2.) * (except the legacy two properties defined in JAXP 1.2.)
* </p>
* *
* <p> * <p>
* To use modern schema languages such as W3C XML Schema or * To use modern schema languages such as W3C XML Schema or
* RELAX NG instead of DTD, you can configure your parser to be * RELAX NG instead of DTD, you can configure your parser to be
* a non-validating parser by leaving the {@link #setValidating(boolean)} * a non-validating parser by leaving the {@link #setValidating(boolean)}
* method <code>false</code>, then use the {@link #setSchema(Schema)} * method {@code false}, then use the {@link #setSchema(Schema)}
* method to associate a schema to a parser. * method to associate a schema to a parser.
* </p>
* *
* @param validating true if the parser produced will validate documents * @param validating true if the parser produced will validate documents
* as they are parsed; false otherwise. * as they are parsed; false otherwise.
@ -234,7 +232,7 @@ public abstract class DocumentBuilderFactory {
* element content that has an element only content model (see XML * element content that has an element only content model (see XML
* Rec 3.2.1) will be eliminated. Due to reliance on the content model * Rec 3.2.1) will be eliminated. Due to reliance on the content model
* this setting requires the parser to be in validating mode. By default * this setting requires the parser to be in validating mode. By default
* the value of this is set to <code>false</code>. * the value of this is set to {@code false}.
* *
* @param whitespace true if the parser created must eliminate whitespace * @param whitespace true if the parser created must eliminate whitespace
* in the element content when parsing XML documents; * in the element content when parsing XML documents;
@ -248,7 +246,7 @@ public abstract class DocumentBuilderFactory {
/** /**
* Specifies that the parser produced by this code will * Specifies that the parser produced by this code will
* expand entity reference nodes. By default the value of this is set to * expand entity reference nodes. By default the value of this is set to
* <code>true</code> * {@code true}
* *
* @param expandEntityRef true if the parser produced will expand entity * @param expandEntityRef true if the parser produced will expand entity
* reference nodes; false otherwise. * reference nodes; false otherwise.
@ -259,11 +257,10 @@ public abstract class DocumentBuilderFactory {
} }
/** /**
* <p>Specifies that the parser produced by this code will * Specifies that the parser produced by this code will
* ignore comments. By default the value of this is set to <code>false * ignore comments. By default the value of this is set to {@code false}.
* </code>.</p>
* *
* @param ignoreComments <code>boolean</code> value to ignore comments during processing * @param ignoreComments {@code boolean} value to ignore comments during processing
*/ */
public void setIgnoringComments(boolean ignoreComments) { public void setIgnoringComments(boolean ignoreComments) {
@ -274,7 +271,7 @@ public abstract class DocumentBuilderFactory {
* Specifies that the parser produced by this code will * Specifies that the parser produced by this code will
* convert CDATA nodes to Text nodes and append it to the * convert CDATA nodes to Text nodes and append it to the
* adjacent (if any) text node. By default the value of this is set to * adjacent (if any) text node. By default the value of this is set to
* <code>false</code> * {@code false}
* *
* @param coalescing true if the parser produced will convert CDATA nodes * @param coalescing true if the parser produced will convert CDATA nodes
* to Text nodes and append it to the adjacent (if any) * to Text nodes and append it to the adjacent (if any)
@ -367,25 +364,23 @@ public abstract class DocumentBuilderFactory {
* All implementations that implement JAXP 1.5 or newer are required to * All implementations that implement JAXP 1.5 or newer are required to
* support the {@link javax.xml.XMLConstants#ACCESS_EXTERNAL_DTD} and * support the {@link javax.xml.XMLConstants#ACCESS_EXTERNAL_DTD} and
* {@link javax.xml.XMLConstants#ACCESS_EXTERNAL_SCHEMA} properties. * {@link javax.xml.XMLConstants#ACCESS_EXTERNAL_SCHEMA} properties.
* </p> *
* <ul> * <ul>
* <li> * <li>
* <p>
* Setting the {@link javax.xml.XMLConstants#ACCESS_EXTERNAL_DTD} property * Setting the {@link javax.xml.XMLConstants#ACCESS_EXTERNAL_DTD} property
* restricts the access to external DTDs, external Entity References to the * restricts the access to external DTDs, external Entity References to the
* protocols specified by the property. * protocols specified by the property.
* If access is denied during parsing due to the restriction of this property, * If access is denied during parsing due to the restriction of this property,
* {@link org.xml.sax.SAXException} will be thrown by the parse methods defined by * {@link org.xml.sax.SAXException} will be thrown by the parse methods defined by
* {@link javax.xml.parsers.DocumentBuilder}. * {@link javax.xml.parsers.DocumentBuilder}.
* </p> * </li>
* <p> * <li>
* Setting the {@link javax.xml.XMLConstants#ACCESS_EXTERNAL_SCHEMA} property * Setting the {@link javax.xml.XMLConstants#ACCESS_EXTERNAL_SCHEMA} property
* restricts the access to external Schema set by the schemaLocation attribute to * restricts the access to external Schema set by the schemaLocation attribute to
* the protocols specified by the property. If access is denied during parsing * the protocols specified by the property. If access is denied during parsing
* due to the restriction of this property, {@link org.xml.sax.SAXException} * due to the restriction of this property, {@link org.xml.sax.SAXException}
* will be thrown by the parse methods defined by * will be thrown by the parse methods defined by
* {@link javax.xml.parsers.DocumentBuilder}. * {@link javax.xml.parsers.DocumentBuilder}.
* </p>
* </li> * </li>
* </ul> * </ul>
* *
@ -413,61 +408,61 @@ public abstract class DocumentBuilderFactory {
throws IllegalArgumentException; throws IllegalArgumentException;
/** /**
* <p>Set a feature for this {@code DocumentBuilderFactory} and <code>DocumentBuilder</code>s created by this factory.</p> * Set a feature for this {@code DocumentBuilderFactory}
* and {@code DocumentBuilder}s created by this factory.
* *
* <p> * <p>
* Feature names are fully qualified {@link java.net.URI}s. * Feature names are fully qualified {@link java.net.URI}s.
* Implementations may define their own features. * Implementations may define their own features.
* A {@link ParserConfigurationException} is thrown if this {@code DocumentBuilderFactory} or the * A {@link ParserConfigurationException} is thrown if this {@code DocumentBuilderFactory} or the
* <code>DocumentBuilder</code>s it creates cannot support the feature. * {@code DocumentBuilder}s it creates cannot support the feature.
* It is possible for a {@code DocumentBuilderFactory} to expose a feature value but be unable to change its state. * It is possible for a {@code DocumentBuilderFactory} to expose a feature value but be unable to change its state.
* </p> *
* *
* <p> * <p>
* All implementations are required to support the {@link javax.xml.XMLConstants#FEATURE_SECURE_PROCESSING} feature. * All implementations are required to support the {@link javax.xml.XMLConstants#FEATURE_SECURE_PROCESSING} feature.
* When the feature is:</p> * When the feature is:
* <ul> * <ul>
* <li> * <li>
* <code>true</code>: the implementation will limit XML processing to conform to implementation limits. * {@code true}: the implementation will limit XML processing to conform to implementation limits.
* Examples include entity expansion limits and XML Schema constructs that would consume large amounts of resources. * Examples include entity expansion limits and XML Schema constructs that would consume large amounts of resources.
* If XML processing is limited for security reasons, it will be reported via a call to the registered * If XML processing is limited for security reasons, it will be reported via a call to the registered
* {@link org.xml.sax.ErrorHandler#fatalError(SAXParseException exception)}. * {@link org.xml.sax.ErrorHandler#fatalError(SAXParseException exception)}.
* See {@link DocumentBuilder#setErrorHandler(org.xml.sax.ErrorHandler errorHandler)}. * See {@link DocumentBuilder#setErrorHandler(org.xml.sax.ErrorHandler errorHandler)}.
* </li> * </li>
* <li> * <li>
* <code>false</code>: the implementation will processing XML according to the XML specifications without * {@code false}: the implementation will processing XML according to the XML specifications without
* regard to possible implementation limits. * regard to possible implementation limits.
* </li> * </li>
* </ul> * </ul>
* *
* @param name Feature name. * @param name Feature name.
* @param value Is feature state <code>true</code> or <code>false</code>. * @param value Is feature state {@code true} or {@code false}.
* *
* @throws ParserConfigurationException if this {@code DocumentBuilderFactory} or the <code>DocumentBuilder</code>s * @throws ParserConfigurationException if this {@code DocumentBuilderFactory} or the {@code DocumentBuilder}s
* it creates cannot support this feature. * it creates cannot support this feature.
* @throws NullPointerException If the <code>name</code> parameter is null. * @throws NullPointerException If the {@code name} parameter is null.
* @since 1.5 * @since 1.5
*/ */
public abstract void setFeature(String name, boolean value) public abstract void setFeature(String name, boolean value)
throws ParserConfigurationException; throws ParserConfigurationException;
/** /**
* <p>Get the state of the named feature.</p> * Get the state of the named feature.
* *
* <p> * <p>
* Feature names are fully qualified {@link java.net.URI}s. * Feature names are fully qualified {@link java.net.URI}s.
* Implementations may define their own features. * Implementations may define their own features.
* An {@link ParserConfigurationException} is thrown if this {@code DocumentBuilderFactory} or the * An {@link ParserConfigurationException} is thrown if this {@code DocumentBuilderFactory} or the
* <code>DocumentBuilder</code>s it creates cannot support the feature. * {@code DocumentBuilder}s it creates cannot support the feature.
* It is possible for an {@code DocumentBuilderFactory} to expose a feature value but be unable to change its state. * It is possible for an {@code DocumentBuilderFactory} to expose a feature value but be unable to change its state.
* </p>
* *
* @param name Feature name. * @param name Feature name.
* *
* @return State of the named feature. * @return State of the named feature.
* *
* @throws ParserConfigurationException if this {@code DocumentBuilderFactory} * @throws ParserConfigurationException if this {@code DocumentBuilderFactory}
* or the <code>DocumentBuilder</code>s it creates cannot support this feature. * or the {@code DocumentBuilder}s it creates cannot support this feature.
* @since 1.5 * @since 1.5
*/ */
public abstract boolean getFeature(String name) public abstract boolean getFeature(String name)
@ -501,7 +496,7 @@ public abstract class DocumentBuilderFactory {
} }
/** /**
* <p>Set the {@link Schema} to be used by parsers created * Set the {@link Schema} to be used by parsers created
* from this factory. * from this factory.
* *
* <p> * <p>
@ -529,26 +524,26 @@ public abstract class DocumentBuilderFactory {
* *
* <p> * <p>
* This processing will take effect even if * This processing will take effect even if
* the {@link #isValidating()} method returns <code>false</code>. * the {@link #isValidating()} method returns {@code false}.
* *
* <p>It is an error to use * <p>It is an error to use
* the <code>http://java.sun.com/xml/jaxp/properties/schemaSource</code> * the {@code http://java.sun.com/xml/jaxp/properties/schemaSource}
* property and/or the <code>http://java.sun.com/xml/jaxp/properties/schemaLanguage</code> * property and/or the {@code http://java.sun.com/xml/jaxp/properties/schemaLanguage}
* property in conjunction with a {@link Schema} object. * property in conjunction with a {@link Schema} object.
* Such configuration will cause a {@link ParserConfigurationException} * Such configuration will cause a {@link ParserConfigurationException}
* exception when the {@link #newDocumentBuilder()} is invoked.</p> * exception when the {@link #newDocumentBuilder()} is invoked.
* *
* *
* <h4>Note for implementors</h4> * <h3>Note for implementors</h3>
* *
* <p> * <p>
* A parser must be able to work with any {@link Schema} * A parser must be able to work with any {@link Schema}
* implementation. However, parsers and schemas are allowed * implementation. However, parsers and schemas are allowed
* to use implementation-specific custom mechanisms * to use implementation-specific custom mechanisms
* as long as they yield the result described in the specification. * as long as they yield the result described in the specification.
* </p>
* *
* @param schema <code>Schema</code> to use or <code>null</code> *
* @param schema {@code Schema} to use or {@code null}
* to remove a schema. * to remove a schema.
* *
* @throws UnsupportedOperationException When implementation does not * @throws UnsupportedOperationException When implementation does not
@ -569,16 +564,16 @@ public abstract class DocumentBuilderFactory {
/** /**
* <p>Set state of XInclude processing.</p> * Set state of XInclude processing.
* *
* <p>If XInclude markup is found in the document instance, should it be * <p>If XInclude markup is found in the document instance, should it be
* processed as specified in <a href="http://www.w3.org/TR/xinclude/"> * processed as specified in <a href="http://www.w3.org/TR/xinclude/">
* XML Inclusions (XInclude) Version 1.0</a>.</p> * XML Inclusions (XInclude) Version 1.0</a>.
* *
* <p>XInclude processing defaults to <code>false</code>.</p> * <p>XInclude processing defaults to {@code false}.
* *
* @param state Set XInclude processing to <code>true</code> or * @param state Set XInclude processing to {@code true} or
* <code>false</code> * {@code false}
* *
* @throws UnsupportedOperationException When implementation does not * @throws UnsupportedOperationException When implementation does not
* override this method. * override this method.
@ -594,7 +589,7 @@ public abstract class DocumentBuilderFactory {
} }
/** /**
* <p>Get state of XInclude processing.</p> * Get state of XInclude processing.
* *
* @return current state of XInclude processing * @return current state of XInclude processing
* *

87
jaxp/src/java.xml/share/classes/javax/xml/parsers/SAXParserFactory.java
View file

@ -42,17 +42,17 @@ import org.xml.sax.SAXNotSupportedException;
public abstract class SAXParserFactory { public abstract class SAXParserFactory {
/** /**
* <p>Should Parsers be validating?</p> * Should Parsers be validating?
*/ */
private boolean validating = false; private boolean validating = false;
/** /**
* <p>Should Parsers be namespace aware?</p> * Should Parsers be namespace aware?
*/ */
private boolean namespaceAware = false; private boolean namespaceAware = false;
/** /**
* <p>Protected constructor to force use of {@link #newInstance()}.</p> * Protected constructor to force use of {@link #newInstance()}.
*/ */
protected SAXParserFactory () { protected SAXParserFactory () {
@ -64,7 +64,6 @@ public abstract class SAXParserFactory {
* This method uses the following ordered lookup procedure to determine * This method uses the following ordered lookup procedure to determine
* the {@code SAXParserFactory} implementation class to * the {@code SAXParserFactory} implementation class to
* load: * load:
* <p>
* <ul> * <ul>
* <li> * <li>
* Use the {@code javax.xml.parsers.SAXParserFactory} system * Use the {@code javax.xml.parsers.SAXParserFactory} system
@ -138,19 +137,19 @@ public abstract class SAXParserFactory {
} }
/** /**
* <p>Obtain a new instance of a {@code SAXParserFactory} from class name. * Obtain a new instance of a {@code SAXParserFactory} from class name.
* This function is useful when there are multiple providers in the classpath. * This function is useful when there are multiple providers in the classpath.
* It gives more control to the application as it can specify which provider * It gives more control to the application as it can specify which provider
* should be loaded.</p> * should be loaded.
* *
* <p>Once an application has obtained a reference to a {@code SAXParserFactory} * <p>Once an application has obtained a reference to a {@code SAXParserFactory}
* it can use the factory to configure and obtain parser instances.</p> * it can use the factory to configure and obtain parser instances.
* *
* *
* <h2>Tip for Trouble-shooting</h2> * <h2>Tip for Trouble-shooting</h2>
* <p>Setting the {@code jaxp.debug} system property will cause * <p>Setting the {@code jaxp.debug} system property will cause
* this method to print a lot of debug messages * this method to print a lot of debug messages
* to {@code System.err} about what it is doing and where it is looking at.</p> * to {@code System.err} about what it is doing and where it is looking at.
* *
* <p> * <p>
* If you have problems, try: * If you have problems, try:
@ -160,12 +159,12 @@ public abstract class SAXParserFactory {
* *
* @param factoryClassName fully qualified factory class name that provides implementation of {@code javax.xml.parsers.SAXParserFactory}. * @param factoryClassName fully qualified factory class name that provides implementation of {@code javax.xml.parsers.SAXParserFactory}.
* *
* @param classLoader <code>ClassLoader</code> used to load the factory class. If <code>null</code> * @param classLoader {@code ClassLoader} used to load the factory class. If {@code null}
* current <code>Thread</code>'s context classLoader is used to load the factory class. * current {@code Thread}'s context classLoader is used to load the factory class.
* *
* @return New instance of a {@code SAXParserFactory} * @return New instance of a {@code SAXParserFactory}
* *
* @throws FactoryConfigurationError if <code>factoryClassName</code> is <code>null</code>, or * @throws FactoryConfigurationError if {@code factoryClassName} is {@code null}, or
* the factory class cannot be loaded, instantiated. * the factory class cannot be loaded, instantiated.
* *
* @see #newInstance() * @see #newInstance()
@ -179,8 +178,8 @@ public abstract class SAXParserFactory {
} }
/** /**
* <p>Creates a new instance of a SAXParser using the currently * Creates a new instance of a SAXParser using the currently
* configured factory parameters.</p> * configured factory parameters.
* *
* @return A new instance of a SAXParser. * @return A new instance of a SAXParser.
* *
@ -196,7 +195,7 @@ public abstract class SAXParserFactory {
/** /**
* Specifies that the parser produced by this code will * Specifies that the parser produced by this code will
* provide support for XML namespaces. By default the value of this is set * provide support for XML namespaces. By default the value of this is set
* to <code>false</code>. * to {@code false}.
* *
* @param awareness true if the parser produced by this code will * @param awareness true if the parser produced by this code will
* provide support for XML namespaces; false otherwise. * provide support for XML namespaces; false otherwise.
@ -209,7 +208,7 @@ public abstract class SAXParserFactory {
/** /**
* Specifies that the parser produced by this code will * Specifies that the parser produced by this code will
* validate documents as they are parsed. By default the value of this is * validate documents as they are parsed. By default the value of this is
* set to <code>false</code>. * set to {@code false}.
* *
* <p> * <p>
* Note that "the validation" here means * Note that "the validation" here means
@ -217,15 +216,13 @@ public abstract class SAXParserFactory {
* parser</a> as defined in the XML recommendation. * parser</a> as defined in the XML recommendation.
* In other words, it essentially just controls the DTD validation. * In other words, it essentially just controls the DTD validation.
* (except the legacy two properties defined in JAXP 1.2.) * (except the legacy two properties defined in JAXP 1.2.)
* </p>
* *
* <p> * <p>
* To use modern schema languages such as W3C XML Schema or * To use modern schema languages such as W3C XML Schema or
* RELAX NG instead of DTD, you can configure your parser to be * RELAX NG instead of DTD, you can configure your parser to be
* a non-validating parser by leaving the {@link #setValidating(boolean)} * a non-validating parser by leaving the {@link #setValidating(boolean)}
* method <code>false</code>, then use the {@link #setSchema(Schema)} * method {@code false}, then use the {@link #setSchema(Schema)}
* method to associate a schema to a parser. * method to associate a schema to a parser.
* </p>
* *
* @param validating true if the parser produced by this code will * @param validating true if the parser produced by this code will
* validate documents as they are parsed; false otherwise. * validate documents as they are parsed; false otherwise.
@ -260,24 +257,23 @@ public abstract class SAXParserFactory {
} }
/** /**
* * Sets the particular feature in the underlying implementation of
* <p>Sets the particular feature in the underlying implementation of
* org.xml.sax.XMLReader. * org.xml.sax.XMLReader.
* A list of the core features and properties can be found at * A list of the core features and properties can be found at
* <a href="http://www.saxproject.org/">http://www.saxproject.org/</a></p> * <a href="http://www.saxproject.org/">http://www.saxproject.org/</a>
* *
* <p>All implementations are required to support the {@link javax.xml.XMLConstants#FEATURE_SECURE_PROCESSING} feature. * <p>All implementations are required to support the {@link javax.xml.XMLConstants#FEATURE_SECURE_PROCESSING} feature.
* When the feature is</p> * When the feature is
* <ul> * <ul>
* <li> * <li>
* <code>true</code>: the implementation will limit XML processing to conform to implementation limits. * {@code true}: the implementation will limit XML processing to conform to implementation limits.
* Examples include entity expansion limits and XML Schema constructs that would consume large amounts of resources. * Examples include entity expansion limits and XML Schema constructs that would consume large amounts of resources.
* If XML processing is limited for security reasons, it will be reported via a call to the registered * If XML processing is limited for security reasons, it will be reported via a call to the registered
* {@link org.xml.sax.ErrorHandler#fatalError(SAXParseException exception)}. * {@link org.xml.sax.ErrorHandler#fatalError(SAXParseException exception)}.
* See {@link SAXParser} <code>parse</code> methods for handler specification. * See {@link SAXParser} {@code parse} methods for handler specification.
* </li> * </li>
* <li> * <li>
* When the feature is <code>false</code>, the implementation will processing XML according to the XML specifications without * When the feature is {@code false}, the implementation will processing XML according to the XML specifications without
* regard to possible implementation limits. * regard to possible implementation limits.
* </li> * </li>
* </ul> * </ul>
@ -292,7 +288,7 @@ public abstract class SAXParserFactory {
* @throws SAXNotSupportedException When the underlying XMLReader * @throws SAXNotSupportedException When the underlying XMLReader
* recognizes the property name but doesn't support the * recognizes the property name but doesn't support the
* property. * property.
* @throws NullPointerException If the <code>name</code> parameter is null. * @throws NullPointerException If the {@code name} parameter is null.
* *
* @see org.xml.sax.XMLReader#setFeature * @see org.xml.sax.XMLReader#setFeature
*/ */
@ -302,8 +298,8 @@ public abstract class SAXParserFactory {
/** /**
* *
* <p>Returns the particular property requested for in the underlying * Returns the particular property requested for in the underlying
* implementation of org.xml.sax.XMLReader.</p> * implementation of org.xml.sax.XMLReader.
* *
* @param name The name of the property to be retrieved. * @param name The name of the property to be retrieved.
* *
@ -347,12 +343,12 @@ public abstract class SAXParserFactory {
} }
/** /**
* <p>Set the {@link Schema} to be used by parsers created * Set the {@link Schema} to be used by parsers created
* from this factory.</p> * from this factory.
* *
* <p>When a {@link Schema} is non-null, a parser will use a validator * <p>When a {@link Schema} is non-null, a parser will use a validator
* created from it to validate documents before it passes information * created from it to validate documents before it passes information
* down to the application.</p> * down to the application.
* *
* <p>When warnings/errors/fatal errors are found by the validator, the parser must * <p>When warnings/errors/fatal errors are found by the validator, the parser must
* handle them as if those errors were found by the parser itself. * handle them as if those errors were found by the parser itself.
@ -364,29 +360,28 @@ public abstract class SAXParserFactory {
* <p>A validator may modify the SAX event stream (for example by * <p>A validator may modify the SAX event stream (for example by
* adding default values that were missing in documents), and a parser * adding default values that were missing in documents), and a parser
* is responsible to make sure that the application will receive * is responsible to make sure that the application will receive
* those modified event stream.</p> * those modified event stream.
* *
* <p>Initially, <code>null</code> is set as the {@link Schema}.</p> * <p>Initially, {@code null} is set as the {@link Schema}.
* *
* <p>This processing will take effect even if * <p>This processing will take effect even if
* the {@link #isValidating()} method returns <code>false</code>. * the {@link #isValidating()} method returns {@code false}.
* *
* <p>It is an error to use * <p>It is an error to use
* the <code>http://java.sun.com/xml/jaxp/properties/schemaSource</code> * the {@code http://java.sun.com/xml/jaxp/properties/schemaSource}
* property and/or the <code>http://java.sun.com/xml/jaxp/properties/schemaLanguage</code> * property and/or the {@code http://java.sun.com/xml/jaxp/properties/schemaLanguage}
* property in conjunction with a non-null {@link Schema} object. * property in conjunction with a non-null {@link Schema} object.
* Such configuration will cause a {@link SAXException} * Such configuration will cause a {@link SAXException}
* exception when those properties are set on a {@link SAXParser}.</p> * exception when those properties are set on a {@link SAXParser}.
* *
* <h4>Note for implementors</h4> * <h3>Note for implementors</h3>
* <p> * <p>
* A parser must be able to work with any {@link Schema} * A parser must be able to work with any {@link Schema}
* implementation. However, parsers and schemas are allowed * implementation. However, parsers and schemas are allowed
* to use implementation-specific custom mechanisms * to use implementation-specific custom mechanisms
* as long as they yield the result described in the specification. * as long as they yield the result described in the specification.
* </p>
* *
* @param schema <code>Schema</code> to use, <code>null</code> to remove a schema. * @param schema {@code Schema} to use, {@code null} to remove a schema.
* *
* @throws UnsupportedOperationException When implementation does not * @throws UnsupportedOperationException When implementation does not
* override this method * override this method
@ -404,16 +399,16 @@ public abstract class SAXParserFactory {
} }
/** /**
* <p>Set state of XInclude processing.</p> * Set state of XInclude processing.
* *
* <p>If XInclude markup is found in the document instance, should it be * <p>If XInclude markup is found in the document instance, should it be
* processed as specified in <a href="http://www.w3.org/TR/xinclude/"> * processed as specified in <a href="http://www.w3.org/TR/xinclude/">
* XML Inclusions (XInclude) Version 1.0</a>.</p> * XML Inclusions (XInclude) Version 1.0</a>.
* *
* <p>XInclude processing defaults to <code>false</code>.</p> * <p>XInclude processing defaults to {@code false}.
* *
* @param state Set XInclude processing to <code>true</code> or * @param state Set XInclude processing to {@code true} or
* <code>false</code> * {@code false}
* *
* @throws UnsupportedOperationException When implementation does not * @throws UnsupportedOperationException When implementation does not
* override this method * override this method
@ -429,7 +424,7 @@ public abstract class SAXParserFactory {
} }
/** /**
* <p>Get state of XInclude processing.</p> * Get state of XInclude processing.
* *
* @return current state of XInclude processing * @return current state of XInclude processing
* *

2
jaxp/src/java.xml/share/classes/javax/xml/stream/XMLEventFactory.java
View file

@ -70,7 +70,6 @@ public abstract class XMLEventFactory {
* This static method creates a new factory instance. * This static method creates a new factory instance.
* This method uses the following ordered lookup procedure to determine * This method uses the following ordered lookup procedure to determine
* the XMLEventFactory implementation class to load: * the XMLEventFactory implementation class to load:
* <p>
* <ul> * <ul>
* <li> * <li>
* Use the javax.xml.stream.XMLEventFactory system property. * Use the javax.xml.stream.XMLEventFactory system property.
@ -158,7 +157,6 @@ public abstract class XMLEventFactory {
* <p> * <p>
* This method uses the following ordered lookup procedure to determine * This method uses the following ordered lookup procedure to determine
* the XMLEventFactory implementation class to load: * the XMLEventFactory implementation class to load:
* <p>
* <ul> * <ul>
* <li> * <li>
* Use the value of the system property identified by {@code factoryId}. * Use the value of the system property identified by {@code factoryId}.

9
jaxp/src/java.xml/share/classes/javax/xml/stream/XMLInputFactory.java
View file

@ -160,7 +160,7 @@ public abstract class XMLInputFactory {
* This static method creates a new factory instance. * This static method creates a new factory instance.
* This method uses the following ordered lookup procedure to determine * This method uses the following ordered lookup procedure to determine
* the XMLInputFactory implementation class to load: * the XMLInputFactory implementation class to load:
* </p> *
* <ul> * <ul>
* <li> * <li>
* <p>Use the javax.xml.stream.XMLInputFactory system property. * <p>Use the javax.xml.stream.XMLInputFactory system property.
@ -201,12 +201,11 @@ public abstract class XMLInputFactory {
* <p> * <p>
* Once an application has obtained a reference to a XMLInputFactory it * Once an application has obtained a reference to a XMLInputFactory it
* can use the factory to configure and obtain stream instances. * can use the factory to configure and obtain stream instances.
* </p>
* <p> * <p>
* Note that this is a new method that replaces the deprecated newInstance() method. * Note that this is a new method that replaces the deprecated newInstance() method.
* No changes in behavior are defined by this replacement method relative to * No changes in behavior are defined by this replacement method relative to
* the deprecated method. * the deprecated method.
* </p> *
* @throws FactoryConfigurationError in case of {@linkplain * @throws FactoryConfigurationError in case of {@linkplain
* java.util.ServiceConfigurationError service configuration error} or if * java.util.ServiceConfigurationError service configuration error} or if
* the implementation is not available or cannot be instantiated. * the implementation is not available or cannot be instantiated.
@ -245,7 +244,6 @@ public abstract class XMLInputFactory {
* <p> * <p>
* This method uses the following ordered lookup procedure to determine * This method uses the following ordered lookup procedure to determine
* the XMLInputFactory implementation class to load: * the XMLInputFactory implementation class to load:
* <p>
* <ul> * <ul>
* <li> * <li>
* <p> * <p>
@ -488,7 +486,6 @@ public abstract class XMLInputFactory {
* <p> * <p>
* All implementations that implement JAXP 1.5 or newer are required to * All implementations that implement JAXP 1.5 or newer are required to
* support the {@link javax.xml.XMLConstants#ACCESS_EXTERNAL_DTD} property. * support the {@link javax.xml.XMLConstants#ACCESS_EXTERNAL_DTD} property.
* </p>
* <ul> * <ul>
* <li> * <li>
* <p> * <p>
@ -497,7 +494,7 @@ public abstract class XMLInputFactory {
* due to the restriction of this property, {@link javax.xml.stream.XMLStreamException} * due to the restriction of this property, {@link javax.xml.stream.XMLStreamException}
* will be thrown by the {@link javax.xml.stream.XMLStreamReader#next()} or * will be thrown by the {@link javax.xml.stream.XMLStreamReader#next()} or
* {@link javax.xml.stream.XMLEventReader#nextEvent()} method. * {@link javax.xml.stream.XMLEventReader#nextEvent()} method.
* </p> *
* </li> * </li>
* </ul> * </ul>
* @param name The name of the property (may not be null) * @param name The name of the property (may not be null)

22
jaxp/src/java.xml/share/classes/javax/xml/stream/XMLOutputFactory.java
View file

@ -54,17 +54,18 @@ import javax.xml.transform.Result;
* <th>Default Value</th> * <th>Default Value</th>
* <th>Required</th> * <th>Required</th>
* </tr> * </tr>
* <tr><td>javax.xml.stream.isRepairingNamespaces</td><td>defaults prefixes on the output side</td><td>Boolean</td><td>False</td><td>Yes</td></tr> * <tr><td>javax.xml.stream.isRepairingNamespaces</td><td>defaults prefixes
* on the output side</td><td>Boolean</td><td>False</td><td>Yes</td></tr>
* </tbody> * </tbody>
* </table> * </table>
* *
* <p>The following paragraphs describe the namespace and prefix repair algorithm:</p> * <p>The following paragraphs describe the namespace and prefix repair algorithm:
* *
* <p>The property can be set with the following code line: * <p>The property can be set with the following code line:
* <code>setProperty("javax.xml.stream.isRepairingNamespaces",new Boolean(true|false));</code></p> * {@code setProperty("javax.xml.stream.isRepairingNamespaces", new Boolean(true|false));}
* *
* <p>This property specifies that the writer default namespace prefix declarations. * <p>This property specifies that the writer default namespace prefix declarations.
* The default value is false. </p> * The default value is false.
* *
* <p>If a writer isRepairingNamespaces it will create a namespace declaration * <p>If a writer isRepairingNamespaces it will create a namespace declaration
* on the current StartElement for * on the current StartElement for
@ -74,11 +75,11 @@ import javax.xml.transform.Result;
* has not been declared in a parent of the current StartElement it will be declared * has not been declared in a parent of the current StartElement it will be declared
* on the current StartElement. If the defaultNamespace is bound and in scope * on the current StartElement. If the defaultNamespace is bound and in scope
* and the default namespace matches the URI of the attribute or StartElement * and the default namespace matches the URI of the attribute or StartElement
* QName no prefix will be assigned.</p> * QName no prefix will be assigned.
* *
* <p>If an element or attribute name has a prefix, but is not * <p>If an element or attribute name has a prefix, but is not
* bound to any namespace URI, then the prefix will be removed * bound to any namespace URI, then the prefix will be removed
* during serialization.</p> * during serialization.
* *
* <p>If element and/or attribute names in the same start or * <p>If element and/or attribute names in the same start or
* empty-element tag are bound to different namespace URIs and * empty-element tag are bound to different namespace URIs and
@ -86,20 +87,20 @@ import javax.xml.transform.Result;
* occurring attribute retains the original prefix and the * occurring attribute retains the original prefix and the
* following attributes have their prefixes replaced with a * following attributes have their prefixes replaced with a
* new prefix that is bound to the namespace URIs of those * new prefix that is bound to the namespace URIs of those
* attributes. </p> * attributes.
* *
* <p>If an element or attribute name uses a prefix that is * <p>If an element or attribute name uses a prefix that is
* bound to a different URI than that inherited from the * bound to a different URI than that inherited from the
* namespace context of the parent of that element and there * namespace context of the parent of that element and there
* is no namespace declaration in the context of the current * is no namespace declaration in the context of the current
* element then such a namespace declaration is added. </p> * element then such a namespace declaration is added.
* *
* <p>If an element or attribute name is bound to a prefix and * <p>If an element or attribute name is bound to a prefix and
* there is a namespace declaration that binds that prefix * there is a namespace declaration that binds that prefix
* to a different URI then that namespace declaration is * to a different URI then that namespace declaration is
* either removed if the correct mapping is inherited from * either removed if the correct mapping is inherited from
* the parent context of that element, or changed to the * the parent context of that element, or changed to the
* namespace URI of the element or attribute using that prefix.</p> * namespace URI of the element or attribute using that prefix.
* *
* @version 1.2 * @version 1.2
* @author Copyright (c) 2009, 2015 by Oracle Corporation. All Rights Reserved. * @author Copyright (c) 2009, 2015 by Oracle Corporation. All Rights Reserved.
@ -136,7 +137,6 @@ public abstract class XMLOutputFactory {
* This static method creates a new factory instance. This method uses the * This static method creates a new factory instance. This method uses the
* following ordered lookup procedure to determine the XMLOutputFactory * following ordered lookup procedure to determine the XMLOutputFactory
* implementation class to load: * implementation class to load:
* <p>
* <ul> * <ul>
* <li> * <li>
* Use the javax.xml.stream.XMLOutputFactory system property. * Use the javax.xml.stream.XMLOutputFactory system property.
@ -177,6 +177,7 @@ public abstract class XMLOutputFactory {
* <p> * <p>
* Otherwise, the system-default implementation is returned. * Otherwise, the system-default implementation is returned.
* </li> * </li>
* </ul>
* <p> * <p>
* Once an application has obtained a reference to a XMLOutputFactory it * Once an application has obtained a reference to a XMLOutputFactory it
* can use the factory to configure and obtain stream instances. * can use the factory to configure and obtain stream instances.
@ -222,7 +223,6 @@ public abstract class XMLOutputFactory {
* <p> * <p>
* This method uses the following ordered lookup procedure to determine * This method uses the following ordered lookup procedure to determine
* the XMLOutputFactory implementation class to load: * the XMLOutputFactory implementation class to load:
* <p>
* <ul> * <ul>
* <li> * <li>
* Use the value of the system property identified by {@code factoryId}. * Use the value of the system property identified by {@code factoryId}.

98
jaxp/src/java.xml/share/classes/javax/xml/stream/XMLStreamReader.java
View file

@ -57,9 +57,9 @@ import javax.xml.namespace.QName;
* javax.xml.stream.notations and javax.xml.stream.entities. * javax.xml.stream.notations and javax.xml.stream.entities.
* When the current event is a DTD the following call will return a * When the current event is a DTD the following call will return a
* list of Notations * list of Notations
* <code>List l = (List) getProperty("javax.xml.stream.notations");</code> * {@code List l = (List) getProperty("javax.xml.stream.notations");}
* The following call will return a list of entity declarations: * The following call will return a list of entity declarations:
* <code>List l = (List) getProperty("javax.xml.stream.entities");</code> * {@code List l = (List) getProperty("javax.xml.stream.entities");}
* These properties can only be accessed during a DTD event and * These properties can only be accessed during a DTD event and
* are defined to return null if the information is not available. * are defined to return null if the information is not available.
* *
@ -97,12 +97,13 @@ import javax.xml.namespace.QName;
* getElementText(), nextTag() * getElementText(), nextTag()
* </td> * </td>
* </tr> * </tr>
* <tr>
* <td> ATTRIBUTE </td> * <td> ATTRIBUTE </td>
* <td> next(), nextTag() * <td> next(), nextTag()
* getAttributeXXX(), isAttributeSpecified(), * getAttributeXXX(), isAttributeSpecified(),
* </td> * </td>
* </tr> * </tr>
* </tr> * <tr>
* <td> NAMESPACE </td> * <td> NAMESPACE </td>
* <td> next(), nextTag() * <td> next(), nextTag()
* getNamespaceXXX() * getNamespaceXXX()
@ -184,7 +185,7 @@ public interface XMLStreamReader extends XMLStreamConstants {
* If element content is empty (i.e. content is "") then no CHARACTERS event will be reported. * If element content is empty (i.e. content is "") then no CHARACTERS event will be reported.
* *
* <p>Given the following XML:<br> * <p>Given the following XML:<br>
* &lt;foo>&lt;!--description-->content text&lt;![CDATA[&lt;greeting>Hello&lt;/greeting>]]>other content&lt;/foo><br> * {@code <foo><!--description-->content text<![CDATA[<greeting>Hello>/greeting>]]>other content>/foo>}<br>
* The behavior of calling next() when being on foo will be:<br> * The behavior of calling next() when being on foo will be:<br>
* 1- the comment (COMMENT)<br> * 1- the comment (COMMENT)<br>
* 2- then the characters section (CHARACTERS)<br> * 2- then the characters section (CHARACTERS)<br>
@ -192,14 +193,14 @@ public interface XMLStreamReader extends XMLStreamConstants {
* 4- then the next characters section (another CHARACTERS)<br> * 4- then the next characters section (another CHARACTERS)<br>
* 5- then the END_ELEMENT<br> * 5- then the END_ELEMENT<br>
* *
* <p><b>NOTE:</b> empty element (such as &lt;tag/>) will be reported * <p><b>NOTE:</b> empty element (such as {@code <tag/>}) will be reported
* with two separate events: START_ELEMENT, END_ELEMENT - This preserves * with two separate events: START_ELEMENT, END_ELEMENT - This preserves
* parsing equivalency of empty element to &lt;tag>&lt;/tag>. * parsing equivalency of empty element to {@code <tag></tag>}.
* *
* This method will throw an IllegalStateException if it is called after hasNext() returns false. * This method will throw an IllegalStateException if it is called after hasNext() returns false.
* @see javax.xml.stream.events.XMLEvent * @see javax.xml.stream.events.XMLEvent
* @return the integer code corresponding to the current parse event * @return the integer code corresponding to the current parse event
* @throws NoSuchElementException if this is called when hasNext() returns false * @throws java.util.NoSuchElementException if this is called when hasNext() returns false
* @throws XMLStreamException if there is an error processing the underlying XML source * @throws XMLStreamException if there is an error processing the underlying XML source
*/ */
public int next() throws XMLStreamException; public int next() throws XMLStreamException;
@ -219,38 +220,39 @@ public interface XMLStreamReader extends XMLStreamConstants {
* Reads the content of a text-only element, an exception is thrown if this is * Reads the content of a text-only element, an exception is thrown if this is
* not a text-only element. * not a text-only element.
* Regardless of value of javax.xml.stream.isCoalescing this method always returns coalesced content. * Regardless of value of javax.xml.stream.isCoalescing this method always returns coalesced content.
* <br /> Precondition: the current event is START_ELEMENT. * <br> Precondition: the current event is START_ELEMENT.
* <br /> Postcondition: the current event is the corresponding END_ELEMENT. * <br> Postcondition: the current event is the corresponding END_ELEMENT.
* *
* <br />The method does the following (implementations are free to optimized * <br>The method does the following (implementations are free to optimized
* but must do equivalent processing): * but must do equivalent processing):
* <pre> * <pre>
* if(getEventType() != XMLStreamConstants.START_ELEMENT) { * if(getEventType() != XMLStreamConstants.START_ELEMENT) {
* throw new XMLStreamException( * throw new XMLStreamException(
* "parser must be on START_ELEMENT to read next text", getLocation()); * "parser must be on START_ELEMENT to read next text", getLocation());
* } * }
*
* int eventType = next(); * int eventType = next();
* StringBuffer content = new StringBuffer(); * StringBuffer content = new StringBuffer();
* while(eventType != XMLStreamConstants.END_ELEMENT ) { * while(eventType != XMLStreamConstants.END_ELEMENT) {
* if(eventType == XMLStreamConstants.CHARACTERS * if(eventType == XMLStreamConstants.CHARACTERS
* || eventType == XMLStreamConstants.CDATA * || eventType == XMLStreamConstants.CDATA
* || eventType == XMLStreamConstants.SPACE * || eventType == XMLStreamConstants.SPACE
* || eventType == XMLStreamConstants.ENTITY_REFERENCE) { * || eventType == XMLStreamConstants.ENTITY_REFERENCE) {
* buf.append(getText()); * buf.append(getText());
* } else if(eventType == XMLStreamConstants.PROCESSING_INSTRUCTION * } else if(eventType == XMLStreamConstants.PROCESSING_INSTRUCTION
* || eventType == XMLStreamConstants.COMMENT) { * || eventType == XMLStreamConstants.COMMENT) {
* // skipping * // skipping
* } else if(eventType == XMLStreamConstants.END_DOCUMENT) { * } else if(eventType == XMLStreamConstants.END_DOCUMENT) {
* throw new XMLStreamException( * throw new XMLStreamException(
* "unexpected end of document when reading element text content", this); * "unexpected end of document when reading element text content", this);
* } else if(eventType == XMLStreamConstants.START_ELEMENT) { * } else if(eventType == XMLStreamConstants.START_ELEMENT) {
* throw new XMLStreamException( * throw new XMLStreamException(
* "element text content may not contain START_ELEMENT", getLocation()); * "element text content may not contain START_ELEMENT", getLocation());
* } else { * } else {
* throw new XMLStreamException( * throw new XMLStreamException(
* "Unexpected event type "+eventType, getLocation()); * "Unexpected event type "+eventType, getLocation());
* } * }
* eventType = next(); * eventType = next();
* } * }
* return buf.toString(); * return buf.toString();
* </pre> * </pre>
@ -268,33 +270,33 @@ public interface XMLStreamReader extends XMLStreamConstants {
* are encountered, an exception is thrown. This method should * are encountered, an exception is thrown. This method should
* be used when processing element-only content seperated by white space. * be used when processing element-only content seperated by white space.
* *
* <br /> Precondition: none * <br> Precondition: none
* <br /> Postcondition: the current event is START_ELEMENT or END_ELEMENT * <br> Postcondition: the current event is START_ELEMENT or END_ELEMENT
* and cursor may have moved over any whitespace event. * and cursor may have moved over any whitespace event.
* *
* <br />Essentially it does the following (implementations are free to optimized * <br>Essentially it does the following (implementations are free to optimized
* but must do equivalent processing): * but must do equivalent processing):
* <pre> * <pre> {@code
* int eventType = next(); * int eventType = next();
* while((eventType == XMLStreamConstants.CHARACTERS &amp;&amp; isWhiteSpace()) // skip whitespace * while((eventType == XMLStreamConstants.CHARACTERS && isWhiteSpace()) // skip whitespace
* || (eventType == XMLStreamConstants.CDATA &amp;&amp; isWhiteSpace()) * || (eventType == XMLStreamConstants.CDATA && isWhiteSpace())
* // skip whitespace * // skip whitespace
* || eventType == XMLStreamConstants.SPACE * || eventType == XMLStreamConstants.SPACE
* || eventType == XMLStreamConstants.PROCESSING_INSTRUCTION * || eventType == XMLStreamConstants.PROCESSING_INSTRUCTION
* || eventType == XMLStreamConstants.COMMENT * || eventType == XMLStreamConstants.COMMENT
* ) { * ) {
* eventType = next(); * eventType = next();
* } * }
* if (eventType != XMLStreamConstants.START_ELEMENT &amp;&amp; eventType != XMLStreamConstants.END_ELEMENT) { * if (eventType != XMLStreamConstants.START_ELEMENT && eventType != XMLStreamConstants.END_ELEMENT) {
* throw new String XMLStreamException("expected start or end tag", getLocation()); * throw new String XMLStreamException("expected start or end tag", getLocation());
* } * }
* return eventType; * return eventType; }
* </pre> * </pre>
* *
* @return the event type of the element read (START_ELEMENT or END_ELEMENT) * @return the event type of the element read (START_ELEMENT or END_ELEMENT)
* @throws XMLStreamException if the current event is not white space, PROCESSING_INSTRUCTION, * @throws XMLStreamException if the current event is not white space, PROCESSING_INSTRUCTION,
* START_ELEMENT or END_ELEMENT * START_ELEMENT or END_ELEMENT
* @throws NoSuchElementException if this is called when hasNext() returns false * @throws java.util.NoSuchElementException if this is called when hasNext() returns false
*/ */
public int nextTag() throws XMLStreamException; public int nextTag() throws XMLStreamException;
@ -309,7 +311,7 @@ public interface XMLStreamReader extends XMLStreamConstants {
public boolean hasNext() throws XMLStreamException; public boolean hasNext() throws XMLStreamException;
/** /**
* Frees any resources associated with this Reader. This method does not close the * Frees any resources associated with this Reader. This method does not close the
* underlying input source. * underlying input source.
* @throws XMLStreamException if there are errors freeing associated resources * @throws XMLStreamException if there are errors freeing associated resources
*/ */
@ -542,7 +544,7 @@ public interface XMLStreamReader extends XMLStreamConstants {
* If the number of characters actually copied is less than the "length", then there is no more text. * If the number of characters actually copied is less than the "length", then there is no more text.
* Otherwise, subsequent calls need to be made until all text has been retrieved. For example: * Otherwise, subsequent calls need to be made until all text has been retrieved. For example:
* *
*<code> * <pre>{@code
* int length = 1024; * int length = 1024;
* char[] myBuffer = new char[ length ]; * char[] myBuffer = new char[ length ];
* *
@ -553,7 +555,7 @@ public interface XMLStreamReader extends XMLStreamConstants {
* if (nCopied < length) * if (nCopied < length)
* break; * break;
* } * }
* </code> * } </pre>
* XMLStreamException may be thrown if there are any XML errors in the underlying source. * XMLStreamException may be thrown if there are any XML errors in the underlying source.
* The "targetStart" argument must be greater than or equal to 0 and less than the length of "target", * The "targetStart" argument must be greater than or equal to 0 and less than the length of "target",
* Length must be greater than 0 and "targetStart + length" must be less than or equal to length of "target". * Length must be greater than 0 and "targetStart + length" must be less than or equal to length of "target".
@ -564,8 +566,8 @@ public interface XMLStreamReader extends XMLStreamConstants {
* @param length the number of characters to copy * @param length the number of characters to copy
* @return the number of characters actually copied * @return the number of characters actually copied
* @throws XMLStreamException if the underlying XML source is not well-formed * @throws XMLStreamException if the underlying XML source is not well-formed
* @throws IndexOutOfBoundsException if targetStart < 0 or > than the length of target * @throws IndexOutOfBoundsException if targetStart {@literal <} 0 or {@literal >} than the length of target
* @throws IndexOutOfBoundsException if length < 0 or targetStart + length > length of target * @throws IndexOutOfBoundsException if length {@literal <} 0 or targetStart + length {@literal >} length of target
* @throws UnsupportedOperationException if this method is not supported * @throws UnsupportedOperationException if this method is not supported
* @throws NullPointerException is if target is null * @throws NullPointerException is if target is null
*/ */

88
jaxp/src/java.xml/share/classes/javax/xml/stream/XMLStreamWriter.java
View file

@ -33,9 +33,9 @@ import javax.xml.namespace.NamespaceContext;
/** /**
* The XMLStreamWriter interface specifies how to write XML. The XMLStreamWriter does * The XMLStreamWriter interface specifies how to write XML. The XMLStreamWriter does
* not perform well formedness checking on its input. However * not perform well formedness checking on its input. However
* the writeCharacters method is required to escape &amp; , &lt; and &gt; * the writeCharacters method is required to escape {@literal &, < and >}
* For attribute values the writeAttribute method will escape the * For attribute values the writeAttribute method will escape the
* above characters plus &quot; to ensure that all character content * above characters plus {@literal "} to ensure that all character content
* and attribute values are well formed. * and attribute values are well formed.
* *
* Each NAMESPACE * Each NAMESPACE
@ -44,12 +44,12 @@ import javax.xml.namespace.NamespaceContext;
* <table border="1" cellpadding="2" cellspacing="0"> * <table border="1" cellpadding="2" cellspacing="0">
* <thead> * <thead>
* <tr> * <tr>
* <th colspan="5">XML Namespaces, <code>javax.xml.stream.isRepairingNamespaces</code> and write method behaviour</th> * <th colspan="5">XML Namespaces, {@code javax.xml.stream.isRepairingNamespaces} and write method behaviour</th>
* </tr> * </tr>
* <tr> * <tr>
* <th>Method</th> <!-- method --> * <th>Method</th> <!-- method -->
* <th colspan="2"><code>isRepairingNamespaces</code> == true</th> * <th colspan="2">{@code isRepairingNamespaces} == true</th>
* <th colspan="2"><code>isRepairingNamespaces</code> == false</th> * <th colspan="2">{@code isRepairingNamespaces} == false</th>
* </tr> * </tr>
* <tr> * <tr>
* <th></th> <!-- method --> * <th></th> <!-- method -->
@ -62,7 +62,7 @@ import javax.xml.namespace.NamespaceContext;
* *
* <tbody> * <tbody>
* <tr> * <tr>
* <th><code>writeAttribute(namespaceURI, localName, value)</code></th> * <th>{@code writeAttribute(namespaceURI, localName, value)}</th>
* <!-- isRepairingNamespaces == true --> * <!-- isRepairingNamespaces == true -->
* <td> * <td>
* <!-- namespaceURI bound --> * <!-- namespaceURI bound -->
@ -79,19 +79,19 @@ import javax.xml.namespace.NamespaceContext;
* </td> * </td>
* <td> * <td>
* <!-- namespaceURI unbound --> * <!-- namespaceURI unbound -->
* <code>XMLStreamException</code> * {@code XMLStreamException}
* </td> * </td>
* </tr> * </tr>
* *
* <tr> * <tr>
* <th><code>writeAttribute(prefix, namespaceURI, localName, value)</code></th> * <th>{@code writeAttribute(prefix, namespaceURI, localName, value)}</th>
* <!-- isRepairingNamespaces == true --> * <!-- isRepairingNamespaces == true -->
* <td> * <td>
* <!-- namespaceURI bound --> * <!-- namespaceURI bound -->
* bound to same prefix:<br /> * bound to same prefix:<br>
* prefix:localName="value"&nbsp;<sup>[1]</sup><br /> * prefix:localName="value"&nbsp;<sup>[1]</sup><br>
* <br /> * <br>
* bound to different prefix:<br /> * bound to different prefix:<br>
* xmlns:{generated}="namespaceURI" {generated}:localName="value" * xmlns:{generated}="namespaceURI" {generated}:localName="value"
* </td> * </td>
* <td> * <td>
@ -101,11 +101,11 @@ import javax.xml.namespace.NamespaceContext;
* <!-- isRepairingNamespaces == false --> * <!-- isRepairingNamespaces == false -->
* <td> * <td>
* <!-- namespaceURI bound --> * <!-- namespaceURI bound -->
* bound to same prefix:<br /> * bound to same prefix:<br>
* prefix:localName="value"&nbsp;<sup>[1][2]</sup><br /> * prefix:localName="value"&nbsp;<sup>[1][2]</sup><br>
* <br /> * <br>
* bound to different prefix:<br /> * bound to different prefix:<br>
* <code>XMLStreamException</code><sup>[2]</sup> * {@code XMLStreamException}<sup>[2]</sup>
* </td> * </td>
* <td> * <td>
* <!-- namespaceURI unbound --> * <!-- namespaceURI unbound -->
@ -114,58 +114,58 @@ import javax.xml.namespace.NamespaceContext;
* </tr> * </tr>
* *
* <tr> * <tr>
* <th><code>writeStartElement(namespaceURI, localName)</code><br /> * <th>{@code writeStartElement(namespaceURI, localName)}<br>
* <br /> * <br>
* <code>writeEmptyElement(namespaceURI, localName)</code></th> * {@code writeEmptyElement(namespaceURI, localName)}</th>
* <!-- isRepairingNamespaces == true --> * <!-- isRepairingNamespaces == true -->
* <td > * <td >
* <!-- namespaceURI bound --> * <!-- namespaceURI bound -->
* &lt;prefix:localName&gt;&nbsp;<sup>[1]</sup> * {@code <prefix:localName>}&nbsp;<sup>[1]</sup>
* </td> * </td>
* <td> * <td>
* <!-- namespaceURI unbound --> * <!-- namespaceURI unbound -->
* &lt;{generated}:localName xmlns:{generated}="namespaceURI"&gt; * {@code <{generated}:localName xmlns:{generated}="namespaceURI">}
* </td> * </td>
* <!-- isRepairingNamespaces == false --> * <!-- isRepairingNamespaces == false -->
* <td> * <td>
* <!-- namespaceURI bound --> * <!-- namespaceURI bound -->
* &lt;prefix:localName&gt;&nbsp;<sup>[1]</sup> * {@code prefix:localName>}&nbsp;<sup>[1]</sup>
* </td> * </td>
* <td> * <td>
* <!-- namespaceURI unbound --> * <!-- namespaceURI unbound -->
* <code>XMLStreamException</code> * {@code XMLStreamException}
* </td> * </td>
* </tr> * </tr>
* *
* <tr> * <tr>
* <th><code>writeStartElement(prefix, localName, namespaceURI)</code><br /> * <th>{@code writeStartElement(prefix, localName, namespaceURI)}<br>
* <br /> * <br>
* <code>writeEmptyElement(prefix, localName, namespaceURI)</code></th> * {@code writeEmptyElement(prefix, localName, namespaceURI)}</th>
* <!-- isRepairingNamespaces == true --> * <!-- isRepairingNamespaces == true -->
* <td> * <td>
* <!-- namespaceURI bound --> * <!-- namespaceURI bound -->
* bound to same prefix:<br /> * bound to same prefix:<br>
* &lt;prefix:localName&gt;&nbsp;<sup>[1]</sup><br /> * {@code <prefix:localName>}&nbsp;<sup>[1]</sup><br>
* <br /> * <br>
* bound to different prefix:<br /> * bound to different prefix:<br>
* &lt;{generated}:localName xmlns:{generated}="namespaceURI"&gt; * {@code <{generated}:localName xmlns:{generated}="namespaceURI">}
* </td> * </td>
* <td> * <td>
* <!-- namespaceURI unbound --> * <!-- namespaceURI unbound -->
* &lt;prefix:localName xmlns:prefix="namespaceURI"&gt;&nbsp;<sup>[4]</sup> * {@code <prefix:localName xmlns:prefix="namespaceURI">}&nbsp;<sup>[4]</sup>
* </td> * </td>
* <!-- isRepairingNamespaces == false --> * <!-- isRepairingNamespaces == false -->
* <td> * <td>
* <!-- namespaceURI bound --> * <!-- namespaceURI bound -->
* bound to same prefix:<br /> * bound to same prefix:<br>
* &lt;prefix:localName&gt;&nbsp;<sup>[1]</sup><br /> * {@code <prefix:localName>}&nbsp;<sup>[1]</sup><br>
* <br /> * <br>
* bound to different prefix:<br /> * bound to different prefix:<br>
* <code>XMLStreamException</code> * {@code XMLStreamException}
* </td> * </td>
* <td> * <td>
* <!-- namespaceURI unbound --> * <!-- namespaceURI unbound -->
* &lt;prefix:localName&gt;&nbsp; * {@code <prefix:localName>}&nbsp;
* </td> * </td>
* </tr> * </tr>
* </tbody> * </tbody>
@ -175,10 +175,14 @@ import javax.xml.namespace.NamespaceContext;
* Notes: * Notes:
* <ul> * <ul>
* <li>[1] if namespaceURI == default Namespace URI, then no prefix is written</li> * <li>[1] if namespaceURI == default Namespace URI, then no prefix is written</li>
* <li>[2] if prefix == "" || null && namespaceURI == "", then no prefix or Namespace declaration is generated or written</li> * <li>[2] if prefix == "" || null {@literal &&} namespaceURI == "", then
* no prefix or Namespace declaration is generated or written</li>
* <li>[3] if prefix == "" || null, then a prefix is randomly generated</li> * <li>[3] if prefix == "" || null, then a prefix is randomly generated</li>
* <li>[4] if prefix == "" || null, then it is treated as the default Namespace and no prefix is generated or written, an xmlns declaration is generated and written if the namespaceURI is unbound</li> * <li>[4] if prefix == "" || null, then it is treated as the default Namespace and
* <li>[5] if prefix == "" || null, then it is treated as an invalid attempt to define the default Namespace and an XMLStreamException is thrown</li> * no prefix is generated or written, an xmlns declaration is generated
* and written if the namespaceURI is unbound</li>
* <li>[5] if prefix == "" || null, then it is treated as an invalid attempt to
* define the default Namespace and an XMLStreamException is thrown</li>
* </ul> * </ul>
* </td> * </td>
* </tr> * </tr>

10
jaxp/src/java.xml/share/classes/javax/xml/transform/Result.java
View file

@ -27,7 +27,7 @@ package javax.xml.transform;
/** /**
* <p>An object that implements this interface contains the information * <p>An object that implements this interface contains the information
* needed to build a transformation result tree.</p> * needed to build a transformation result tree.
* *
* @author <a href="Jeff.Suttor@Sun.com">Jeff Suttor</a> * @author <a href="Jeff.Suttor@Sun.com">Jeff Suttor</a>
* @since 1.4 * @since 1.4
@ -38,7 +38,7 @@ public interface Result {
* The name of the processing instruction that is sent if the * The name of the processing instruction that is sent if the
* result tree disables output escaping. * result tree disables output escaping.
* *
* <p>Normally, result tree serialization escapes & and < (and * <p>Normally, result tree serialization escapes{@literal & and <} (and
* possibly other characters) when outputting text nodes. * possibly other characters) when outputting text nodes.
* This ensures that the output is well-formed XML. However, * This ensures that the output is well-formed XML. However,
* it is sometimes convenient to be able to produce output that is * it is sometimes convenient to be able to produce output that is
@ -46,10 +46,10 @@ public interface Result {
* the output may include ill-formed sections that will * the output may include ill-formed sections that will
* be transformed into well-formed XML by a subsequent non-XML aware * be transformed into well-formed XML by a subsequent non-XML aware
* process. If a processing instruction is sent with this name, * process. If a processing instruction is sent with this name,
* serialization should be output without any escaping. </p> * serialization should be output without any escaping.
* *
* <p>Result DOM trees may also have PI_DISABLE_OUTPUT_ESCAPING and * <p>Result DOM trees may also have PI_DISABLE_OUTPUT_ESCAPING and
* PI_ENABLE_OUTPUT_ESCAPING inserted into the tree.</p> * PI_ENABLE_OUTPUT_ESCAPING inserted into the tree.
* *
* @see <a href="http://www.w3.org/TR/xslt#disable-output-escaping">disable-output-escaping in XSLT Specification</a> * @see <a href="http://www.w3.org/TR/xslt#disable-output-escaping">disable-output-escaping in XSLT Specification</a>
*/ */
@ -71,7 +71,7 @@ public interface Result {
* *
* <p>If the Result is not to be written to a file, the system identifier is optional. * <p>If the Result is not to be written to a file, the system identifier is optional.
* The application may still want to provide one, however, for use in error messages * The application may still want to provide one, however, for use in error messages
* and warnings, or to resolve relative output identifiers.</p> * and warnings, or to resolve relative output identifiers.
* *
* @param systemId The system identifier as a URI string. * @param systemId The system identifier as a URI string.
*/ */

129
jaxp/src/java.xml/share/classes/javax/xml/transform/TransformerFactory.java
View file

@ -28,13 +28,13 @@ package javax.xml.transform;
/** /**
* <p>A TransformerFactory instance can be used to create * <p>A TransformerFactory instance can be used to create
* {@link javax.xml.transform.Transformer} and * {@link javax.xml.transform.Transformer} and
* {@link javax.xml.transform.Templates} objects.</p> * {@link javax.xml.transform.Templates} objects.
* *
* <p>The system property that determines which Factory implementation * <p>The system property that determines which Factory implementation
* to create is named <code>"javax.xml.transform.TransformerFactory"</code>. * to create is named {@code "javax.xml.transform.TransformerFactory"}.
* This property names a concrete subclass of the * This property names a concrete subclass of the
* {@code TransformerFactory} abstract class. If the property is not * {@code TransformerFactory} abstract class. If the property is not
* defined, a platform default is be used.</p> * defined, a platform default is be used.
* *
* @author <a href="mailto:Jeff.Suttor@Sun.com">Jeff Suttor</a> * @author <a href="mailto:Jeff.Suttor@Sun.com">Jeff Suttor</a>
* @author <a href="mailto:Neeraj.Bajaj@sun.com">Neeraj Bajaj</a> * @author <a href="mailto:Neeraj.Bajaj@sun.com">Neeraj Bajaj</a>
@ -51,14 +51,11 @@ public abstract class TransformerFactory {
/** /**
* <p>
* Obtain a new instance of a {@code TransformerFactory}. * Obtain a new instance of a {@code TransformerFactory}.
* This static method creates a new factory instance. * This static method creates a new factory instance.
* <p> * <p>
* This method uses the following ordered lookup procedure to determine * This method uses the following ordered lookup procedure to determine
* the {@code TransformerFactory} implementation class to * the {@code TransformerFactory} implementation class to load:
* load:
* <p>
* <ul> * <ul>
* <li> * <li>
* Use the {@code javax.xml.transform.TransformerFactory} system * Use the {@code javax.xml.transform.TransformerFactory} system
@ -118,34 +115,34 @@ public abstract class TransformerFactory {
} }
/** /**
* <p>Obtain a new instance of a {@code TransformerFactory} from factory class name. * Obtain a new instance of a {@code TransformerFactory} from factory class name.
* This function is useful when there are multiple providers in the classpath. * This function is useful when there are multiple providers in the classpath.
* It gives more control to the application as it can specify which provider * It gives more control to the application as it can specify which provider
* should be loaded.</p> * should be loaded.
* *
* <p>Once an application has obtained a reference to a * <p>Once an application has obtained a reference to a
* {@code TransformerFactory} it can use the factory to configure * {@code TransformerFactory} it can use the factory to configure
* and obtain transformer instances.</p> * and obtain transformer instances.
* *
* <h2>Tip for Trouble-shooting</h2> * <h2>Tip for Trouble-shooting</h2>
* <p>Setting the <code>jaxp.debug</code> system property will cause * <p>Setting the {@code jaxp.debug} system property will cause
* this method to print a lot of debug messages * this method to print a lot of debug messages
* to <code>System.err</code> about what it is doing and where it is looking at.</p> * to {@code System.err} about what it is doing and where it is looking at.
* *
* <p> If you have problems try:</p> * <p> If you have problems try:
* <pre> * <pre>
* java -Djaxp.debug=1 YourProgram .... * java -Djaxp.debug=1 YourProgram ....
* </pre> * </pre>
* *
* @param factoryClassName fully qualified factory class name that provides implementation of {@code javax.xml.transform.TransformerFactory}. * @param factoryClassName fully qualified factory class name that provides implementation of {@code javax.xml.transform.TransformerFactory}.
* *
* @param classLoader <code>ClassLoader</code> used to load the factory class. If <code>null</code> * @param classLoader {@code ClassLoader} used to load the factory class. If {@code null}
* current <code>Thread</code>'s context classLoader is used to load the factory class. * current {@code Thread}'s context classLoader is used to load the factory class.
* *
* @return new TransformerFactory instance, never null. * @return new TransformerFactory instance, never null.
* *
* @throws TransformerFactoryConfigurationError * @throws TransformerFactoryConfigurationError
* if <code>factoryClassName</code> is <code>null</code>, or * if {@code factoryClassName} is {@code null}, or
* the factory class cannot be loaded, instantiated. * the factory class cannot be loaded, instantiated.
* *
* @see #newInstance() * @see #newInstance()
@ -160,29 +157,29 @@ public abstract class TransformerFactory {
factoryClassName, classLoader, false, false); factoryClassName, classLoader, false, false);
} }
/** /**
* <p>Process the <code>Source</code> into a <code>Transformer</code> * Process the {@code Source} into a {@code Transformer}
* <code>Object</code>. The <code>Source</code> is an XSLT document that * {@code Object}. The {@code Source} is an XSLT document that
* conforms to <a href="http://www.w3.org/TR/xslt"> * conforms to <a href="http://www.w3.org/TR/xslt">
* XSL Transformations (XSLT) Version 1.0</a>. Care must * XSL Transformations (XSLT) Version 1.0</a>. Care must
* be taken not to use this <code>Transformer</code> in multiple * be taken not to use this {@code Transformer} in multiple
* <code>Thread</code>s running concurrently. * {@code Thread}s running concurrently.
* Different <code>TransformerFactories</code> can be used concurrently by * Different {@code TransformerFactories} can be used concurrently by
* different <code>Thread</code>s.</p> * different {@code Thread}s.
* *
* @param source <code>Source </code> of XSLT document used to create * @param source {@code Source } of XSLT document used to create
* <code>Transformer</code>. * {@code Transformer}.
* Examples of XML <code>Source</code>s include * Examples of XML {@code Source}s include
* {@link javax.xml.transform.dom.DOMSource DOMSource}, * {@link javax.xml.transform.dom.DOMSource DOMSource},
* {@link javax.xml.transform.sax.SAXSource SAXSource}, and * {@link javax.xml.transform.sax.SAXSource SAXSource}, and
* {@link javax.xml.transform.stream.StreamSource StreamSource}. * {@link javax.xml.transform.stream.StreamSource StreamSource}.
* *
* @return A <code>Transformer</code> object that may be used to perform * @return A {@code Transformer} object that may be used to perform
* a transformation in a single <code>Thread</code>, never * a transformation in a single {@code Thread}, never
* <code>null</code>. * {@code null}.
* *
* @throws TransformerConfigurationException Thrown if there are errors when * @throws TransformerConfigurationException Thrown if there are errors when
* parsing the <code>Source</code> or it is not possible to create a * parsing the {@code Source} or it is not possible to create a
* <code>Transformer</code> instance. * {@code Transformer} instance.
* *
* @see <a href="http://www.w3.org/TR/xslt"> * @see <a href="http://www.w3.org/TR/xslt">
* XSL Transformations (XSLT) Version 1.0</a> * XSL Transformations (XSLT) Version 1.0</a>
@ -191,15 +188,15 @@ public abstract class TransformerFactory {
throws TransformerConfigurationException; throws TransformerConfigurationException;
/** /**
* <p>Create a new <code>Transformer</code> that performs a copy * Create a new {@code Transformer} that performs a copy
* of the <code>Source</code> to the <code>Result</code>. * of the {@code Source} to the {@code Result}.
* i.e. the "<em>identity transform</em>".</p> * i.e. the "<em>identity transform</em>".
* *
* @return A Transformer object that may be used to perform a transformation * @return A Transformer object that may be used to perform a transformation
* in a single thread, never null. * in a single thread, never null.
* *
* @throws TransformerConfigurationException When it is not * @throws TransformerConfigurationException When it is not
* possible to create a <code>Transformer</code> instance. * possible to create a {@code Transformer} instance.
*/ */
public abstract Transformer newTransformer() public abstract Transformer newTransformer()
throws TransformerConfigurationException; throws TransformerConfigurationException;
@ -215,7 +212,7 @@ public abstract class TransformerFactory {
* @param source An object that holds a URL, input stream, etc. * @param source An object that holds a URL, input stream, etc.
* *
* @return A Templates object capable of being used for transformation * @return A Templates object capable of being used for transformation
* purposes, never <code>null</code>. * purposes, never {@code null}.
* *
* @throws TransformerConfigurationException When parsing to * @throws TransformerConfigurationException When parsing to
* construct the Templates object fails. * construct the Templates object fails.
@ -224,13 +221,13 @@ public abstract class TransformerFactory {
throws TransformerConfigurationException; throws TransformerConfigurationException;
/** /**
* <p>Get the stylesheet specification(s) associated with the * Get the stylesheet specification(s) associated with the
* XML <code>Source</code> document via the * XML {@code Source} document via the
* <a href="http://www.w3.org/TR/xml-stylesheet/"> * <a href="http://www.w3.org/TR/xml-stylesheet/">
* xml-stylesheet processing instruction</a> that match the given criteria. * xml-stylesheet processing instruction</a> that match the given criteria.
* Note that it is possible to return several stylesheets, in which case * Note that it is possible to return several stylesheets, in which case
* they are applied as if they were a list of imports or cascades in a * they are applied as if they were a list of imports or cascades in a
* single stylesheet.</p> * single stylesheet.
* *
* @param source The XML source document. * @param source The XML source document.
* @param media The media attribute to be matched. May be null, in which * @param media The media attribute to be matched. May be null, in which
@ -238,12 +235,12 @@ public abstract class TransformerFactory {
* @param title The value of the title attribute to match. May be null. * @param title The value of the title attribute to match. May be null.
* @param charset The value of the charset attribute to match. May be null. * @param charset The value of the charset attribute to match. May be null.
* *
* @return A <code>Source</code> <code>Object</code> suitable for passing * @return A {@code Source} {@code Object} suitable for passing
* to the {@code TransformerFactory}. * to the {@code TransformerFactory}.
* *
* @throws TransformerConfigurationException An <code>Exception</code> * @throws TransformerConfigurationException An {@code Exception}
* is thrown if an error occurings during parsing of the * is thrown if an error occurings during parsing of the
* <code>source</code>. * {@code source}.
* *
* @see <a href="http://www.w3.org/TR/xml-stylesheet/"> * @see <a href="http://www.w3.org/TR/xml-stylesheet/">
* Associating Style Sheets with XML documents Version 1.0</a> * Associating Style Sheets with XML documents Version 1.0</a>
@ -275,22 +272,21 @@ public abstract class TransformerFactory {
//======= CONFIGURATION METHODS ======= //======= CONFIGURATION METHODS =======
/** /**
* <p>Set a feature for this {@code TransformerFactory} and <code>Transformer</code>s * <p>Set a feature for this {@code TransformerFactory} and {@code Transformer}s
* or <code>Template</code>s created by this factory.</p> * or {@code Template}s created by this factory.
* *
* <p> * <p>
* Feature names are fully qualified {@link java.net.URI}s. * Feature names are fully qualified {@link java.net.URI}s.
* Implementations may define their own features. * Implementations may define their own features.
* An {@link TransformerConfigurationException} is thrown if this {@code TransformerFactory} or the * An {@link TransformerConfigurationException} is thrown if this {@code TransformerFactory} or the
* <code>Transformer</code>s or <code>Template</code>s it creates cannot support the feature. * {@code Transformer}s or {@code Template}s it creates cannot support the feature.
* It is possible for an {@code TransformerFactory} to expose a feature value but be unable to change its state. * It is possible for an {@code TransformerFactory} to expose a feature value but be unable to change its state.
* </p>
* *
* <p>All implementations are required to support the {@link javax.xml.XMLConstants#FEATURE_SECURE_PROCESSING} feature. * <p>All implementations are required to support the {@link javax.xml.XMLConstants#FEATURE_SECURE_PROCESSING} feature.
* When the feature is:</p> * When the feature is:
* <ul> * <ul>
* <li> * <li>
* <code>true</code>: the implementation will limit XML processing to conform to implementation limits * {@code true}: the implementation will limit XML processing to conform to implementation limits
* and behave in a secure fashion as defined by the implementation. * and behave in a secure fashion as defined by the implementation.
* Examples include resolving user defined style sheets and functions. * Examples include resolving user defined style sheets and functions.
* If XML processing is limited for security reasons, it will be reported via a call to the registered * If XML processing is limited for security reasons, it will be reported via a call to the registered
@ -298,17 +294,17 @@ public abstract class TransformerFactory {
* See {@link #setErrorListener(ErrorListener listener)}. * See {@link #setErrorListener(ErrorListener listener)}.
* </li> * </li>
* <li> * <li>
* <code>false</code>: the implementation will processing XML according to the XML specifications without * {@code false}: the implementation will processing XML according to the XML specifications without
* regard to possible implementation limits. * regard to possible implementation limits.
* </li> * </li>
* </ul> * </ul>
* *
* @param name Feature name. * @param name Feature name.
* @param value Is feature state <code>true</code> or <code>false</code>. * @param value Is feature state {@code true} or {@code false}.
* *
* @throws TransformerConfigurationException if this {@code TransformerFactory} * @throws TransformerConfigurationException if this {@code TransformerFactory}
* or the <code>Transformer</code>s or <code>Template</code>s it creates cannot support this feature. * or the {@code Transformer}s or {@code Template}s it creates cannot support this feature.
* @throws NullPointerException If the <code>name</code> parameter is null. * @throws NullPointerException If the {@code name} parameter is null.
*/ */
public abstract void setFeature(String name, boolean value) public abstract void setFeature(String name, boolean value)
throws TransformerConfigurationException; throws TransformerConfigurationException;
@ -319,16 +315,15 @@ public abstract class TransformerFactory {
* <p> * <p>
* Feature names are fully qualified {@link java.net.URI}s. * Feature names are fully qualified {@link java.net.URI}s.
* Implementations may define their own features. * Implementations may define their own features.
* <code>false</code> is returned if this {@code TransformerFactory} or the * {@code false} is returned if this {@code TransformerFactory} or the
* <code>Transformer</code>s or <code>Template</code>s it creates cannot support the feature. * {@code Transformer}s or {@code Template}s it creates cannot support the feature.
* It is possible for an {@code TransformerFactory} to expose a feature value but be unable to change its state. * It is possible for an {@code TransformerFactory} to expose a feature value but be unable to change its state.
* </p>
* *
* @param name Feature name. * @param name Feature name.
* *
* @return The current state of the feature, <code>true</code> or <code>false</code>. * @return The current state of the feature, {@code true} or {@code false}.
* *
* @throws NullPointerException If the <code>name</code> parameter is null. * @throws NullPointerException If the {@code name} parameter is null.
*/ */
public abstract boolean getFeature(String name); public abstract boolean getFeature(String name);
@ -336,13 +331,13 @@ public abstract class TransformerFactory {
* Allows the user to set specific attributes on the underlying * Allows the user to set specific attributes on the underlying
* implementation. An attribute in this context is defined to * implementation. An attribute in this context is defined to
* be an option that the implementation provides. * be an option that the implementation provides.
* An <code>IllegalArgumentException</code> is thrown if the underlying * An {@code IllegalArgumentException} is thrown if the underlying
* implementation doesn't recognize the attribute. * implementation doesn't recognize the attribute.
* <p> * <p>
* All implementations that implement JAXP 1.5 or newer are required to * All implementations that implement JAXP 1.5 or newer are required to
* support the {@link javax.xml.XMLConstants#ACCESS_EXTERNAL_DTD} and * support the {@link javax.xml.XMLConstants#ACCESS_EXTERNAL_DTD} and
* {@link javax.xml.XMLConstants#ACCESS_EXTERNAL_STYLESHEET} properties. * {@link javax.xml.XMLConstants#ACCESS_EXTERNAL_STYLESHEET} properties.
* </p> *
* <ul> * <ul>
* <li> * <li>
* <p> * <p>
@ -351,7 +346,7 @@ public abstract class TransformerFactory {
* If access is denied during transformation due to the restriction of this property, * If access is denied during transformation due to the restriction of this property,
* {@link javax.xml.transform.TransformerException} will be thrown by * {@link javax.xml.transform.TransformerException} will be thrown by
* {@link javax.xml.transform.Transformer#transform(Source, Result)}. * {@link javax.xml.transform.Transformer#transform(Source, Result)}.
* </p> *
* <p> * <p>
* Access to external DTDs in the stylesheet is restricted to the protocols * Access to external DTDs in the stylesheet is restricted to the protocols
* specified by the {@link javax.xml.XMLConstants#ACCESS_EXTERNAL_DTD} property. * specified by the {@link javax.xml.XMLConstants#ACCESS_EXTERNAL_DTD} property.
@ -359,7 +354,7 @@ public abstract class TransformerFactory {
* restriction of this property, * restriction of this property,
* {@link javax.xml.transform.TransformerConfigurationException} will be thrown * {@link javax.xml.transform.TransformerConfigurationException} will be thrown
* by the {@link #newTransformer(Source)} method. * by the {@link #newTransformer(Source)} method.
* </p> *
* <p> * <p>
* Access to external reference set by the stylesheet processing instruction, * Access to external reference set by the stylesheet processing instruction,
* Import and Include element is restricted to the protocols specified by the * Import and Include element is restricted to the protocols specified by the
@ -368,14 +363,14 @@ public abstract class TransformerFactory {
* restriction of this property, * restriction of this property,
* {@link javax.xml.transform.TransformerConfigurationException} will be thrown * {@link javax.xml.transform.TransformerConfigurationException} will be thrown
* by the {@link #newTransformer(Source)} method. * by the {@link #newTransformer(Source)} method.
* </p> *
* <p> * <p>
* Access to external document through XSLT document function is restricted * Access to external document through XSLT document function is restricted
* to the protocols specified by the property. If access is denied during * to the protocols specified by the property. If access is denied during
* the transformation due to the restriction of this property, * the transformation due to the restriction of this property,
* {@link javax.xml.transform.TransformerException} will be thrown by the * {@link javax.xml.transform.TransformerException} will be thrown by the
* {@link javax.xml.transform.Transformer#transform(Source, Result)} method. * {@link javax.xml.transform.Transformer#transform(Source, Result)} method.
* </p> *
* </li> * </li>
* </ul> * </ul>
* *
@ -390,7 +385,7 @@ public abstract class TransformerFactory {
/** /**
* Allows the user to retrieve specific attributes on the underlying * Allows the user to retrieve specific attributes on the underlying
* implementation. * implementation.
* An <code>IllegalArgumentException</code> is thrown if the underlying * An {@code IllegalArgumentException} is thrown if the underlying
* implementation doesn't recognize the attribute. * implementation doesn't recognize the attribute.
* *
* @param name The name of the attribute. * @param name The name of the attribute.
@ -406,13 +401,13 @@ public abstract class TransformerFactory {
* Set the error event listener for the TransformerFactory, which * Set the error event listener for the TransformerFactory, which
* is used for the processing of transformation instructions, * is used for the processing of transformation instructions,
* and not for the transformation itself. * and not for the transformation itself.
* An <code>IllegalArgumentException</code> is thrown if the * An {@code IllegalArgumentException} is thrown if the
* <code>ErrorListener</code> listener is <code>null</code>. * {@code ErrorListener} listener is {@code null}.
* *
* @param listener The new error listener. * @param listener The new error listener.
* *
* @throws IllegalArgumentException When <code>listener</code> is * @throws IllegalArgumentException When {@code listener} is
* <code>null</code> * {@code null}
*/ */
public abstract void setErrorListener(ErrorListener listener); public abstract void setErrorListener(ErrorListener listener);

170
jaxp/src/java.xml/share/classes/javax/xml/transform/dom/DOMResult.java
View file

@ -29,29 +29,32 @@ import javax.xml.transform.Result;
import org.w3c.dom.Node; import org.w3c.dom.Node;
/** /**
* <p>Acts as a holder for a transformation result tree in the form of a Document Object Model (DOM) tree.</p> * Acts as a holder for a transformation result tree
* in the form of a Document Object Model (DOM) tree.
* *
* <p>If no output DOM source is set, the transformation will create a Document node as the holder for the result of the transformation, * <p>If no output DOM source is set, the transformation will create
* which may be retrieved with {@link #getNode()}.</p> * a Document node as the holder for the result of the transformation,
* which may be retrieved with {@link #getNode()}.
* *
* @author <a href="Jeff.Suttor@Sun.com">Jeff Suttor</a> * @author <a href="Jeff.Suttor@Sun.com">Jeff Suttor</a>
* @since 1.4 * @since 1.4
*/ */
public class DOMResult implements Result { public class DOMResult implements Result {
/** <p>If {@link javax.xml.transform.TransformerFactory#getFeature} /**
* returns <code>true</code> when passed this value as an argument, * If {@link javax.xml.transform.TransformerFactory#getFeature}
* the <code>Transformer</code> supports <code>Result</code> output of this type.</p> * returns {@code true} when passed this value as an argument,
* the {@code Transformer} supports {@code Result} output of this type.
*/ */
public static final String FEATURE = "http://javax.xml.transform.dom.DOMResult/feature"; public static final String FEATURE = "http://javax.xml.transform.dom.DOMResult/feature";
/** /**
* <p>Zero-argument default constructor.</p> * Zero-argument default constructor.
* *
* <p><code>node</code>, * <p>{@code node},
* <code>siblingNode</code> and * {@code siblingNode} and
* <code>systemId</code> * {@code systemId}
* will be set to <code>null</code>.</p> * will be set to {@code null}.
*/ */
public DOMResult() { public DOMResult() {
setNode(null); setNode(null);
@ -60,17 +63,17 @@ public class DOMResult implements Result {
} }
/** /**
* <p>Use a DOM node to create a new output target.</p> * Use a DOM node to create a new output target.
* *
* <p>In practice, the node should be * <p>In practice, the node should be
* a {@link org.w3c.dom.Document} node, * a {@link org.w3c.dom.Document} node,
* a {@link org.w3c.dom.DocumentFragment} node, or * a {@link org.w3c.dom.DocumentFragment} node, or
* a {@link org.w3c.dom.Element} node. * a {@link org.w3c.dom.Element} node.
* In other words, a node that accepts children.</p> * In other words, a node that accepts children.
* *
* <p><code>siblingNode</code> and * <p>{@code siblingNode} and
* <code>systemId</code> * {@code systemId}
* will be set to <code>null</code>.</p> * will be set to {@code null}.
* *
* @param node The DOM node that will contain the result tree. * @param node The DOM node that will contain the result tree.
*/ */
@ -81,15 +84,15 @@ public class DOMResult implements Result {
} }
/** /**
* <p>Use a DOM node to create a new output target with the specified System ID.<p> * Use a DOM node to create a new output target with the specified System ID.
* *
* <p>In practice, the node should be * <p>In practice, the node should be
* a {@link org.w3c.dom.Document} node, * a {@link org.w3c.dom.Document} node,
* a {@link org.w3c.dom.DocumentFragment} node, or * a {@link org.w3c.dom.DocumentFragment} node, or
* a {@link org.w3c.dom.Element} node. * a {@link org.w3c.dom.Element} node.
* In other words, a node that accepts children.</p> * In other words, a node that accepts children.
* *
* <p><code>siblingNode</code> will be set to <code>null</code>.</p> * <p>{@code siblingNode} will be set to {@code null}.
* *
* @param node The DOM node that will contain the result tree. * @param node The DOM node that will contain the result tree.
* @param systemId The system identifier which may be used in association with this node. * @param systemId The system identifier which may be used in association with this node.
@ -101,32 +104,33 @@ public class DOMResult implements Result {
} }
/** /**
* <p>Use a DOM node to create a new output target specifying the child node where the result nodes should be inserted before.</p> * Use a DOM node to create a new output target specifying
* the child node where the result nodes should be inserted before.
* *
* <p>In practice, <code>node</code> and <code>nextSibling</code> should be * <p>In practice, {@code node} and {@code nextSibling} should be
* a {@link org.w3c.dom.Document} node, * a {@link org.w3c.dom.Document} node,
* a {@link org.w3c.dom.DocumentFragment} node, or * a {@link org.w3c.dom.DocumentFragment} node, or
* a {@link org.w3c.dom.Element} node. * a {@link org.w3c.dom.Element} node.
* In other words, a node that accepts children.</p> * In other words, a node that accepts children.
* *
* <p>Use <code>nextSibling</code> to specify the child node * <p>Use {@code nextSibling} to specify the child node
* where the result nodes should be inserted before. * where the result nodes should be inserted before.
* If <code>nextSibling</code> is not a sibling of <code>node</code>, * If {@code nextSibling} is not a sibling of {@code node},
* then an <code>IllegalArgumentException</code> is thrown. * then an {@code IllegalArgumentException} is thrown.
* If <code>node</code> is <code>null</code> and <code>nextSibling</code> is not <code>null</code>, * If {@code node} is {@code null} and {@code nextSibling} is not {@code null},
* then an <code>IllegalArgumentException</code> is thrown. * then an {@code IllegalArgumentException} is thrown.
* If <code>nextSibling</code> is <code>null</code>, * If {@code nextSibling} is {@code null},
* then the behavior is the same as calling {@link #DOMResult(Node node)}, * then the behavior is the same as calling {@link #DOMResult(Node node)},
* i.e. append the result nodes as the last child of the specified <code>node</code>.</p> * i.e. append the result nodes as the last child of the specified {@code node}.
* *
* <p><code>systemId</code> will be set to <code>null</code>.</p> * <p>{@code systemId} will be set to {@code null}.
* *
* @param node The DOM node that will contain the result tree. * @param node The DOM node that will contain the result tree.
* @param nextSibling The child node where the result nodes should be inserted before. * @param nextSibling The child node where the result nodes should be inserted before.
* *
* @throws IllegalArgumentException If <code>nextSibling</code> is not a sibling of <code>node</code> or * @throws IllegalArgumentException If {@code nextSibling} is not a sibling of {@code node} or
* <code>node</code> is <code>null</code> and <code>nextSibling</code> * {@code node} is {@code null} and {@code nextSibling}
* is not <code>null</code>. * is not {@code null}.
* *
* @since 1.5 * @since 1.5
*/ */
@ -151,33 +155,35 @@ public class DOMResult implements Result {
} }
/** /**
* <p>Use a DOM node to create a new output target specifying the child node where the result nodes should be inserted before and * Use a DOM node to create a new output target specifying the child
* the specified System ID.</p> * node where the result nodes should be inserted before and
* the specified System ID.
* *
* <p>In practice, <code>node</code> and <code>nextSibling</code> should be * <p>In practice, {@code node} and {@code nextSibling} should be
* a {@link org.w3c.dom.Document} node, * a {@link org.w3c.dom.Document} node,
* a {@link org.w3c.dom.DocumentFragment} node, or a * a {@link org.w3c.dom.DocumentFragment} node, or a
* {@link org.w3c.dom.Element} node. * {@link org.w3c.dom.Element} node.
* In other words, a node that accepts children.</p> * In other words, a node that accepts children.
* *
* <p>Use <code>nextSibling</code> to specify the child node * <p>Use {@code nextSibling} to specify the child node
* where the result nodes should be inserted before. * where the result nodes should be inserted before.
* If <code>nextSibling</code> is not a sibling of <code>node</code>, * If {@code nextSibling} is not a sibling of {@code node},
* then an <code>IllegalArgumentException</code> is thrown. * then an {@code IllegalArgumentException} is thrown.
* If <code>node</code> is <code>null</code> and <code>nextSibling</code> is not <code>null</code>, * If {@code node} is {@code null} and {@code nextSibling} is not {@code null},
* then an <code>IllegalArgumentException</code> is thrown. * then an {@code IllegalArgumentException} is thrown.
* If <code>nextSibling</code> is <code>null</code>, * If {@code nextSibling} is {@code null},
* then the behavior is the same as calling {@link #DOMResult(Node node, String systemId)}, * then the behavior is the same as calling {@link #DOMResult(Node node, String systemId)},
* i.e. append the result nodes as the last child of the specified node and use the specified System ID.</p> * i.e. append the result nodes as the last child of the specified
* node and use the specified System ID.
* *
* @param node The DOM node that will contain the result tree. * @param node The DOM node that will contain the result tree.
* @param nextSibling The child node where the result nodes should be inserted before. * @param nextSibling The child node where the result nodes should be inserted before.
* @param systemId The system identifier which may be used in association with this node. * @param systemId The system identifier which may be used in association with this node.
* *
* @throws IllegalArgumentException If <code>nextSibling</code> is not a * @throws IllegalArgumentException If {@code nextSibling} is not a
* sibling of <code>node</code> or * sibling of {@code node} or
* <code>node</code> is <code>null</code> and <code>nextSibling</code> * {@code node} is {@code null} and {@code nextSibling}
* is not <code>null</code>. * is not {@code null}.
* *
* @since 1.5 * @since 1.5
*/ */
@ -202,27 +208,27 @@ public class DOMResult implements Result {
} }
/** /**
* <p>Set the node that will contain the result DOM tree.<p> * Set the node that will contain the result DOM tree.
* *
* <p>In practice, the node should be * <p>In practice, the node should be
* a {@link org.w3c.dom.Document} node, * a {@link org.w3c.dom.Document} node,
* a {@link org.w3c.dom.DocumentFragment} node, or * a {@link org.w3c.dom.DocumentFragment} node, or
* a {@link org.w3c.dom.Element} node. * a {@link org.w3c.dom.Element} node.
* In other words, a node that accepts children.</p> * In other words, a node that accepts children.
* *
* <p>An <code>IllegalStateException</code> is thrown if * <p>An {@code IllegalStateException} is thrown if
* <code>nextSibling</code> is not <code>null</code> and * {@code nextSibling} is not {@code null} and
* <code>node</code> is not a parent of <code>nextSibling</code>. * {@code node} is not a parent of {@code nextSibling}.
* An <code>IllegalStateException</code> is thrown if <code>node</code> is <code>null</code> and * An {@code IllegalStateException} is thrown if {@code node} is {@code null} and
* <code>nextSibling</code> is not <code>null</code>.</p> * {@code nextSibling} is not {@code null}.
* *
* @param node The node to which the transformation will be appended. * @param node The node to which the transformation will be appended.
* *
* @throws IllegalStateException If <code>nextSibling</code> is not * @throws IllegalStateException If {@code nextSibling} is not
* <code>null</code> and * {@code null} and
* <code>nextSibling</code> is not a child of <code>node</code> or * {@code nextSibling} is not a child of {@code node} or
* <code>node</code> is <code>null</code> and * {@code node} is {@code null} and
* <code>nextSibling</code> is not <code>null</code>. * {@code nextSibling} is not {@code null}.
*/ */
public void setNode(Node node) { public void setNode(Node node) {
// does the corrent parent/child relationship exist? // does the corrent parent/child relationship exist?
@ -242,7 +248,7 @@ public class DOMResult implements Result {
} }
/** /**
* <p>Get the node that will contain the result DOM tree.</p> * Get the node that will contain the result DOM tree.
* *
* <p>If no node was set via * <p>If no node was set via
* {@link #DOMResult(Node node)}, * {@link #DOMResult(Node node)},
@ -251,7 +257,7 @@ public class DOMResult implements Result {
* {@link #DOMResult(Node node, Node nextSibling, String systemId)} or * {@link #DOMResult(Node node, Node nextSibling, String systemId)} or
* {@link #setNode(Node node)}, * {@link #setNode(Node node)},
* then the node will be set by the transformation, and may be obtained from this method once the transformation is complete. * then the node will be set by the transformation, and may be obtained from this method once the transformation is complete.
* Calling this method before the transformation will return <code>null</code>.</p> * Calling this method before the transformation will return {@code null}.
* *
* @return The node to which the transformation will be appended. * @return The node to which the transformation will be appended.
*/ */
@ -260,24 +266,24 @@ public class DOMResult implements Result {
} }
/** /**
* <p>Set the child node before which the result nodes will be inserted.</p> * Set the child node before which the result nodes will be inserted.
* *
* <p>Use <code>nextSibling</code> to specify the child node * <p>Use {@code nextSibling} to specify the child node
* before which the result nodes should be inserted. * before which the result nodes should be inserted.
* If <code>nextSibling</code> is not a descendant of <code>node</code>, * If {@code nextSibling} is not a descendant of {@code node},
* then an <code>IllegalArgumentException</code> is thrown. * then an {@code IllegalArgumentException} is thrown.
* If <code>node</code> is <code>null</code> and <code>nextSibling</code> is not <code>null</code>, * If {@code node} is {@code null} and {@code nextSibling} is not {@code null},
* then an <code>IllegalStateException</code> is thrown. * then an {@code IllegalStateException} is thrown.
* If <code>nextSibling</code> is <code>null</code>, * If {@code nextSibling} is {@code null},
* then the behavior is the same as calling {@link #DOMResult(Node node)}, * then the behavior is the same as calling {@link #DOMResult(Node node)},
* i.e. append the result nodes as the last child of the specified <code>node</code>.</p> * i.e. append the result nodes as the last child of the specified {@code node}.
* *
* @param nextSibling The child node before which the result nodes will be inserted. * @param nextSibling The child node before which the result nodes will be inserted.
* *
* @throws IllegalArgumentException If <code>nextSibling</code> is not a * @throws IllegalArgumentException If {@code nextSibling} is not a
* descendant of <code>node</code>. * descendant of {@code node}.
* @throws IllegalStateException If <code>node</code> is <code>null</code> * @throws IllegalStateException If {@code node} is {@code null}
* and <code>nextSibling</code> is not <code>null</code>. * and {@code nextSibling} is not {@code null}.
* *
* @since 1.5 * @since 1.5
*/ */
@ -300,13 +306,13 @@ public class DOMResult implements Result {
} }
/** /**
* <p>Get the child node before which the result nodes will be inserted.</p> * Get the child node before which the result nodes will be inserted.
* *
* <p>If no node was set via * <p>If no node was set via
* {@link #DOMResult(Node node, Node nextSibling)}, * {@link #DOMResult(Node node, Node nextSibling)},
* {@link #DOMResult(Node node, Node nextSibling, String systemId)} or * {@link #DOMResult(Node node, Node nextSibling, String systemId)} or
* {@link #setNextSibling(Node nextSibling)}, * {@link #setNextSibling(Node nextSibling)},
* then <code>null</code> will be returned.</p> * then {@code null} will be returned.
* *
* @return The child node before which the result nodes will be inserted. * @return The child node before which the result nodes will be inserted.
* *
@ -317,7 +323,7 @@ public class DOMResult implements Result {
} }
/** /**
* <p>Set the systemId that may be used in association with the node.</p> * Set the systemId that may be used in association with the node.
* *
* @param systemId The system identifier as a URI string. * @param systemId The system identifier as a URI string.
*/ */
@ -326,13 +332,13 @@ public class DOMResult implements Result {
} }
/** /**
* <p>Get the System Identifier.</p> * Get the System Identifier.
* *
* <p>If no System ID was set via * <p>If no System ID was set via
* {@link #DOMResult(Node node, String systemId)}, * {@link #DOMResult(Node node, String systemId)},
* {@link #DOMResult(Node node, Node nextSibling, String systemId)} or * {@link #DOMResult(Node node, Node nextSibling, String systemId)} or
* {@link #setSystemId(String systemId)}, * {@link #setSystemId(String systemId)},
* then <code>null</code> will be returned.</p> * then {@code null} will be returned.
* *
* @return The system identifier. * @return The system identifier.
*/ */
@ -345,19 +351,19 @@ public class DOMResult implements Result {
////////////////////////////////////////////////////////////////////// //////////////////////////////////////////////////////////////////////
/** /**
* <p>The node to which the transformation will be appended.</p> * The node to which the transformation will be appended.
*/ */
private Node node = null; private Node node = null;
/** /**
* <p>The child node before which the result nodes will be inserted.</p> * The child node before which the result nodes will be inserted.
* *
* @since 1.5 * @since 1.5
*/ */
private Node nextSibling = null; private Node nextSibling = null;
/** /**
* <p>The System ID that may be used in association with the node.</p> * The System ID that may be used in association with the node.
*/ */
private String systemId = null; private String systemId = null;
} }

5
jaxp/src/java.xml/share/classes/javax/xml/transform/stax/package.html
View file

@ -65,9 +65,6 @@ questions.
<li>@see XMLEventReader</li> <li>@see XMLEventReader</li>
</ul> </ul>
<p> @since 1.6
@since 1.6
</p>
</body> </body>
</html> </html>

169
jaxp/src/java.xml/share/classes/javax/xml/validation/SchemaFactory.java
View file

@ -37,7 +37,7 @@ import org.xml.sax.SAXNotSupportedException;
import org.xml.sax.SAXParseException; import org.xml.sax.SAXParseException;
/** /**
* Factory that creates {@link Schema} objects&#x2E; Entry-point to * Factory that creates {@link Schema} objects. Entry-point to
* the validation API. * the validation API.
* *
* <p> * <p>
@ -49,12 +49,12 @@ import org.xml.sax.SAXParseException;
* it is the application's responsibility to ensure that at most * it is the application's responsibility to ensure that at most
* one thread is using a {@link SchemaFactory} object at any * one thread is using a {@link SchemaFactory} object at any
* given moment. Implementations are encouraged to mark methods * given moment. Implementations are encouraged to mark methods
* as <code>synchronized</code> to protect themselves from broken clients. * as {@code synchronized} to protect themselves from broken clients.
* *
* <p> * <p>
* {@link SchemaFactory} is not re-entrant. While one of the * {@link SchemaFactory} is not re-entrant. While one of the
* <code>newSchema</code> methods is being invoked, applications * {@code newSchema} methods is being invoked, applications
* may not attempt to recursively invoke the <code>newSchema</code> method, * may not attempt to recursively invoke the {@code newSchema} method,
* even from the same thread. * even from the same thread.
* *
* <h2><a name="schemaLanguage"></a>Schema Language</h2> * <h2><a name="schemaLanguage"></a>Schema Language</h2>
@ -92,11 +92,11 @@ import org.xml.sax.SAXParseException;
* </thead> * </thead>
* <tbody> * <tbody>
* <tr> * <tr>
* <td>{@link javax.xml.XMLConstants#W3C_XML_SCHEMA_NS_URI} ("<code>http://www.w3.org/2001/XMLSchema</code>")</td> * <td>{@link javax.xml.XMLConstants#W3C_XML_SCHEMA_NS_URI} ("{@code http://www.w3.org/2001/XMLSchema}")</td>
* <td><a href="http://www.w3.org/TR/xmlschema-1">W3C XML Schema 1.0</a></td> * <td><a href="http://www.w3.org/TR/xmlschema-1">W3C XML Schema 1.0</a></td>
* </tr> * </tr>
* <tr> * <tr>
* <td>{@link javax.xml.XMLConstants#RELAXNG_NS_URI} ("<code>http://relaxng.org/ns/structure/1.0</code>")</td> * <td>{@link javax.xml.XMLConstants#RELAXNG_NS_URI} ("{@code http://relaxng.org/ns/structure/1.0}")</td>
* <td><a href="http://www.relaxng.org/">RELAX NG 1.0</a></td> * <td><a href="http://www.relaxng.org/">RELAX NG 1.0</a></td>
* </tr> * </tr>
* </tbody> * </tbody>
@ -112,24 +112,24 @@ public abstract class SchemaFactory {
private static SecuritySupport ss = new SecuritySupport(); private static SecuritySupport ss = new SecuritySupport();
/** /**
* <p>Constructor for derived classes.</p> * Constructor for derived classes.
* *
* <p>The constructor does nothing.</p> * <p>The constructor does nothing.
* *
* <p>Derived classes must create {@link SchemaFactory} objects that have * <p>Derived classes must create {@link SchemaFactory} objects that have
* <code>null</code> {@link ErrorHandler} and * {@code null} {@link ErrorHandler} and
* <code>null</code> {@link LSResourceResolver}.</p> * {@code null} {@link LSResourceResolver}.
*/ */
protected SchemaFactory() { protected SchemaFactory() {
} }
/** /**
* <p>Lookup an implementation of the <code>SchemaFactory</code> that supports the specified * Lookup an implementation of the {@code SchemaFactory} that supports the specified
* schema language and return it.</p> * schema language and return it.
* *
* <p>To find a <code>SchemaFactory</code> object for a given schema language, * <p>To find a {@code SchemaFactory} object for a given schema language,
* this method looks the following places in the following order * this method looks the following places in the following order
* where "the class loader" refers to the context class loader:</p> * where "the class loader" refers to the context class loader:
* <ol> * <ol>
* <li> * <li>
* <p> * <p>
@ -178,9 +178,9 @@ public abstract class SchemaFactory {
* </li> * </li>
* <li> * <li>
* <p> * <p>
* Platform default <code>SchemaFactory</code> is located * Platform default {@code SchemaFactory} is located
* in a implementation specific way. There must be a platform default * in a implementation specific way. There must be a platform default
* <code>SchemaFactory</code> for W3C XML Schema. * {@code SchemaFactory} for W3C XML Schema.
* </li> * </li>
* </ol> * </ol>
* *
@ -201,12 +201,12 @@ public abstract class SchemaFactory {
* <a href="#schemaLanguage">the list of available * <a href="#schemaLanguage">the list of available
* schema languages</a> for the possible values. * schema languages</a> for the possible values.
* *
* @return New instance of a <code>SchemaFactory</code> * @return New instance of a {@code SchemaFactory}
* *
* @throws IllegalArgumentException * @throws IllegalArgumentException
* If no implementation of the schema language is available. * If no implementation of the schema language is available.
* @throws NullPointerException * @throws NullPointerException
* If the <code>schemaLanguage</code> parameter is null. * If the {@code schemaLanguage} parameter is null.
* @throws SchemaFactoryConfigurationError * @throws SchemaFactoryConfigurationError
* If a configuration error is encountered. * If a configuration error is encountered.
* *
@ -233,42 +233,42 @@ public abstract class SchemaFactory {
} }
/** /**
* <p>Obtain a new instance of a <code>SchemaFactory</code> from class name. <code>SchemaFactory</code> * Obtain a new instance of a {@code SchemaFactory} from class name. {@code SchemaFactory}
* is returned if specified factory class name supports the specified schema language. * is returned if specified factory class name supports the specified schema language.
* This function is useful when there are multiple providers in the classpath. * This function is useful when there are multiple providers in the classpath.
* It gives more control to the application as it can specify which provider * It gives more control to the application as it can specify which provider
* should be loaded.</p> * should be loaded.
* *
* <h2>Tip for Trouble-shooting</h2> * <h2>Tip for Trouble-shooting</h2>
* <p>Setting the <code>jaxp.debug</code> system property will cause * <p>Setting the {@code jaxp.debug} system property will cause
* this method to print a lot of debug messages * this method to print a lot of debug messages
* to <code>System.err</code> about what it is doing and where it is looking at.</p> * to {@code System.err} about what it is doing and where it is looking at.
* *
* <p> If you have problems try:</p> * <p> If you have problems try:
* <pre> * <pre>
* java -Djaxp.debug=1 YourProgram .... * java -Djaxp.debug=1 YourProgram ....
* </pre> * </pre>
* *
* @param schemaLanguage Specifies the schema language which the returned * @param schemaLanguage Specifies the schema language which the returned
* <code>SchemaFactory</code> will understand. See * {@code SchemaFactory} will understand. See
* <a href="#schemaLanguage">the list of available * <a href="#schemaLanguage">the list of available
* schema languages</a> for the possible values. * schema languages</a> for the possible values.
* *
* @param factoryClassName fully qualified factory class name that provides implementation of <code>javax.xml.validation.SchemaFactory</code>. * @param factoryClassName fully qualified factory class name that provides implementation of {@code javax.xml.validation.SchemaFactory}.
* *
* @param classLoader <code>ClassLoader</code> used to load the factory class. If <code>null</code> * @param classLoader {@code ClassLoader} used to load the factory class. If {@code null}
* current <code>Thread</code>'s context classLoader is used to load the factory class. * current {@code Thread}'s context classLoader is used to load the factory class.
* *
* @return New instance of a <code>SchemaFactory</code> * @return New instance of a {@code SchemaFactory}
* *
* @throws IllegalArgumentException * @throws IllegalArgumentException
* if <code>factoryClassName</code> is <code>null</code>, or * if {@code factoryClassName} is {@code null}, or
* the factory class cannot be loaded, instantiated or doesn't * the factory class cannot be loaded, instantiated or doesn't
* support the schema language specified in <code>schemLanguage</code> * support the schema language specified in {@code schemLanguage}
* parameter. * parameter.
* *
* @throws NullPointerException * @throws NullPointerException
* If the <code>schemaLanguage</code> parameter is null. * If the {@code schemaLanguage} parameter is null.
* *
* @see #newInstance(String schemaLanguage) * @see #newInstance(String schemaLanguage)
* *
@ -299,16 +299,16 @@ public abstract class SchemaFactory {
} }
/** /**
* <p>Is specified schema supported by this <code>SchemaFactory</code>?</p> * Is specified schema supported by this {@code SchemaFactory}?
* *
* @param schemaLanguage Specifies the schema language which the returned <code>SchemaFactory</code> will understand. * @param schemaLanguage Specifies the schema language which the returned {@code SchemaFactory} will understand.
* <code>schemaLanguage</code> must specify a <a href="#schemaLanguage">valid</a> schema language. * {@code schemaLanguage} must specify a <a href="#schemaLanguage">valid</a> schema language.
* *
* @return <code>true</code> if <code>SchemaFactory</code> supports <code>schemaLanguage</code>, else <code>false</code>. * @return {@code true} if {@code SchemaFactory} supports {@code schemaLanguage}, else {@code false}.
* *
* @throws NullPointerException If <code>schemaLanguage</code> is <code>null</code>. * @throws NullPointerException If {@code schemaLanguage} is {@code null}.
* @throws IllegalArgumentException If <code>schemaLanguage.length() == 0</code> * @throws IllegalArgumentException If {@code schemaLanguage.length() == 0}
* or <code>schemaLanguage</code> does not specify a <a href="#schemaLanguage">valid</a> schema language. * or {@code schemaLanguage} does not specify a <a href="#schemaLanguage">valid</a> schema language.
*/ */
public abstract boolean isSchemaLanguageSupported(String schemaLanguage); public abstract boolean isSchemaLanguageSupported(String schemaLanguage);
@ -320,7 +320,7 @@ public abstract class SchemaFactory {
* temporarily be unable to return its value. * temporarily be unable to return its value.
* *
* <p>Implementors are free (and encouraged) to invent their own features, * <p>Implementors are free (and encouraged) to invent their own features,
* using names built on their own URIs.</p> * using names built on their own URIs.
* *
* @param name The feature name, which is a non-null fully-qualified URI. * @param name The feature name, which is a non-null fully-qualified URI.
* *
@ -331,7 +331,7 @@ public abstract class SchemaFactory {
* @throws SAXNotSupportedException When the * @throws SAXNotSupportedException When the
* {@link SchemaFactory} recognizes the feature name but * {@link SchemaFactory} recognizes the feature name but
* cannot determine its value at this time. * cannot determine its value at this time.
* @throws NullPointerException If <code>name</code> is <code>null</code>. * @throws NullPointerException If {@code name} is {@code null}.
* *
* @see #setFeature(String, boolean) * @see #setFeature(String, boolean)
*/ */
@ -345,38 +345,37 @@ public abstract class SchemaFactory {
} }
/** /**
* <p>Set a feature for this <code>SchemaFactory</code>, * Set a feature for this {@code SchemaFactory},
* {@link Schema}s created by this factory, and by extension, * {@link Schema}s created by this factory, and by extension,
* {@link Validator}s and {@link ValidatorHandler}s created by * {@link Validator}s and {@link ValidatorHandler}s created by
* those {@link Schema}s. * those {@link Schema}s.
* </p>
* *
* <p>Implementors and developers should pay particular attention * <p>Implementors and developers should pay particular attention
* to how the special {@link Schema} object returned by {@link * to how the special {@link Schema} object returned by {@link
* #newSchema()} is processed. In some cases, for example, when the * #newSchema()} is processed. In some cases, for example, when the
* <code>SchemaFactory</code> and the class actually loading the * {@code SchemaFactory} and the class actually loading the
* schema come from different implementations, it may not be possible * schema come from different implementations, it may not be possible
* for <code>SchemaFactory</code> features to be inherited automatically. * for {@code SchemaFactory} features to be inherited automatically.
* Developers should * Developers should
* make sure that features, such as secure processing, are explicitly * make sure that features, such as secure processing, are explicitly
* set in both places.</p> * set in both places.
* *
* <p>The feature name is any fully-qualified URI. It is * <p>The feature name is any fully-qualified URI. It is
* possible for a {@link SchemaFactory} to expose a feature value but * possible for a {@link SchemaFactory} to expose a feature value but
* to be unable to change the current value.</p> * to be unable to change the current value.
* *
* <p>All implementations are required to support the {@link javax.xml.XMLConstants#FEATURE_SECURE_PROCESSING} feature. * <p>All implementations are required to support the {@link javax.xml.XMLConstants#FEATURE_SECURE_PROCESSING} feature.
* When the feature is:</p> * When the feature is:
* <ul> * <ul>
* <li> * <li>
* <code>true</code>: the implementation will limit XML processing to conform to implementation limits. * {@code true}: the implementation will limit XML processing to conform to implementation limits.
* Examples include entity expansion limits and XML Schema constructs that would consume large amounts of resources. * Examples include entity expansion limits and XML Schema constructs that would consume large amounts of resources.
* If XML processing is limited for security reasons, it will be reported via a call to the registered * If XML processing is limited for security reasons, it will be reported via a call to the registered
* {@link ErrorHandler#fatalError(SAXParseException exception)}. * {@link ErrorHandler#fatalError(SAXParseException exception)}.
* See {@link #setErrorHandler(ErrorHandler errorHandler)}. * See {@link #setErrorHandler(ErrorHandler errorHandler)}.
* </li> * </li>
* <li> * <li>
* <code>false</code>: the implementation will processing XML according to the XML specifications without * {@code false}: the implementation will processing XML according to the XML specifications without
* regard to possible implementation limits. * regard to possible implementation limits.
* </li> * </li>
* </ul> * </ul>
@ -389,7 +388,7 @@ public abstract class SchemaFactory {
* @throws SAXNotSupportedException When the * @throws SAXNotSupportedException When the
* {@link SchemaFactory} recognizes the feature name but * {@link SchemaFactory} recognizes the feature name but
* cannot set the requested value. * cannot set the requested value.
* @throws NullPointerException If <code>name</code> is <code>null</code>. * @throws NullPointerException If {@code name} is {@code null}.
* *
* @see #getFeature(String) * @see #getFeature(String)
*/ */
@ -405,15 +404,15 @@ public abstract class SchemaFactory {
/** /**
* Set the value of a property. * Set the value of a property.
* *
* <p>The property name is any fully-qualified URI. It is * <p>The property name is any fully-qualified URI. It is
* possible for a {@link SchemaFactory} to recognize a property name but * possible for a {@link SchemaFactory} to recognize a property name but
* to be unable to change the current value.</p> * to be unable to change the current value.
* *
* <p> * <p>
* All implementations that implement JAXP 1.5 or newer are required to * All implementations that implement JAXP 1.5 or newer are required to
* support the {@link javax.xml.XMLConstants#ACCESS_EXTERNAL_DTD} and * support the {@link javax.xml.XMLConstants#ACCESS_EXTERNAL_DTD} and
* {@link javax.xml.XMLConstants#ACCESS_EXTERNAL_SCHEMA} properties. * {@link javax.xml.XMLConstants#ACCESS_EXTERNAL_SCHEMA} properties.
* </p> *
* <ul> * <ul>
* <li> * <li>
* <p>Access to external DTDs in Schema files is restricted to the protocols * <p>Access to external DTDs in Schema files is restricted to the protocols
@ -421,14 +420,14 @@ public abstract class SchemaFactory {
* If access is denied during the creation of new Schema due to the restriction * If access is denied during the creation of new Schema due to the restriction
* of this property, {@link org.xml.sax.SAXException} will be thrown by the * of this property, {@link org.xml.sax.SAXException} will be thrown by the
* {@link #newSchema(Source)} or {@link #newSchema(File)} * {@link #newSchema(Source)} or {@link #newSchema(File)}
* or {@link #newSchema(URL)} or or {@link #newSchema(Source[])} method.</p> * or {@link #newSchema(URL)} or {@link #newSchema(Source[])} method.
* *
* <p>Access to external DTDs in xml source files is restricted to the protocols * <p>Access to external DTDs in xml source files is restricted to the protocols
* specified by the {@link javax.xml.XMLConstants#ACCESS_EXTERNAL_DTD} property. * specified by the {@link javax.xml.XMLConstants#ACCESS_EXTERNAL_DTD} property.
* If access is denied during validation due to the restriction * If access is denied during validation due to the restriction
* of this property, {@link org.xml.sax.SAXException} will be thrown by the * of this property, {@link org.xml.sax.SAXException} will be thrown by the
* {@link javax.xml.validation.Validator#validate(Source)} or * {@link javax.xml.validation.Validator#validate(Source)} or
* {@link javax.xml.validation.Validator#validate(Source, Result)} method.</p> * {@link javax.xml.validation.Validator#validate(Source, Result)} method.
* *
* <p>Access to external reference set by the schemaLocation attribute is * <p>Access to external reference set by the schemaLocation attribute is
* restricted to the protocols specified by the * restricted to the protocols specified by the
@ -436,7 +435,7 @@ public abstract class SchemaFactory {
* If access is denied during validation due to the restriction of this property, * If access is denied during validation due to the restriction of this property,
* {@link org.xml.sax.SAXException} will be thrown by the * {@link org.xml.sax.SAXException} will be thrown by the
* {@link javax.xml.validation.Validator#validate(Source)} or * {@link javax.xml.validation.Validator#validate(Source)} or
* {@link javax.xml.validation.Validator#validate(Source, Result)} method.</p> * {@link javax.xml.validation.Validator#validate(Source, Result)} method.
* *
* <p>Access to external reference set by the Import * <p>Access to external reference set by the Import
* and Include element is restricted to the protocols specified by the * and Include element is restricted to the protocols specified by the
@ -444,7 +443,7 @@ public abstract class SchemaFactory {
* If access is denied during the creation of new Schema due to the restriction * If access is denied during the creation of new Schema due to the restriction
* of this property, {@link org.xml.sax.SAXException} will be thrown by the * of this property, {@link org.xml.sax.SAXException} will be thrown by the
* {@link #newSchema(Source)} or {@link #newSchema(File)} * {@link #newSchema(Source)} or {@link #newSchema(File)}
* or {@link #newSchema(URL)} or {@link #newSchema(Source[])} method.</p> * or {@link #newSchema(URL)} or {@link #newSchema(Source[])} method.
* </li> * </li>
* </ul> * </ul>
* *
@ -456,7 +455,7 @@ public abstract class SchemaFactory {
* @throws SAXNotSupportedException When the * @throws SAXNotSupportedException When the
* {@link SchemaFactory} recognizes the property name but * {@link SchemaFactory} recognizes the property name but
* cannot set the requested value. * cannot set the requested value.
* @throws NullPointerException If <code>name</code> is <code>null</code>. * @throws NullPointerException If {@code name} is {@code null}.
*/ */
public void setProperty(String name, Object object) public void setProperty(String name, Object object)
throws SAXNotRecognizedException, SAXNotSupportedException { throws SAXNotRecognizedException, SAXNotSupportedException {
@ -472,13 +471,13 @@ public abstract class SchemaFactory {
* *
* <p>The property name is any fully-qualified URI. It is * <p>The property name is any fully-qualified URI. It is
* possible for a {@link SchemaFactory} to recognize a property name but * possible for a {@link SchemaFactory} to recognize a property name but
* temporarily be unable to return its value.</p> * temporarily be unable to return its value.
* *
* <p>{@link SchemaFactory}s are not required to recognize any specific * <p>{@link SchemaFactory}s are not required to recognize any specific
* property names.</p> * property names.
* *
* <p>Implementors are free (and encouraged) to invent their own properties, * <p>Implementors are free (and encouraged) to invent their own properties,
* using names built on their own URIs.</p> * using names built on their own URIs.
* *
* @param name The property name, which is a non-null fully-qualified URI. * @param name The property name, which is a non-null fully-qualified URI.
* *
@ -489,7 +488,7 @@ public abstract class SchemaFactory {
* @throws SAXNotSupportedException When the * @throws SAXNotSupportedException When the
* XMLReader recognizes the property name but * XMLReader recognizes the property name but
* cannot determine its value at this time. * cannot determine its value at this time.
* @throws NullPointerException If <code>name</code> is <code>null</code>. * @throws NullPointerException If {@code name} is {@code null}.
* *
* @see #setProperty(String, Object) * @see #setProperty(String, Object)
*/ */
@ -504,7 +503,7 @@ public abstract class SchemaFactory {
/** /**
* Sets the {@link ErrorHandler} to receive errors encountered * Sets the {@link ErrorHandler} to receive errors encountered
* during the <code>newSchema</code> method invocation. * during the {@code newSchema} method invocation.
* *
* <p> * <p>
* Error handler can be used to customize the error handling process * Error handler can be used to customize the error handling process
@ -521,7 +520,7 @@ public abstract class SchemaFactory {
* <p> * <p>
* If any {@link Throwable} (or instances of its derived classes) * If any {@link Throwable} (or instances of its derived classes)
* is thrown from an {@link ErrorHandler}, * is thrown from an {@link ErrorHandler},
* the caller of the <code>newSchema</code> method will be thrown * the caller of the {@code newSchema} method will be thrown
* the same {@link Throwable} object. * the same {@link Throwable} object.
* *
* <p> * <p>
@ -557,7 +556,7 @@ public abstract class SchemaFactory {
* {@link ValidatorHandler}s that are created from this {@link SchemaFactory}. * {@link ValidatorHandler}s that are created from this {@link SchemaFactory}.
* *
* @param errorHandler A new error handler to be set. * @param errorHandler A new error handler to be set.
* This parameter can be <code>null</code>. * This parameter can be {@code null}.
*/ */
public abstract void setErrorHandler(ErrorHandler errorHandler); public abstract void setErrorHandler(ErrorHandler errorHandler);
@ -583,7 +582,7 @@ public abstract class SchemaFactory {
* when it needs to locate external resources while parsing schemas, * when it needs to locate external resources while parsing schemas,
* although exactly what constitutes "locating external resources" is * although exactly what constitutes "locating external resources" is
* up to each schema language. For example, for W3C XML Schema, * up to each schema language. For example, for W3C XML Schema,
* this includes files <code>&lt;include></code>d or <code>&lt;import></code>ed, * this includes files {@code <include>}d or {@code <import>}ed,
* and DTD referenced from schema files, etc. * and DTD referenced from schema files, etc.
* *
* <p> * <p>
@ -607,7 +606,7 @@ public abstract class SchemaFactory {
* If a {@link LSResourceResolver} throws a {@link RuntimeException} * If a {@link LSResourceResolver} throws a {@link RuntimeException}
* (or instances of its derived classes), * (or instances of its derived classes),
* then the {@link SchemaFactory} will abort the parsing and * then the {@link SchemaFactory} will abort the parsing and
* the caller of the <code>newSchema</code> method will receive * the caller of the {@code newSchema} method will receive
* the same {@link RuntimeException}. * the same {@link RuntimeException}.
* *
* <p> * <p>
@ -635,48 +634,48 @@ public abstract class SchemaFactory {
public abstract LSResourceResolver getResourceResolver(); public abstract LSResourceResolver getResourceResolver();
/** /**
* <p>Parses the specified source as a schema and returns it as a schema.</p> * Parses the specified source as a schema and returns it as a schema.
* *
* <p>This is a convenience method for {@link #newSchema(Source[] schemas)}.</p> * <p>This is a convenience method for {@link #newSchema(Source[] schemas)}.
* *
* @param schema Source that represents a schema. * @param schema Source that represents a schema.
* *
* @return New <code>Schema</code> from parsing <code>schema</code>. * @return New {@code Schema} from parsing {@code schema}.
* *
* @throws SAXException If a SAX error occurs during parsing. * @throws SAXException If a SAX error occurs during parsing.
* @throws NullPointerException if <code>schema</code> is null. * @throws NullPointerException if {@code schema} is null.
*/ */
public Schema newSchema(Source schema) throws SAXException { public Schema newSchema(Source schema) throws SAXException {
return newSchema(new Source[]{schema}); return newSchema(new Source[]{schema});
} }
/** /**
* <p>Parses the specified <code>File</code> as a schema and returns it as a <code>Schema</code>.</p> * Parses the specified {@code File} as a schema and returns it as a {@code Schema}.
* *
* <p>This is a convenience method for {@link #newSchema(Source schema)}.</p> * <p>This is a convenience method for {@link #newSchema(Source schema)}.
* *
* @param schema File that represents a schema. * @param schema File that represents a schema.
* *
* @return New <code>Schema</code> from parsing <code>schema</code>. * @return New {@code Schema} from parsing {@code schema}.
* *
* @throws SAXException If a SAX error occurs during parsing. * @throws SAXException If a SAX error occurs during parsing.
* @throws NullPointerException if <code>schema</code> is null. * @throws NullPointerException if {@code schema} is null.
*/ */
public Schema newSchema(File schema) throws SAXException { public Schema newSchema(File schema) throws SAXException {
return newSchema(new StreamSource(schema)); return newSchema(new StreamSource(schema));
} }
/** /**
* <p>Parses the specified <code>URL</code> as a schema and returns it as a <code>Schema</code>.</p> * Parses the specified {@code URL} as a schema and returns it as a {@code Schema}.
* *
* <p>This is a convenience method for {@link #newSchema(Source schema)}.</p> * <p>This is a convenience method for {@link #newSchema(Source schema)}.
* *
* @param schema <code>URL</code> that represents a schema. * @param schema {@code URL} that represents a schema.
* *
* @return New <code>Schema</code> from parsing <code>schema</code>. * @return New {@code Schema} from parsing {@code schema}.
* *
* @throws SAXException If a SAX error occurs during parsing. * @throws SAXException If a SAX error occurs during parsing.
* @throws NullPointerException if <code>schema</code> is null. * @throws NullPointerException if {@code schema} is null.
*/ */
public Schema newSchema(URL schema) throws SAXException { public Schema newSchema(URL schema) throws SAXException {
return newSchema(new StreamSource(schema.toExternalForm())); return newSchema(new StreamSource(schema.toExternalForm()));
@ -710,7 +709,7 @@ public abstract class SchemaFactory {
* regard. While a processor should be consistent in its treatment of * regard. While a processor should be consistent in its treatment of
* JAXP schema sources and XML Schema imports, the behaviour between * JAXP schema sources and XML Schema imports, the behaviour between
* JAXP-compliant parsers may vary; in particular, parsers may choose * JAXP-compliant parsers may vary; in particular, parsers may choose
* to ignore all but the first &lt;import> for a given namespace, * to ignore all but the first {@code <import>} for a given namespace,
* regardless of information provided in schemaLocation. * regardless of information provided in schemaLocation.
* *
* <p> * <p>
@ -721,7 +720,7 @@ public abstract class SchemaFactory {
* <h2>RELAX NG</h2> * <h2>RELAX NG</h2>
* *
* <p>For RELAX NG, this method must throw {@link UnsupportedOperationException} * <p>For RELAX NG, this method must throw {@link UnsupportedOperationException}
* if <code>schemas.length!=1</code>. * if {@code schemas.length!=1}.
* *
* *
* @param schemas * @param schemas
@ -748,7 +747,7 @@ public abstract class SchemaFactory {
* When an {@link ErrorHandler} is set, errors are reported to * When an {@link ErrorHandler} is set, errors are reported to
* there first. See {@link #setErrorHandler(ErrorHandler)}. * there first. See {@link #setErrorHandler(ErrorHandler)}.
* @throws NullPointerException * @throws NullPointerException
* If the <code>schemas</code> parameter itself is null or * If the {@code schemas} parameter itself is null or
* any item in the array is null. * any item in the array is null.
* @throws IllegalArgumentException * @throws IllegalArgumentException
* If any item in the array is not recognized by this method. * If any item in the array is not recognized by this method.
@ -765,7 +764,7 @@ public abstract class SchemaFactory {
* is created. * is created.
* *
* <p>Also, implementations are allowed to use implementation-specific * <p>Also, implementations are allowed to use implementation-specific
* property/feature to alter the semantics of this method.</p> * property/feature to alter the semantics of this method.
* *
* <p>Implementors and developers should pay particular attention * <p>Implementors and developers should pay particular attention
* to how the features set on this {@link SchemaFactory} are * to how the features set on this {@link SchemaFactory} are
@ -776,7 +775,7 @@ public abstract class SchemaFactory {
* for {@link SchemaFactory} features to be inherited automatically. * for {@link SchemaFactory} features to be inherited automatically.
* Developers should * Developers should
* make sure that features, such as secure processing, are explicitly * make sure that features, such as secure processing, are explicitly
* set in both places.</p> * set in both places.
* *
* <h2>W3C XML Schema 1.0</h2> * <h2>W3C XML Schema 1.0</h2>
* <p> * <p>

134
jaxp/src/java.xml/share/classes/javax/xml/validation/Validator.java
View file

@ -37,16 +37,15 @@ import org.xml.sax.SAXNotRecognizedException;
import org.xml.sax.SAXNotSupportedException; import org.xml.sax.SAXNotSupportedException;
/** /**
* <p>A processor that checks an XML document against {@link Schema}.</p> * A processor that checks an XML document against {@link Schema}.
* *
* <p> * <p>
* A validator object is not thread-safe and not reentrant. * A validator object is not thread-safe and not reentrant.
* In other words, it is the application's responsibility to make * In other words, it is the application's responsibility to make
* sure that one {@link Validator} object is not used from * sure that one {@link Validator} object is not used from
* more than one thread at any given time, and while the <code>validate</code> * more than one thread at any given time, and while the {@code validate}
* method is invoked, applications may not recursively call * method is invoked, applications may not recursively call
* the <code>validate</code> method. * the {@code validate} method.
* <p>
* *
* *
* @author <a href="mailto:Kohsuke.Kawaguchi@Sun.com">Kohsuke Kawaguchi</a> * @author <a href="mailto:Kohsuke.Kawaguchi@Sun.com">Kohsuke Kawaguchi</a>
@ -57,27 +56,28 @@ public abstract class Validator {
/** /**
* Constructor for derived classes. * Constructor for derived classes.
* *
* <p>The constructor does nothing.</p> * <p>The constructor does nothing.
* *
* <p>Derived classes must create {@link Validator} objects that have * <p>Derived classes must create {@link Validator} objects that have
* <code>null</code> {@link ErrorHandler} and * {@code null} {@link ErrorHandler} and
* <code>null</code> {@link LSResourceResolver}. * {@code null} {@link LSResourceResolver}.
* </p>
*/ */
protected Validator() { protected Validator() {
} }
/** /**
* <p>Reset this <code>Validator</code> to its original configuration.</p> * Reset this {@code Validator} to its original configuration.
* *
* <p><code>Validator</code> is reset to the same state as when it was created with * <p>{@code Validator} is reset to the same state as when it was created with
* {@link Schema#newValidator()}. * {@link Schema#newValidator()}.
* <code>reset()</code> is designed to allow the reuse of existing <code>Validator</code>s * {@code reset()} is designed to allow the reuse of existing {@code Validator}s
* thus saving resources associated with the creation of new <code>Validator</code>s.</p> * thus saving resources associated with the creation of new {@code Validator}s.
* *
* <p>The reset <code>Validator</code> is not guaranteed to have the same {@link LSResourceResolver} or {@link ErrorHandler} * <p>The reset {@code Validator} is not guaranteed to have
* <code>Object</code>s, e.g. {@link Object#equals(Object obj)}. It is guaranteed to have a functionally equal * the same {@link LSResourceResolver} or {@link ErrorHandler}
* <code>LSResourceResolver</code> and <code>ErrorHandler</code>.</p> * {@code Object}s, e.g. {@link Object#equals(Object obj)}.
* It is guaranteed to have a functionally equal
* {@code LSResourceResolver} and {@code ErrorHandler}.
*/ */
public abstract void reset(); public abstract void reset();
@ -86,7 +86,7 @@ public abstract class Validator {
* *
* <p>This is just a convenience method for * <p>This is just a convenience method for
* {@link #validate(Source source, Result result)} * {@link #validate(Source source, Result result)}
* with <code>result</code> of <code>null</code>.</p> * with {@code result} of {@code null}.
* *
* @param source * @param source
* XML to be validated. Must be an XML document or * XML to be validated. Must be an XML document or
@ -97,7 +97,7 @@ public abstract class Validator {
* or throw an IllegalArgumentException. * or throw an IllegalArgumentException.
* *
* @throws IllegalArgumentException * @throws IllegalArgumentException
* If the <code>Source</code> * If the {@code Source}
* is an XML artifact that the implementation cannot * is an XML artifact that the implementation cannot
* validate (for example, a processing instruction). * validate (for example, a processing instruction).
* *
@ -113,8 +113,8 @@ public abstract class Validator {
* {@link IOException}. * {@link IOException}.
* *
* *
* @throws NullPointerException If <code>source</code> is * @throws NullPointerException If {@code source} is
* <code>null</code>. * {@code null}.
* *
* @see #validate(Source source, Result result) * @see #validate(Source source, Result result)
*/ */
@ -125,16 +125,16 @@ public abstract class Validator {
} }
/** /**
* <p>Validates the specified input and send the augmented validation * Validates the specified input and send the augmented validation
* result to the specified output.</p> * result to the specified output.
* *
* <p>This method places the following restrictions on the types of * <p>This method places the following restrictions on the types of
* the {@link Source}/{@link Result} accepted.</p> * the {@link Source}/{@link Result} accepted.
* *
* <table border=1> * <table border=1>
* <thead> * <thead>
* <tr> * <tr>
* <th colspan="5"><code>Source</code> / <code>Result</code> Accepted</th> * <th colspan="5">{@code Source} / {@code Result} Accepted</th>
* </tr> * </tr>
* <tr> * <tr>
* <th></th> * <th></th>
@ -146,7 +146,7 @@ public abstract class Validator {
* </thead> * </thead>
* <tbody align="center"> * <tbody align="center">
* <tr> * <tr>
* <td><code>null</code></td> * <td>{@code null}</td>
* <td>OK</td> * <td>OK</td>
* <td>OK</td> * <td>OK</td>
* <td>OK</td> * <td>OK</td>
@ -155,44 +155,44 @@ public abstract class Validator {
* <tr> * <tr>
* <th>{@link javax.xml.transform.stream.StreamResult}</th> * <th>{@link javax.xml.transform.stream.StreamResult}</th>
* <td>OK</td> * <td>OK</td>
* <td><code>IllegalArgumentException</code></td> * <td>{@code IllegalArgumentException}</td>
* <td><code>IllegalArgumentException</code></td> * <td>{@code IllegalArgumentException}</td>
* <td><code>IllegalArgumentException</code></td> * <td>{@code IllegalArgumentException}</td>
* </tr> * </tr>
* <tr> * <tr>
* <th>{@link javax.xml.transform.sax.SAXResult}</th> * <th>{@link javax.xml.transform.sax.SAXResult}</th>
* <td><code>IllegalArgumentException</code></td> * <td>{@code IllegalArgumentException}</td>
* <td>OK</td> * <td>OK</td>
* <td><code>IllegalArgumentException</code></td> * <td>{@code IllegalArgumentException}</td>
* <td><code>IllegalArgumentException</code></td> * <td>{@code IllegalArgumentException}</td>
* </tr> * </tr>
* <tr> * <tr>
* <th>{@link javax.xml.transform.dom.DOMResult}</th> * <th>{@link javax.xml.transform.dom.DOMResult}</th>
* <td><code>IllegalArgumentException</code></td> * <td>{@code IllegalArgumentException}</td>
* <td><code>IllegalArgumentException</code></td> * <td>{@code IllegalArgumentException}</td>
* <td>OK</td> * <td>OK</td>
* <td><code>IllegalArgumentException</code></td> * <td>{@code IllegalArgumentException}</td>
* </tr> * </tr>
* <tr> * <tr>
* <th>{@link javax.xml.transform.stax.StAXResult}</th> * <th>{@link javax.xml.transform.stax.StAXResult}</th>
* <td><code>IllegalArgumentException</code></td> * <td>{@code IllegalArgumentException}</td>
* <td><code>IllegalArgumentException</code></td> * <td>{@code IllegalArgumentException}</td>
* <td><code>IllegalArgumentException</code></td> * <td>{@code IllegalArgumentException}</td>
* <td>OK</td> * <td>OK</td>
* </tr> * </tr>
* </tbody> * </tbody>
* </table> * </table>
* *
* <p>To validate one <code>Source</code> into another kind of * <p>To validate one {@code Source} into another kind of
* <code>Result</code>, use the identity transformer (see * {@code Result}, use the identity transformer (see
* {@link javax.xml.transform.TransformerFactory#newTransformer()}).</p> * {@link javax.xml.transform.TransformerFactory#newTransformer()}).
* *
* <p>Errors found during the validation is sent to the specified * <p>Errors found during the validation is sent to the specified
* {@link ErrorHandler}.</p> * {@link ErrorHandler}.
* *
* <p>If a document is valid, or if a document contains some errors * <p>If a document is valid, or if a document contains some errors
* but none of them were fatal and the <code>ErrorHandler</code> didn't * but none of them were fatal and the {@code ErrorHandler} didn't
* throw any exception, then the method returns normally.</p> * throw any exception, then the method returns normally.
* *
* @param source * @param source
* XML to be validated. Must be an XML document or * XML to be validated. Must be an XML document or
@ -203,34 +203,34 @@ public abstract class Validator {
* or throw an IllegalArgumentException. * or throw an IllegalArgumentException.
* *
* @param result * @param result
* The <code>Result</code> object that receives (possibly augmented) * The {@code Result} object that receives (possibly augmented)
* XML. This parameter can be null if the caller is not interested * XML. This parameter can be null if the caller is not interested
* in it. * in it.
* *
* Note that when a <code>DOMResult</code> is used, * Note that when a {@code DOMResult} is used,
* a validator might just pass the same DOM node from * a validator might just pass the same DOM node from
* <code>DOMSource</code> to <code>DOMResult</code> * {@code DOMSource} to {@code DOMResult}
* (in which case <code>source.getNode()==result.getNode()</code>), * (in which case {@code source.getNode()==result.getNode()}),
* it might copy the entire DOM tree, or it might alter the * it might copy the entire DOM tree, or it might alter the
* node given by the source. * node given by the source.
* *
* @throws IllegalArgumentException * @throws IllegalArgumentException
* If the <code>Result</code> type doesn't match the * If the {@code Result} type doesn't match the
* <code>Source</code> type of if the <code>Source</code> * {@code Source} type of if the {@code Source}
* is an XML artifact that the implementation cannot * is an XML artifact that the implementation cannot
* validate (for example, a processing instruction). * validate (for example, a processing instruction).
* @throws SAXException * @throws SAXException
* If the <code>ErrorHandler</code> throws a * If the {@code ErrorHandler} throws a
* <code>SAXException</code> or * {@code SAXException} or
* if a fatal error is found and the <code>ErrorHandler</code> returns * if a fatal error is found and the {@code ErrorHandler} returns
* normally. * normally.
* @throws IOException * @throws IOException
* If the validator is processing a * If the validator is processing a
* <code>SAXSource</code> and the * {@code SAXSource} and the
* underlying {@link org.xml.sax.XMLReader} throws an * underlying {@link org.xml.sax.XMLReader} throws an
* <code>IOException</code>. * {@code IOException}.
* @throws NullPointerException * @throws NullPointerException
* If the <code>source</code> parameter is <code>null</code>. * If the {@code source} parameter is {@code null}.
* *
* @see #validate(Source source) * @see #validate(Source source)
*/ */
@ -239,7 +239,7 @@ public abstract class Validator {
/** /**
* Sets the {@link ErrorHandler} to receive errors encountered * Sets the {@link ErrorHandler} to receive errors encountered
* during the <code>validate</code> method invocation. * during the {@code validate} method invocation.
* *
* <p> * <p>
* Error handler can be used to customize the error handling process * Error handler can be used to customize the error handling process
@ -255,7 +255,7 @@ public abstract class Validator {
* *
* <p> * <p>
* If any {@link Throwable} is thrown from an {@link ErrorHandler}, * If any {@link Throwable} is thrown from an {@link ErrorHandler},
* the caller of the <code>validate</code> method will be thrown * the caller of the {@code validate} method will be thrown
* the same {@link Throwable} object. * the same {@link Throwable} object.
* *
* <p> * <p>
@ -329,7 +329,7 @@ public abstract class Validator {
* If a {@link LSResourceResolver} throws a {@link RuntimeException} * If a {@link LSResourceResolver} throws a {@link RuntimeException}
* (or instances of its derived classes), * (or instances of its derived classes),
* then the {@link Validator} will abort the parsing and * then the {@link Validator} will abort the parsing and
* the caller of the <code>validate</code> method will receive * the caller of the {@code validate} method will receive
* the same {@link RuntimeException}. * the same {@link RuntimeException}.
* *
* <p> * <p>
@ -366,7 +366,7 @@ public abstract class Validator {
* contexts, such as before, during, or after a validation. * contexts, such as before, during, or after a validation.
* *
* <p>Implementors are free (and encouraged) to invent their own features, * <p>Implementors are free (and encouraged) to invent their own features,
* using names built on their own URIs.</p> * using names built on their own URIs.
* *
* @param name The feature name, which is a non-null fully-qualified URI. * @param name The feature name, which is a non-null fully-qualified URI.
* *
@ -398,14 +398,14 @@ public abstract class Validator {
* <p> * <p>
* Feature can be used to control the way a {@link Validator} * Feature can be used to control the way a {@link Validator}
* parses schemas, although {@link Validator}s are not required * parses schemas, although {@link Validator}s are not required
* to recognize any specific feature names.</p> * to recognize any specific feature names.
* *
* <p>The feature name is any fully-qualified URI. It is * <p>The feature name is any fully-qualified URI. It is
* possible for a {@link Validator} to expose a feature value but * possible for a {@link Validator} to expose a feature value but
* to be unable to change the current value. * to be unable to change the current value.
* Some feature values may be immutable or mutable only * Some feature values may be immutable or mutable only
* in specific contexts, such as before, during, or after * in specific contexts, such as before, during, or after
* a validation.</p> * a validation.
* *
* @param name The feature name, which is a non-null fully-qualified URI. * @param name The feature name, which is a non-null fully-qualified URI.
* @param value The requested value of the feature (true or false). * @param value The requested value of the feature (true or false).
@ -438,27 +438,27 @@ public abstract class Validator {
* to be unable to change the current value. * to be unable to change the current value.
* Some property values may be immutable or mutable only * Some property values may be immutable or mutable only
* in specific contexts, such as before, during, or after * in specific contexts, such as before, during, or after
* a validation.</p> * a validation.
* *
* <p> * <p>
* All implementations that implement JAXP 1.5 or newer are required to * All implementations that implement JAXP 1.5 or newer are required to
* support the {@link javax.xml.XMLConstants#ACCESS_EXTERNAL_DTD} and * support the {@link javax.xml.XMLConstants#ACCESS_EXTERNAL_DTD} and
* {@link javax.xml.XMLConstants#ACCESS_EXTERNAL_SCHEMA} properties. * {@link javax.xml.XMLConstants#ACCESS_EXTERNAL_SCHEMA} properties.
* </p> *
* <ul> * <ul>
* <li> * <li>
* <p>Access to external DTDs in source or Schema file is restricted to * <p>Access to external DTDs in source or Schema file is restricted to
* the protocols specified by the {@link javax.xml.XMLConstants#ACCESS_EXTERNAL_DTD} * the protocols specified by the {@link javax.xml.XMLConstants#ACCESS_EXTERNAL_DTD}
* property. If access is denied during validation due to the restriction * property. If access is denied during validation due to the restriction
* of this property, {@link org.xml.sax.SAXException} will be thrown by the * of this property, {@link org.xml.sax.SAXException} will be thrown by the
* {@link #validate(Source)} method.</p> * {@link #validate(Source)} method.
* *
* <p>Access to external reference set by the schemaLocation attribute is * <p>Access to external reference set by the schemaLocation attribute is
* restricted to the protocols specified by the * restricted to the protocols specified by the
* {@link javax.xml.XMLConstants#ACCESS_EXTERNAL_SCHEMA} property. * {@link javax.xml.XMLConstants#ACCESS_EXTERNAL_SCHEMA} property.
* If access is denied during validation due to the restriction of this property, * If access is denied during validation due to the restriction of this property,
* {@link org.xml.sax.SAXException} will be thrown by the * {@link org.xml.sax.SAXException} will be thrown by the
* {@link #validate(Source)} method.</p> * {@link #validate(Source)} method.
* </li> * </li>
* </ul> * </ul>
* *
@ -490,13 +490,13 @@ public abstract class Validator {
* possible for a {@link Validator} to recognize a property name but * possible for a {@link Validator} to recognize a property name but
* temporarily be unable to return its value. * temporarily be unable to return its value.
* Some property values may be available only in specific * Some property values may be available only in specific
* contexts, such as before, during, or after a validation.</p> * contexts, such as before, during, or after a validation.
* *
* <p>{@link Validator}s are not required to recognize any specific * <p>{@link Validator}s are not required to recognize any specific
* property names.</p> * property names.
* *
* <p>Implementors are free (and encouraged) to invent their own properties, * <p>Implementors are free (and encouraged) to invent their own properties,
* using names built on their own URIs.</p> * using names built on their own URIs.
* *
* @param name The property name, which is a non-null fully-qualified URI. * @param name The property name, which is a non-null fully-qualified URI.
* *

4
jaxp/src/java.xml/share/classes/javax/xml/xpath/XPath.java
View file

@ -32,7 +32,7 @@ import org.xml.sax.InputSource;
/** /**
* {@code XPath} provides access to the XPath evaluation environment and expressions. * {@code XPath} provides access to the XPath evaluation environment and expressions.
* *
* <a name="XPath-evaluation"/> * <a name="XPath-evaluation"></a>
* <table border="1" cellpadding="2"> * <table border="1" cellpadding="2">
* <thead> * <thead>
* <tr> * <tr>
@ -90,7 +90,6 @@ import org.xml.sax.InputSource;
* more than one thread at any given time, and while the {@code evaluate} * more than one thread at any given time, and while the {@code evaluate}
* method is invoked, applications may not recursively call * method is invoked, applications may not recursively call
* the {@code evaluate} method. * the {@code evaluate} method.
* <p>
* *
* @author <a href="Norman.Walsh@Sun.com">Norman Walsh</a> * @author <a href="Norman.Walsh@Sun.com">Norman Walsh</a>
* @author <a href="Jeff.Suttor@Sun.com">Jeff Suttor</a> * @author <a href="Jeff.Suttor@Sun.com">Jeff Suttor</a>
@ -462,7 +461,6 @@ public interface XPath {
* <pre> {@code * <pre> {@code
* evaluateExpression(expression, item, XPathEvaluationResult.class); * evaluateExpression(expression, item, XPathEvaluationResult.class);
* }</pre> * }</pre>
* <p>
* *
* @implSpec * @implSpec
* The default implementation in the XPath API is equivalent to: * The default implementation in the XPath API is equivalent to:

3
jaxp/src/java.xml/share/classes/javax/xml/xpath/XPathEvaluationResult.java
View file

@ -32,7 +32,6 @@ import org.w3c.dom.Node;
* evaluation of an XPath expression within the context of a particular node. * evaluation of an XPath expression within the context of a particular node.
* The evaluation of an XPath expression can result in various result types as * The evaluation of an XPath expression can result in various result types as
* defined in XML Path Language (XPath) Version 1.0. * defined in XML Path Language (XPath) Version 1.0.
* <p>
* *
* @param <T> the object type returned by the XPath evaluation. * @param <T> the object type returned by the XPath evaluation.
* @see <a href="http://www.w3.org/TR/xpath">XML Path Language (XPath) Version * @see <a href="http://www.w3.org/TR/xpath">XML Path Language (XPath) Version
@ -121,7 +120,7 @@ public interface XPathEvaluationResult<T> {
public XPathResultType type(); public XPathResultType type();
/** /**
* Returns the value of the result as the type &lt;T&gt; specified for the class. * Returns the value of the result as the type {@code <T>} specified for the class.
* *
* @return The value of the result. * @return The value of the result.
*/ */

46
jaxp/src/java.xml/share/classes/javax/xml/xpath/XPathException.java
View file

@ -33,7 +33,7 @@ import java.io.ObjectStreamField;
import java.io.InvalidClassException; import java.io.InvalidClassException;
/** /**
* <code>XPathException</code> represents a generic XPath exception.</p> * {@code XPathException} represents a generic XPath exception.
* *
* @author <a href="Norman.Walsh@Sun.com">Norman Walsh</a> * @author <a href="Norman.Walsh@Sun.com">Norman Walsh</a>
* @author <a href="mailto:Jeff.Suttor@Sun.COM">Jeff Suttor</a> * @author <a href="mailto:Jeff.Suttor@Sun.COM">Jeff Suttor</a>
@ -46,23 +46,23 @@ public class XPathException extends Exception {
}; };
/** /**
* <p>Stream Unique Identifier.</p> * Stream Unique Identifier.
*/ */
private static final long serialVersionUID = -1837080260374986980L; private static final long serialVersionUID = -1837080260374986980L;
/** /**
* <p>Constructs a new <code>XPathException</code> * Constructs a new {@code XPathException}
* with the specified detail <code>message</code>.</p> * with the specified detail {@code message}.
* *
* <p>The <code>cause</code> is not initialized.</p> * <p>The {@code cause} is not initialized.
* *
* <p>If <code>message</code> is <code>null</code>, * <p>If {@code message} is {@code null},
* then a <code>NullPointerException</code> is thrown.</p> * then a {@code NullPointerException} is thrown.
* *
* @param message The detail message. * @param message The detail message.
* *
* @throws NullPointerException When <code>message</code> is * @throws NullPointerException When {@code message} is
* <code>null</code>. * {@code null}.
*/ */
public XPathException(String message) { public XPathException(String message) {
super(message); super(message);
@ -72,15 +72,15 @@ public class XPathException extends Exception {
} }
/** /**
* <p>Constructs a new <code>XPathException</code> * Constructs a new {@code XPathException}
* with the specified <code>cause</code>.</p> * with the specified {@code cause}.
* *
* <p>If <code>cause</code> is <code>null</code>, * <p>If {@code cause} is {@code null},
* then a <code>NullPointerException</code> is thrown.</p> * then a {@code NullPointerException} is thrown.
* *
* @param cause The cause. * @param cause The cause.
* *
* @throws NullPointerException if <code>cause</code> is <code>null</code>. * @throws NullPointerException if {@code cause} is {@code null}.
*/ */
public XPathException(Throwable cause) { public XPathException(Throwable cause) {
super(cause); super(cause);
@ -90,7 +90,7 @@ public class XPathException extends Exception {
} }
/** /**
* <p>Get the cause of this XPathException.</p> * Get the cause of this XPathException.
* *
* @return Cause of this XPathException. * @return Cause of this XPathException.
*/ */
@ -103,7 +103,7 @@ public class XPathException extends Exception {
* The cause is got from the parent class. * The cause is got from the parent class.
* *
* @param out stream used for serialization. * @param out stream used for serialization.
* @throws IOException thrown by <code>ObjectOutputStream</code> * @throws IOException thrown by {@code ObjectOutputStream}
* *
*/ */
private void writeObject(ObjectOutputStream out) private void writeObject(ObjectOutputStream out)
@ -120,8 +120,8 @@ public class XPathException extends Exception {
* done before. * done before.
* *
* @param in stream used for deserialization * @param in stream used for deserialization
* @throws IOException thrown by <code>ObjectInputStream</code> * @throws IOException thrown by {@code ObjectInputStream}
* @throws ClassNotFoundException thrown by <code>ObjectInputStream</code> * @throws ClassNotFoundException thrown by {@code ObjectInputStream}
*/ */
private void readObject(ObjectInputStream in) private void readObject(ObjectInputStream in)
throws IOException, ClassNotFoundException throws IOException, ClassNotFoundException
@ -139,9 +139,9 @@ public class XPathException extends Exception {
} }
/** /**
* <p>Print stack trace to specified <code>PrintStream</code>.</p> * Print stack trace to specified {@code PrintStream}.
* *
* @param s Print stack trace to this <code>PrintStream</code>. * @param s Print stack trace to this {@code PrintStream}.
*/ */
public void printStackTrace(java.io.PrintStream s) { public void printStackTrace(java.io.PrintStream s) {
if (getCause() != null) { if (getCause() != null) {
@ -153,16 +153,16 @@ public class XPathException extends Exception {
} }
/** /**
* <p>Print stack trace to <code>System.err</code>.</p> * Print stack trace to {@code System.err}.
*/ */
public void printStackTrace() { public void printStackTrace() {
printStackTrace(System.err); printStackTrace(System.err);
} }
/** /**
* <p>Print stack trace to specified <code>PrintWriter</code>.</p> * Print stack trace to specified {@code PrintWriter}.
* *
* @param s Print stack trace to this <code>PrintWriter</code>. * @param s Print stack trace to this {@code PrintWriter}.
*/ */
public void printStackTrace(PrintWriter s) { public void printStackTrace(PrintWriter s) {

47
jaxp/src/java.xml/share/classes/javax/xml/xpath/XPathExpression.java
View file

@ -29,9 +29,9 @@ import javax.xml.namespace.QName;
import org.xml.sax.InputSource; import org.xml.sax.InputSource;
/** /**
* <p>{@code XPathExpression} provides access to compiled XPath expressions.</p> * {@code XPathExpression} provides access to compiled XPath expressions.
* *
* <a name="XPathExpression-evaluation"/> * <a name="XPathExpression-evaluation"></a>
* <table border="1" cellpadding="2"> * <table border="1" cellpadding="2">
* <thead> * <thead>
* <tr> * <tr>
@ -54,7 +54,7 @@ import org.xml.sax.InputSource;
* If the expression contains a variable reference, its value will be found through the {@link XPathVariableResolver}. * If the expression contains a variable reference, its value will be found through the {@link XPathVariableResolver}.
* An {@link XPathExpressionException} is raised if the variable resolver is undefined or * An {@link XPathExpressionException} is raised if the variable resolver is undefined or
* the resolver returns {@code null} for the variable. * the resolver returns {@code null} for the variable.
* The value of a variable must be immutable through the course of any single evaluation.</p> * The value of a variable must be immutable through the course of any single evaluation.
* </td> * </td>
* </tr> * </tr>
* <tr> * <tr>
@ -62,7 +62,7 @@ import org.xml.sax.InputSource;
* <td> * <td>
* If the expression contains a function reference, the function will be found through the {@link XPathFunctionResolver}. * If the expression contains a function reference, the function will be found through the {@link XPathFunctionResolver}.
* An {@link XPathExpressionException} is raised if the function resolver is undefined or * An {@link XPathExpressionException} is raised if the function resolver is undefined or
* the function resolver returns {@code null} for the function.</p> * the function resolver returns {@code null} for the function.
* </td> * </td>
* </tr> * </tr>
* <tr> * <tr>
@ -76,9 +76,10 @@ import org.xml.sax.InputSource;
* <td> * <td>
* This result of evaluating an expression is converted to an instance of the desired return type. * This result of evaluating an expression is converted to an instance of the desired return type.
* Valid return types are defined in {@link XPathConstants}. * Valid return types are defined in {@link XPathConstants}.
* Conversion to the return type follows XPath conversion rules.</p> * Conversion to the return type follows XPath conversion rules.
* </td> * </td>
* </tr> * </tr>
* </tbody>
* </table> * </table>
* *
* <p>An XPath expression is not thread-safe and not reentrant. * <p>An XPath expression is not thread-safe and not reentrant.
@ -87,7 +88,6 @@ import org.xml.sax.InputSource;
* more than one thread at any given time, and while the {@code evaluate} * more than one thread at any given time, and while the {@code evaluate}
* method is invoked, applications may not recursively call * method is invoked, applications may not recursively call
* the {@code evaluate} method. * the {@code evaluate} method.
* <p>
* *
* @author <a href="mailto:Norman.Walsh@Sun.com">Norman Walsh</a> * @author <a href="mailto:Norman.Walsh@Sun.com">Norman Walsh</a>
* @author <a href="mailto:Jeff.Suttor@Sun.com">Jeff Suttor</a> * @author <a href="mailto:Jeff.Suttor@Sun.com">Jeff Suttor</a>
@ -98,10 +98,10 @@ public interface XPathExpression {
/** /**
* <p>Evaluate the compiled XPath expression in the specified context and return the result as the specified type.</p> * Evaluate the compiled XPath expression in the specified context and return the result as the specified type.
* *
* <p>See <a href="#XPathExpression-evaluation">Evaluation of XPath Expressions</a> for context item evaluation, * <p>See <a href="#XPathExpression-evaluation">Evaluation of XPath Expressions</a> for context item evaluation,
* variable, function and QName resolution and return type conversion.</p> * variable, function and QName resolution and return type conversion.
* *
* <p> * <p>
* The parameter {@code item} represents the context the XPath expression * The parameter {@code item} represents the context the XPath expression
@ -126,13 +126,13 @@ public interface XPathExpression {
throws XPathExpressionException; throws XPathExpressionException;
/** /**
* <p>Evaluate the compiled XPath expression in the specified context and return the result as a {@code String}.</p> * Evaluate the compiled XPath expression in the specified context and return the result as a {@code String}.
* *
* <p>This method calls {@link #evaluate(Object item, QName returnType)} with a {@code returnType} of * <p>This method calls {@link #evaluate(Object item, QName returnType)} with a {@code returnType} of
* {@link XPathConstants#STRING}.</p> * {@link XPathConstants#STRING}.
* *
* <p>See <a href="#XPathExpression-evaluation">Evaluation of XPath Expressions</a> for context item evaluation, * <p>See <a href="#XPathExpression-evaluation">Evaluation of XPath Expressions</a> for context item evaluation,
* variable, function and QName resolution and return type conversion.</p> * variable, function and QName resolution and return type conversion.
* *
* <p> * <p>
* The parameter {@code item} represents the context the XPath expression * The parameter {@code item} represents the context the XPath expression
@ -153,20 +153,21 @@ public interface XPathExpression {
throws XPathExpressionException; throws XPathExpressionException;
/** /**
* <p>Evaluate the compiled XPath expression in the context of the specified {@code InputSource} and return the result as the * Evaluate the compiled XPath expression in the context
* specified type.</p> * of the specified {@code InputSource} and return the result as the
* specified type.
* *
* <p>This method builds a data model for the {@link InputSource} and calls * <p>This method builds a data model for the {@link InputSource} and calls
* {@link #evaluate(Object item, QName returnType)} on the resulting document object.</p> * {@link #evaluate(Object item, QName returnType)} on the resulting document object.
* *
* <p>See <a href="#XPathExpression-evaluation">Evaluation of XPath Expressions</a> for context item evaluation, * <p>See <a href="#XPathExpression-evaluation">Evaluation of XPath Expressions</a> for context item evaluation,
* variable, function and QName resolution and return type conversion.</p> * variable, function and QName resolution and return type conversion.
* *
* <p>If {@code returnType} is not one of the types defined in {@link XPathConstants}, * <p>If {@code returnType} is not one of the types defined in {@link XPathConstants},
* then an {@code IllegalArgumentException} is thrown.</p> * then an {@code IllegalArgumentException} is thrown.
* *
* <p>If {@code source} or {@code returnType} is {@code null}, * <p>If {@code source} or {@code returnType} is {@code null},
* then a {@code NullPointerException} is thrown.</p> * then a {@code NullPointerException} is thrown.
* *
* @param source The {@code InputSource} of the document to evaluate over. * @param source The {@code InputSource} of the document to evaluate over.
* @param returnType The desired return type. * @param returnType The desired return type.
@ -182,16 +183,17 @@ public interface XPathExpression {
throws XPathExpressionException; throws XPathExpressionException;
/** /**
* <p>Evaluate the compiled XPath expression in the context of the specified {@code InputSource} and return the result as a * Evaluate the compiled XPath expression in the context
* {@code String}.</p> * of the specified {@code InputSource} and return the result as a
* {@code String}.
* *
* <p>This method calls {@link #evaluate(InputSource source, QName returnType)} with a {@code returnType} of * <p>This method calls {@link #evaluate(InputSource source, QName returnType)} with a {@code returnType} of
* {@link XPathConstants#STRING}.</p> * {@link XPathConstants#STRING}.
* *
* <p>See <a href="#XPathExpression-evaluation">Evaluation of XPath Expressions</a> for context item evaluation, * <p>See <a href="#XPathExpression-evaluation">Evaluation of XPath Expressions</a> for context item evaluation,
* variable, function and QName resolution and return type conversion.</p> * variable, function and QName resolution and return type conversion.
* *
* <p>If {@code source} is {@code null}, then a {@code NullPointerException} is thrown.</p> * <p>If {@code source} is {@code null}, then a {@code NullPointerException} is thrown.
* *
* @param source The {@code InputSource} of the document to evaluate over. * @param source The {@code InputSource} of the document to evaluate over.
* *
@ -351,7 +353,6 @@ public interface XPathExpression {
* <pre> {@code * <pre> {@code
* evaluateExpression(source, XPathEvaluationResult.class); * evaluateExpression(source, XPathEvaluationResult.class);
* }</pre> * }</pre>
* <p>
* *
* @implSpec * @implSpec
* The default implementation in the XPath API is equivalent to: * The default implementation in the XPath API is equivalent to:

28
jaxp/src/java.xml/share/classes/javax/xml/xpath/XPathExpressionException.java
View file

@ -26,7 +26,7 @@
package javax.xml.xpath; package javax.xml.xpath;
/** /**
* <code>XPathExpressionException</code> represents an error in an XPath expression.</p> * {@code XPathExpressionException} represents an error in an XPath expression.
* *
* @author <a href="mailto:Norman.Walsh@Sun.com">Norman Walsh</a> * @author <a href="mailto:Norman.Walsh@Sun.com">Norman Walsh</a>
* @author <a href="mailto:Jeff.Suttor@Sun.com">Jeff Suttor</a> * @author <a href="mailto:Jeff.Suttor@Sun.com">Jeff Suttor</a>
@ -35,38 +35,38 @@ package javax.xml.xpath;
public class XPathExpressionException extends XPathException { public class XPathExpressionException extends XPathException {
/** /**
* <p>Stream Unique Identifier.</p> * Stream Unique Identifier.
*/ */
private static final long serialVersionUID = -1837080260374986980L; private static final long serialVersionUID = -1837080260374986980L;
/** /**
* <p>Constructs a new <code>XPathExpressionException</code> * Constructs a new {@code XPathExpressionException}
* with the specified detail <code>message</code>.</p> * with the specified detail {@code message}.
* *
* <p>The <code>cause</code> is not initialized.</p> * <p>The {@code cause} is not initialized.
* *
* <p>If <code>message</code> is <code>null</code>, * <p>If {@code message} is {@code null},
* then a <code>NullPointerException</code> is thrown.</p> * then a {@code NullPointerException} is thrown.
* *
* @param message The detail message. * @param message The detail message.
* *
* @throws NullPointerException When <code>message</code> is * @throws NullPointerException When {@code message} is
* <code>null</code>. * {@code null}.
*/ */
public XPathExpressionException(String message) { public XPathExpressionException(String message) {
super(message); super(message);
} }
/** /**
* <p>Constructs a new <code>XPathExpressionException</code> * Constructs a new {@code XPathExpressionException}
* with the specified <code>cause</code>.</p> * with the specified {@code cause}.
* *
* <p>If <code>cause</code> is <code>null</code>, * <p>If {@code cause} is {@code null},
* then a <code>NullPointerException</code> is thrown.</p> * then a {@code NullPointerException} is thrown.
* *
* @param cause The cause. * @param cause The cause.
* *
* @throws NullPointerException if <code>cause</code> is <code>null</code>. * @throws NullPointerException if {@code cause} is {@code null}.
*/ */
public XPathExpressionException(Throwable cause) { public XPathExpressionException(Throwable cause) {
super(cause); super(cause);

28
jaxp/src/java.xml/share/classes/javax/xml/xpath/XPathFactoryConfigurationException.java
View file

@ -26,7 +26,8 @@
package javax.xml.xpath; package javax.xml.xpath;
/** /**
* <code>XPathFactoryConfigurationException</code> represents a configuration error in a <code>XPathFactory</code> environment.</p> * {@code XPathFactoryConfigurationException} represents
* a configuration error in a {@code XPathFactory} environment.
* *
* @author <a href="mailto:Norman.Walsh@Sun.com">Norman Walsh</a> * @author <a href="mailto:Norman.Walsh@Sun.com">Norman Walsh</a>
* @author <a href="mailto:Jeff.Suttor@Sun.com">Jeff Suttor</a> * @author <a href="mailto:Jeff.Suttor@Sun.com">Jeff Suttor</a>
@ -35,37 +36,38 @@ package javax.xml.xpath;
public class XPathFactoryConfigurationException extends XPathException { public class XPathFactoryConfigurationException extends XPathException {
/** /**
* <p>Stream Unique Identifier.</p> * Stream Unique Identifier.
*/ */
private static final long serialVersionUID = -1837080260374986980L; private static final long serialVersionUID = -1837080260374986980L;
/** /**
* <p>Constructs a new <code>XPathFactoryConfigurationException</code> with the specified detail <code>message</code>.</p> * Constructs a new {@code XPathFactoryConfigurationException}
* with the specified detail {@code message}.
* *
* <p>The <code>cause</code> is not initialized.</p> * <p>The {@code cause} is not initialized.
* *
* <p>If <code>message</code> is <code>null</code>, * <p>If {@code message} is {@code null},
* then a <code>NullPointerException</code> is thrown.</p> * then a {@code NullPointerException} is thrown.
* *
* @param message The detail message. * @param message The detail message.
* *
* @throws NullPointerException When <code>message</code> is * @throws NullPointerException When {@code message} is
* <code>null</code>. * {@code null}.
*/ */
public XPathFactoryConfigurationException(String message) { public XPathFactoryConfigurationException(String message) {
super(message); super(message);
} }
/** /**
* <p>Constructs a new <code>XPathFactoryConfigurationException</code> * Constructs a new {@code XPathFactoryConfigurationException}
* with the specified <code>cause</code>.</p> * with the specified {@code cause}.
* *
* <p>If <code>cause</code> is <code>null</code>, * <p>If {@code cause} is {@code null},
* then a <code>NullPointerException</code> is thrown.</p> * then a {@code NullPointerException} is thrown.
* *
* @param cause The cause. * @param cause The cause.
* *
* @throws NullPointerException if <code>cause</code> is <code>null</code>. * @throws NullPointerException if {@code cause} is {@code null}.
*/ */
public XPathFactoryConfigurationException(Throwable cause) { public XPathFactoryConfigurationException(Throwable cause) {
super(cause); super(cause);

24
jaxp/src/java.xml/share/classes/javax/xml/xpath/XPathFunctionException.java
View file

@ -26,7 +26,7 @@
package javax.xml.xpath; package javax.xml.xpath;
/** /**
* <code>XPathFunctionException</code> represents an error with an XPath function.</p> * {@code XPathFunctionException} represents an error with an XPath function.
* *
* @author <a href="mailto:Norman.Walsh@Sun.com">Norman Walsh</a> * @author <a href="mailto:Norman.Walsh@Sun.com">Norman Walsh</a>
* @author <a href="mailto:Jeff.Suttor@Sun.com">Jeff Suttor</a> * @author <a href="mailto:Jeff.Suttor@Sun.com">Jeff Suttor</a>
@ -35,36 +35,36 @@ package javax.xml.xpath;
public class XPathFunctionException extends XPathExpressionException { public class XPathFunctionException extends XPathExpressionException {
/** /**
* <p>Stream Unique Identifier.</p> * Stream Unique Identifier.
*/ */
private static final long serialVersionUID = -1837080260374986980L; private static final long serialVersionUID = -1837080260374986980L;
/** /**
* <p>Constructs a new <code>XPathFunctionException</code> with the specified detail <code>message</code>.</p> * Constructs a new {@code XPathFunctionException} with the specified detail {@code message}.
* *
* <p>The <code>cause</code> is not initialized.</p> * <p>The {@code cause} is not initialized.
* *
* <p>If <code>message</code> is <code>null</code>, * <p>If {@code message} is {@code null},
* then a <code>NullPointerException</code> is thrown.</p> * then a {@code NullPointerException} is thrown.
* *
* @param message The detail message. * @param message The detail message.
* *
* @throws NullPointerException When <code>message</code> is * @throws NullPointerException When {@code message} is
* <code>null</code>. * {@code null}.
*/ */
public XPathFunctionException(String message) { public XPathFunctionException(String message) {
super(message); super(message);
} }
/** /**
* <p>Constructs a new <code>XPathFunctionException</code> with the specified <code>cause</code>.</p> * Constructs a new {@code XPathFunctionException} with the specified {@code cause}.
* *
* <p>If <code>cause</code> is <code>null</code>, * <p>If {@code cause} is {@code null},
* then a <code>NullPointerException</code> is thrown.</p> * then a {@code NullPointerException} is thrown.
* *
* @param cause The cause. * @param cause The cause.
* *
* @throws NullPointerException if <code>cause</code> is <code>null</code>. * @throws NullPointerException if {@code cause} is {@code null}.
*/ */
public XPathFunctionException(Throwable cause) { public XPathFunctionException(Throwable cause) {
super(cause); super(cause);

2
jaxp/src/java.xml/share/classes/javax/xml/xpath/package.html
View file

@ -282,7 +282,6 @@ It is an XML document tree represented as a hierarchy of nodes, a
<h3>5. Using the XPath API</h3> <h3>5. Using the XPath API</h3>
Consider the following XML document: Consider the following XML document:
<p>
<blockquote> <blockquote>
<pre> <pre>
&lt;widgets&gt; &lt;widgets&gt;
@ -366,7 +365,6 @@ The XPath 1.0 Number data type is defined as a double. However, the XPath
specification also provides functions that returns Integer type. To facilitate specification also provides functions that returns Integer type. To facilitate
such operations, the XPath API allows Integer and Long to be used in such operations, the XPath API allows Integer and Long to be used in
{@code evaluateExpression} method such as the following code: {@code evaluateExpression} method such as the following code:
<p>
<blockquote> <blockquote>
<pre> <pre>
int count = xpath.evaluate("count(/widgets/widget)", document, Integer.class); int count = xpath.evaluate("count(/widgets/widget)", document, Integer.class);

40
jaxp/src/java.xml/share/classes/org/w3c/dom/ranges/package.html
View file

@ -21,11 +21,11 @@
W3C IPR SOFTWARE NOTICE W3C IPR SOFTWARE NOTICE
</h1> </h1>
<h3> <h3>
Copyright &copy; 2000 <loc href="http://www.w3.org/">World Wide Web Copyright &copy; 2000 <a href="http://www.w3.org/">World Wide Web
Consortium</loc>, (<loc href="http://www.lcs.mit.edu/">Massachusetts Consortium</a>, (<a href="http://www.lcs.mit.edu/">Massachusetts
Institute of Technology</loc>, <loc href="http://www.inria.fr/">Institut Institute of Technology</a>, <a href="http://www.inria.fr/">Institut
National de Recherche en Informatique et en Automatique</loc>, <loc National de Recherche en Informatique et en Automatique</a>, <a
href="http://www.keio.ac.jp/">Keio University</loc>). All Rights href="http://www.keio.ac.jp/">Keio University</a>). All Rights
Reserved. Reserved.
</h3> </h3>
<p> <p>
@ -66,25 +66,25 @@
</p> </p>
<ol> <ol>
<li> <li>
The full text of this NOTICE in a location viewable to users of the The full text of this NOTICE in a location viewable to users of the
redistributed or derivative work. redistributed or derivative work.
</li> </li>
<li> <li>
Any pre-existing intellectual property disclaimers, notices, or terms Any pre-existing intellectual property disclaimers, notices, or terms
and conditions. If none exist, a short notice of the following form and conditions. If none exist, a short notice of the following form
(hypertext is preferred, text is permitted) should be used within the (hypertext is preferred, text is permitted) should be used within the
body of any redistributed or derivative code: "Copyright &copy; body of any redistributed or derivative code: "Copyright &copy;
[$date-of-software] <a href="http://www.w3.org/">World Wide Web [$date-of-software] <a href="http://www.w3.org/">World Wide Web
Consortium</a>, (<a href="http://www.lcs.mit.edu/">Massachusetts Consortium</a>, (<a href="http://www.lcs.mit.edu/">Massachusetts
Institute of Technology</a>, <a href="http://www.inria.fr/">Institut Institute of Technology</a>, <a href="http://www.inria.fr/">Institut
National de Recherche en Informatique et en Automatique</a>, <a National de Recherche en Informatique et en Automatique</a>, <a
href="http://www.keio.ac.jp/">Keio University</a>). All Rights href="http://www.keio.ac.jp/">Keio University</a>). All Rights
Reserved. http://www.w3.org/Consortium/Legal/" Reserved. http://www.w3.org/Consortium/Legal/"
</li> </li>
<li> <li>
Notice of any changes or modifications to the W3C files, including the Notice of any changes or modifications to the W3C files, including the
date changes were made. (We recommend you provide URIs to the location date changes were made. (We recommend you provide URIs to the location
from which the code is derived.) from which the code is derived.)
</li> </li>
</ol> </ol>
<p> <p>

36
jaxp/src/java.xml/share/classes/org/xml/sax/AttributeList.java
View file

@ -42,7 +42,7 @@ package org.xml.sax;
* *
* <p>This is the original SAX1 interface for reporting an element's * <p>This is the original SAX1 interface for reporting an element's
* attributes. Unlike the new {@link org.xml.sax.Attributes Attributes} * attributes. Unlike the new {@link org.xml.sax.Attributes Attributes}
* interface, it does not support Namespace-related information.</p> * interface, it does not support Namespace-related information.
* *
* <p>When an attribute list is supplied as part of a * <p>When an attribute list is supplied as part of a
* {@link org.xml.sax.DocumentHandler#startElement startElement} * {@link org.xml.sax.DocumentHandler#startElement startElement}
@ -51,16 +51,16 @@ package org.xml.sax;
* to the parser, the attribute list is invalid. To save a * to the parser, the attribute list is invalid. To save a
* persistent copy of the attribute list, use the SAX1 * persistent copy of the attribute list, use the SAX1
* {@link org.xml.sax.helpers.AttributeListImpl AttributeListImpl} * {@link org.xml.sax.helpers.AttributeListImpl AttributeListImpl}
* helper class.</p> * helper class.
* *
* <p>An attribute list includes only attributes that have been * <p>An attribute list includes only attributes that have been
* specified or defaulted: #IMPLIED attributes will not be included.</p> * specified or defaulted: #IMPLIED attributes will not be included.
* *
* <p>There are two ways for the SAX application to obtain information * <p>There are two ways for the SAX application to obtain information
* from the AttributeList. First, it can iterate through the entire * from the AttributeList. First, it can iterate through the entire
* list:</p> * list:
* *
* <pre> * <pre>{@code
* public void startElement (String name, AttributeList atts) { * public void startElement (String name, AttributeList atts) {
* for (int i = 0; i < atts.getLength(); i++) { * for (int i = 0; i < atts.getLength(); i++) {
* String name = atts.getName(i); * String name = atts.getName(i);
@ -69,13 +69,13 @@ package org.xml.sax;
* [...] * [...]
* } * }
* } * }
* </pre> * }</pre>
* *
* <p>(Note that the result of getLength() will be zero if there * <p>(Note that the result of getLength() will be zero if there
* are no attributes.) * are no attributes.)
* *
* <p>As an alternative, the application can request the value or * <p>As an alternative, the application can request the value or
* type of specific attributes:</p> * type of specific attributes:
* *
* <pre> * <pre>
* public void startElement (String name, AttributeList atts) { * public void startElement (String name, AttributeList atts) {
@ -107,7 +107,7 @@ public interface AttributeList {
* <p>The SAX parser may provide attributes in any * <p>The SAX parser may provide attributes in any
* arbitrary order, regardless of the order in which they were * arbitrary order, regardless of the order in which they were
* declared or specified. The number of attributes may be * declared or specified. The number of attributes may be
* zero.</p> * zero.
* *
* @return The number of attributes in the list. * @return The number of attributes in the list.
*/ */
@ -120,10 +120,10 @@ public interface AttributeList {
* <p>The names must be unique: the SAX parser shall not include the * <p>The names must be unique: the SAX parser shall not include the
* same attribute twice. Attributes without values (those declared * same attribute twice. Attributes without values (those declared
* #IMPLIED without a value specified in the start tag) will be * #IMPLIED without a value specified in the start tag) will be
* omitted from the list.</p> * omitted from the list.
* *
* <p>If the attribute name has a namespace prefix, the prefix * <p>If the attribute name has a namespace prefix, the prefix
* will still be attached.</p> * will still be attached.
* *
* @param i The index of the attribute in the list (starting at 0). * @param i The index of the attribute in the list (starting at 0).
* @return The name of the indexed attribute, or null * @return The name of the indexed attribute, or null
@ -138,15 +138,15 @@ public interface AttributeList {
* *
* <p>The attribute type is one of the strings "CDATA", "ID", * <p>The attribute type is one of the strings "CDATA", "ID",
* "IDREF", "IDREFS", "NMTOKEN", "NMTOKENS", "ENTITY", "ENTITIES", * "IDREF", "IDREFS", "NMTOKEN", "NMTOKENS", "ENTITY", "ENTITIES",
* or "NOTATION" (always in upper case).</p> * or "NOTATION" (always in upper case).
* *
* <p>If the parser has not read a declaration for the attribute, * <p>If the parser has not read a declaration for the attribute,
* or if the parser does not report attribute types, then it must * or if the parser does not report attribute types, then it must
* return the value "CDATA" as stated in the XML 1.0 Recommentation * return the value "CDATA" as stated in the XML 1.0 Recommentation
* (clause 3.3.3, "Attribute-Value Normalization").</p> * (clause 3.3.3, "Attribute-Value Normalization").
* *
* <p>For an enumerated attribute that is not a notation, the * <p>For an enumerated attribute that is not a notation, the
* parser will report the type as "NMTOKEN".</p> * parser will report the type as "NMTOKEN".
* *
* @param i The index of the attribute in the list (starting at 0). * @param i The index of the attribute in the list (starting at 0).
* @return The attribute type as a string, or * @return The attribute type as a string, or
@ -162,7 +162,7 @@ public interface AttributeList {
* *
* <p>If the attribute value is a list of tokens (IDREFS, * <p>If the attribute value is a list of tokens (IDREFS,
* ENTITIES, or NMTOKENS), the tokens will be concatenated * ENTITIES, or NMTOKENS), the tokens will be concatenated
* into a single string separated by whitespace.</p> * into a single string separated by whitespace.
* *
* @param i The index of the attribute in the list (starting at 0). * @param i The index of the attribute in the list (starting at 0).
* @return The attribute value as a string, or * @return The attribute value as a string, or
@ -183,10 +183,10 @@ public interface AttributeList {
* Return the type of an attribute in the list (by name). * Return the type of an attribute in the list (by name).
* *
* <p>The return value is the same as the return value for * <p>The return value is the same as the return value for
* getType(int).</p> * getType(int).
* *
* <p>If the attribute name has a namespace prefix in the document, * <p>If the attribute name has a namespace prefix in the document,
* the application must include the prefix here.</p> * the application must include the prefix here.
* *
* @param name The name of the attribute. * @param name The name of the attribute.
* @return The attribute type as a string, or null if no * @return The attribute type as a string, or null if no
@ -200,10 +200,10 @@ public interface AttributeList {
* Return the value of an attribute in the list (by name). * Return the value of an attribute in the list (by name).
* *
* <p>The return value is the same as the return value for * <p>The return value is the same as the return value for
* getValue(int).</p> * getValue(int).
* *
* <p>If the attribute name has a namespace prefix in the document, * <p>If the attribute name has a namespace prefix in the document,
* the application must include the prefix here.</p> * the application must include the prefix here.
* *
* @param name the name of the attribute to return * @param name the name of the attribute to return
* @return The attribute value as a string, or null if * @return The attribute value as a string, or null if

25
jaxp/src/java.xml/share/classes/org/xml/sax/ext/EntityResolver2.java
View file

@ -61,7 +61,6 @@ import org.xml.sax.SAXException;
* recognized). If that flag is unrecognized, or its value is false, * recognized). If that flag is unrecognized, or its value is false,
* or the resolver does not implement this interface, then only the * or the resolver does not implement this interface, then only the
* {@link EntityResolver} method will be used. * {@link EntityResolver} method will be used.
* </p>
* *
* <p>That supports three categories of application that modify entity * <p>That supports three categories of application that modify entity
* resolution. <em>Old Style</em> applications won't know about this interface; * resolution. <em>Old Style</em> applications won't know about this interface;
@ -76,7 +75,6 @@ import org.xml.sax.SAXException;
* They will insist that feature flag have a value of "true", and the * They will insist that feature flag have a value of "true", and the
* EntityResolver2 implementation they provide might throw an exception * EntityResolver2 implementation they provide might throw an exception
* if the original SAX 1.0 style entity resolution method is invoked. * if the original SAX 1.0 style entity resolution method is invoked.
* </p>
* *
* @see org.xml.sax.XMLReader#setEntityResolver * @see org.xml.sax.XMLReader#setEntityResolver
* *
@ -95,7 +93,7 @@ public interface EntityResolver2 extends EntityResolver
* through the {@link LexicalHandler#startDTD startDTD()} method as if * through the {@link LexicalHandler#startDTD startDTD()} method as if
* the document text had originally included the external subset; * the document text had originally included the external subset;
* this callback is made before any internal subset data or errors * this callback is made before any internal subset data or errors
* are reported.</p> * are reported.
* *
* <p>This method can also be used with documents that have no DOCTYPE * <p>This method can also be used with documents that have no DOCTYPE
* declaration. When the root element is encountered, * declaration. When the root element is encountered,
@ -104,7 +102,7 @@ public interface EntityResolver2 extends EntityResolver
* element is declared to be the root element, giving the effect of * element is declared to be the root element, giving the effect of
* splicing a DOCTYPE declaration at the end the prolog of a document * splicing a DOCTYPE declaration at the end the prolog of a document
* that could not otherwise be valid. The sequence of parser callbacks * that could not otherwise be valid. The sequence of parser callbacks
* in that case logically resembles this:</p> * in that case logically resembles this:
* *
* <pre> * <pre>
* ... comments and PIs from the prolog (as usual) * ... comments and PIs from the prolog (as usual)
@ -122,7 +120,7 @@ public interface EntityResolver2 extends EntityResolver
* {@link #resolveEntity resolveEntity()} to gain benefits such as use * {@link #resolveEntity resolveEntity()} to gain benefits such as use
* of local caches of DTD entities. Also, this method will never be * of local caches of DTD entities. Also, this method will never be
* used by a (non-validating) processor that is not including external * used by a (non-validating) processor that is not including external
* parameter entities. </p> * parameter entities.
* *
* <p>Uses for this method include facilitating data validation when * <p>Uses for this method include facilitating data validation when
* interoperating with XML processors that would always require * interoperating with XML processors that would always require
@ -131,12 +129,11 @@ public interface EntityResolver2 extends EntityResolver
* Non-validation motives include forcing documents to include DTDs so * Non-validation motives include forcing documents to include DTDs so
* that attributes are handled consistently. * that attributes are handled consistently.
* For example, an XPath processor needs to know which attibutes have * For example, an XPath processor needs to know which attibutes have
* type "ID" before it can process a widely used type of reference.</p> * type "ID" before it can process a widely used type of reference.
* *
* <p><strong>Warning:</strong> Returning an external subset modifies * <p><strong>Warning:</strong> Returning an external subset modifies
* the input document. By providing definitions for general entities, * the input document. By providing definitions for general entities,
* it can make a malformed document appear to be well formed. * it can make a malformed document appear to be well formed.
* </p>
* *
* @param name Identifies the document root element. This name comes * @param name Identifies the document root element. This name comes
* from a DOCTYPE declaration (where available) or from the actual * from a DOCTYPE declaration (where available) or from the actual
@ -166,8 +163,8 @@ public interface EntityResolver2 extends EntityResolver
* This method provides more flexibility than the {@link EntityResolver} * This method provides more flexibility than the {@link EntityResolver}
* interface, supporting implementations of more complex catalogue * interface, supporting implementations of more complex catalogue
* schemes such as the one defined by the <a href= * schemes such as the one defined by the <a href=
"http://www.oasis-open.org/committees/entity/spec-2001-08-06.html" * "http://www.oasis-open.org/committees/entity/spec-2001-08-06.html"
>OASIS XML Catalogs</a> specification.</p> * >OASIS XML Catalogs</a> specification.
* *
* <p>Parsers configured to use this resolver method will call it * <p>Parsers configured to use this resolver method will call it
* to determine the input source to use for any external entity * to determine the input source to use for any external entity
@ -176,13 +173,13 @@ public interface EntityResolver2 extends EntityResolver
* by {@link #getExternalSubset getExternalSubset()}. * by {@link #getExternalSubset getExternalSubset()}.
* When a (non-validating) processor is configured not to include * When a (non-validating) processor is configured not to include
* a class of entities (parameter or general) through use of feature * a class of entities (parameter or general) through use of feature
* flags, this method is not invoked for such entities. </p> * flags, this method is not invoked for such entities.
* *
* <p>Note that the entity naming scheme used here is the same one * <p>Note that the entity naming scheme used here is the same one
* used in the {@link LexicalHandler}, or in the {@link * used in the {@link LexicalHandler}, or in the {@link
org.xml.sax.ContentHandler#skippedEntity * org.xml.sax.ContentHandler#skippedEntity
ContentHandler.skippedEntity()} * ContentHandler.skippedEntity()}
* method. </p> * method.
* *
* @param name Identifies the external entity being resolved. * @param name Identifies the external entity being resolved.
* Either "[dtd]" for the external subset, or a name starting * Either "[dtd]" for the external subset, or a name starting
@ -196,7 +193,7 @@ public interface EntityResolver2 extends EntityResolver
* are interpreted. This is always an absolute URI, unless it is * are interpreted. This is always an absolute URI, unless it is
* null (likely because the XMLReader was given an InputSource without * null (likely because the XMLReader was given an InputSource without
* one). This URI is defined by the XML specification to be the one * one). This URI is defined by the XML specification to be the one
* associated with the "&lt;" starting the relevant declaration. * associated with the "{@literal <}" starting the relevant declaration.
* @param systemId The system identifier of the external entity * @param systemId The system identifier of the external entity
* being referenced; either a relative or absolute URI. * being referenced; either a relative or absolute URI.
* This is never null when invoked by a SAX2 parser; only declared * This is never null when invoked by a SAX2 parser; only declared

23
jaxp/src/java.xml/share/classes/org/xml/sax/helpers/XMLReaderFactory.java
View file

@ -49,7 +49,7 @@ import org.xml.sax.SAXException;
* </blockquote> * </blockquote>
* *
* <p>This class contains static methods for creating an XML reader * <p>This class contains static methods for creating an XML reader
* from an explicit class name, or based on runtime defaults:</p> * from an explicit class name, or based on runtime defaults:
* *
* <pre> * <pre>
* try { * try {
@ -64,8 +64,8 @@ import org.xml.sax.SAXException;
* <em>createXMLReader</em> to handle cases where the external * <em>createXMLReader</em> to handle cases where the external
* configuration mechanisms aren't set up. That method should do its * configuration mechanisms aren't set up. That method should do its
* best to return a parser when one is in the class path, even when * best to return a parser when one is in the class path, even when
* nothing bound its class name to <code>org.xml.sax.driver</code> so * nothing bound its class name to {@code org.xml.sax.driver} so
* those configuration mechanisms would see it.</p> * those configuration mechanisms would see it.
* *
* @since 1.4, SAX 2.0 * @since 1.4, SAX 2.0
* @author David Megginson, David Brownell * @author David Megginson, David Brownell
@ -76,7 +76,7 @@ final public class XMLReaderFactory
/** /**
* Private constructor. * Private constructor.
* *
* <p>This constructor prevents the class from being instantiated.</p> * <p>This constructor prevents the class from being instantiated.
*/ */
private XMLReaderFactory () private XMLReaderFactory ()
{ {
@ -91,9 +91,10 @@ final public class XMLReaderFactory
* Attempt to create an XMLReader from system defaults. * Attempt to create an XMLReader from system defaults.
* In environments which can support it, the name of the XMLReader * In environments which can support it, the name of the XMLReader
* class is determined by trying each these options in order, and * class is determined by trying each these options in order, and
* using the first one which succeeds:</p> <ul> * using the first one which succeeds:
* <ul>
* *
* <li>If the system property <code>org.xml.sax.driver</code> * <li>If the system property {@code org.xml.sax.driver}
* has a value, that is used as an XMLReader class name. </li> * has a value, that is used as an XMLReader class name. </li>
* *
* <li>The JAR "Services API" is used to look for a class name * <li>The JAR "Services API" is used to look for a class name
@ -107,14 +108,13 @@ final public class XMLReaderFactory
* <li>Finally, if {@link ParserFactory#makeParser()} can * <li>Finally, if {@link ParserFactory#makeParser()} can
* return a system default SAX1 parser, that parser is wrapped in * return a system default SAX1 parser, that parser is wrapped in
* a {@link ParserAdapter}. (This is a migration aid for SAX1 * a {@link ParserAdapter}. (This is a migration aid for SAX1
* environments, where the <code>org.xml.sax.parser</code> system * environments, where the {@code org.xml.sax.parser} system
* property will often be usable.) </li> * property will often be usable.) </li>
*
* </ul> * </ul>
* *
* <p> In environments such as small embedded systems, which can not * <p> In environments such as small embedded systems, which can not
* support that flexibility, other mechanisms to determine the default * support that flexibility, other mechanisms to determine the default
* may be used. </p> * may be used.
* *
* <p>Note that many Java environments allow system properties to be * <p>Note that many Java environments allow system properties to be
* initialized on a command line. This means that <em>in most cases</em> * initialized on a command line. This means that <em>in most cases</em>
@ -122,7 +122,6 @@ final public class XMLReaderFactory
* method will succeed, except when security policies intervene. * method will succeed, except when security policies intervene.
* This will also maximize application portability to older SAX * This will also maximize application portability to older SAX
* environments, with less robust implementations of this method. * environments, with less robust implementations of this method.
* </p>
* *
* @return A new XMLReader. * @return A new XMLReader.
* @exception org.xml.sax.SAXException If no default XMLReader class * @exception org.xml.sax.SAXException If no default XMLReader class
@ -204,11 +203,11 @@ final public class XMLReaderFactory
* Attempt to create an XML reader from a class name. * Attempt to create an XML reader from a class name.
* *
* <p>Given a class name, this method attempts to load * <p>Given a class name, this method attempts to load
* and instantiate the class as an XML reader.</p> * and instantiate the class as an XML reader.
* *
* <p>Note that this method will not be usable in environments where * <p>Note that this method will not be usable in environments where
* the caller (perhaps an applet) is not permitted to load classes * the caller (perhaps an applet) is not permitted to load classes
* dynamically.</p> * dynamically.
* *
* @return A new XML reader. * @return A new XML reader.
* @exception org.xml.sax.SAXException If the class cannot be * @exception org.xml.sax.SAXException If the class cannot be