archive/jdk
1
0
Fork 0
mirror of https://github.com/openjdk/jdk.git synced 2025-09-20 11:04:34 +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;
/**
* <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>
* @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 {
/**
* <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">
* Namespaces in XML, 5.2 Namespace Defaulting</a>
@ -58,9 +58,9 @@ public final class XMLConstants {
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
* 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 = "";
/**
* <p>The official XML Namespace name URI.</p>
* The official XML Namespace name URI.
*
* <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
* 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";
/**
* <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
* 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";
/**
* <p>The official XML attribute used for specifying XML Namespace
* The official XML attribute used for specifying XML Namespace
* 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
* "{@code http://www.w3.org/2000/xmlns/}".</p>
* "{@code http://www.w3.org/2000/xmlns/}".
*
* @see <a
* 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/";
/**
* <p>The official XML attribute used for specifying XML Namespace
* declarations.</p>
* The official XML attribute used for specifying XML Namespace
* declarations.
*
* <p>It is <strong><em>NOT</em></strong> valid to use as a
* prefix. Defined by the XML specification to be
* "{@code xmlns}".</p>
* "{@code xmlns}".
*
* @see <a
* 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";
/**
* <p>W3C XML Schema Namespace URI.</p>
* W3C XML Schema Namespace URI.
*
* <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";
/**
* <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=
* "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 =
"http://www.w3.org/2001/XMLSchema-instance";
/**
* <p>W3C XPath Datatype Namespace URI.</p>
*
* <p>Defined to be "{@code http://www.w3.org/2003/11/xpath-datatypes}".</p>
*
* @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";
/**
* W3C XPath Datatype Namespace URI.
*
* <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>
*/
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}".
*/
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>
*/
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>
* <li>
@ -193,14 +193,13 @@ public final class XMLConstants {
/**
* <p>Property: accessExternalDTD</p>
* Property: accessExternalDTD
*
* <p>
* 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
* 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.
* </p>
*
* <p>
* <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.
*
* </blockquote>
*</p>
*
*<p>
* <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>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>
*</UL><br>
* </UL><br>
* When FEATURE_SECURE_PROCESSING is enabled, it is recommended that implementations
* restrict external connections by default, though this may cause problems for applications
* that process XML/XSD/XSL with external references.
* </blockquote>
* </p>
*
* <p>
* <b>Granting all access:</b> the keyword "all" grants permission to all protocols.
* </p>
*
* <p>
* <b>System Property:</b> The value of this property can be set or overridden by
* system property {@code javax.xml.accessExternalDTD}.
* </p>
*
*
* <p>
* <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
* property is specified, its value will be used to override the default
* of the property.
* </p>
*
* <p>
*
* </p>
* @since 1.7
*/
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
* to the context is thrown. In the case of {@link javax.xml.validation.SchemaFactory}
* for example, org.xml.sax.SAXException is thrown.
* </p>
*
* <p>
* <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
@ -290,9 +284,8 @@ public final class XMLConstants {
* Examples of protocols are file, http, jar:file.
*
* </blockquote>
*</p>
*
*<p>
* <p>
* <b>Default value:</b> The default value is implementation specific and therefore not specified.
* The following options are provided for consideration:
* <blockquote>
@ -300,20 +293,18 @@ public final class XMLConstants {
* <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>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
* restrict external connections by default, though this may cause problems for applications
* that process XML/XSD/XSL with external references.
* </blockquote>
* </p>
*
* <p>
* <b>Granting all access:</b> the keyword "all" grants permission to all protocols.
* </p>
*
* <p>
* <b>System Property:</b> The value of this property can be set or overridden by
* system property {@code javax.xml.accessExternalSchema}
* </p>
*
* <p>
* <b>jaxp.properties:</b> This configuration file is in standard
@ -323,12 +314,11 @@ public final class XMLConstants {
* of the property.
*
* @since 1.7
* </p>
*/
public static final String ACCESS_EXTERNAL_SCHEMA = "http://javax.xml.XMLConstants/property/accessExternalSchema";
/**
* <p>Property: accessExternalStylesheet</p>
* Property: accessExternalStylesheet
*
* <p>
* 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.TransformerConfigurationException}
* will be thrown by the {@link javax.xml.transform.TransformerFactory}.
* </p>
*
* <p>
* <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
@ -358,9 +348,8 @@ public final class XMLConstants {
* Examples of protocols are file, http, jar:file.
*
* </blockquote>
*</p>
*
*<p>
* <p>
* <b>Default value:</b> The default value is implementation specific and therefore not specified.
* The following options are provided for consideration:
* <blockquote>
@ -368,20 +357,18 @@ public final class XMLConstants {
* <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>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
* restrict external connections by default, though this may cause problems for applications
* that process XML/XSD/XSL with external references.
* </blockquote>
* </p>
*
* <p>
* <b>Granting all access:</b> the keyword "all" grants permission to all protocols.
* </p>
*
* <p>
* <b>System Property:</b> The value of this property can be set or overridden by
* system property {@code javax.xml.accessExternalStylesheet}
* </p>
*
* <p>
* <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;
/**
* 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>
* 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:
* <p>
* <ol>
* <li>
* 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 {
/**
* <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 =
// We use a String constant here, rather than calling
@ -100,16 +99,15 @@ public abstract class DatatypeFactory {
"javax.xml.datatype.DatatypeFactory";
/**
* <p>Default implementation class name as defined in
* <em>JSR 206: Java(TM) API for XML Processing (JAXP) 1.3</em>.</p>
* Default implementation class name as defined in
* <em>JSR 206: Java(TM) API for XML Processing (JAXP) 1.3</em>.
*
* <p>Implementers should specify the name of an appropriate class
* 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
* document a factory implementation detail.
* </p>
*/
public static final String DATATYPEFACTORY_IMPLEMENTATION_CLASS =
// We use new String() here to prevent javadoc from generating
@ -130,18 +128,18 @@ public abstract class DatatypeFactory {
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() {
}
/**
* <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
* <code>Class</code>'s documentation.</p>
* {@code Class}'s documentation.
*
* @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.
* 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}
* 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>
* <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
* 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>
* java -Djaxp.debug=1 YourProgram ....
* </pre>
*
* @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>
* current <code>Thread</code>'s context classLoader is used to load the factory class.
* @param classLoader {@code ClassLoader} used to load the factory class. If {@code null}
* current {@code Thread}'s context classLoader is used to load the factory class.
*
* @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.
*
* @see #newInstance()
@ -201,11 +199,11 @@ public abstract class DatatypeFactory {
}
/**
* <p>Obtain a new instance of a <code>Duration</code>
* specifying the <code>Duration</code> as its string representation, "PnYnMnDTnHnMnS",
* as defined in XML Schema 1.0 section 3.2.6.1.</p>
* Obtain a new instance of a {@code Duration}
* specifying the {@code Duration} as its string representation, "PnYnMnDTnHnMnS",
* 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>
* duration represents a duration of time.
* 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
* year, month, day, hour, minute, and second.
* </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.
* 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
* 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 NullPointerException if <code>lexicalRepresentation</code> is <code>null</code>.
* @throws NullPointerException if {@code lexicalRepresentation} is {@code null}.
*/
public abstract Duration newDuration(final String lexicalRepresentation);
/**
* <p>Obtain a new instance of a <code>Duration</code>
* specifying the <code>Duration</code> as milliseconds.</p>
* Obtain a new instance of a {@code Duration}
* 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>
* duration represents a duration of time.
* 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.
* </blockquote>
* <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}.
* The values conform to and are defined by:</p>
* and are available using the {@code get} methods of the created {@link Duration}.
* The values conform to and are defined by:
* <ul>
* <li>ISO 8601:2000(E) Section 5.5.3.2 Alternative format</li>
* <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.
* 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}
* 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.
*
* @return New <code>Duration</code> representing <code>durationInMilliSeconds</code>.
* @return New {@code Duration} representing {@code durationInMilliSeconds}.
*/
public abstract Duration newDuration(final long durationInMilliSeconds);
/**
* <p>Obtain a new instance of a <code>Duration</code>
* specifying the <code>Duration</code> as isPositive, years, months, days, hours, minutes, seconds.</p>
* Obtain a new instance of a {@code Duration}
* 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.
* 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
* 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.
* @param years of this <code>Duration</code>
* @param months of this <code>Duration</code>
* @param days of this <code>Duration</code>
* @param hours of this <code>Duration</code>
* @param minutes of this <code>Duration</code>
* @param seconds of this <code>Duration</code>
* @param years of this {@code Duration}
* @param months of this {@code Duration}
* @param days of this {@code Duration}
* @param hours of this {@code Duration}
* @param minutes of this {@code Duration}
* @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
* <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.
* @throws UnsupportedOperationException If implementation cannot support requested values.
*/
@ -304,24 +302,24 @@ public abstract class DatatypeFactory {
final BigDecimal seconds);
/**
* <p>Obtain a new instance of a <code>Duration</code>
* specifying the <code>Duration</code> as isPositive, years, months, days, hours, minutes, seconds.</p>
* Obtain a new instance of a {@code Duration}
* 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.
* @param years of this <code>Duration</code>
* @param months of this <code>Duration</code>
* @param days of this <code>Duration</code>
* @param hours of this <code>Duration</code>
* @param minutes of this <code>Duration</code>
* @param seconds of this <code>Duration</code>
* @param years of this {@code Duration}
* @param months of this {@code Duration}
* @param days of this {@code Duration}
* @param hours of this {@code Duration}
* @param minutes of this {@code Duration}
* @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
* <code>Duration</code>: if any of the fields is negative.
* {@code Duration}: if any of the fields is negative.
*
* @see #newDuration(
* 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">
* 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.
* 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.
* 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
* if implementation capacities are exceeded.</p>
* if implementation capacities are exceeded.
*
* @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 NullPointerException If <code>lexicalRepresentation</code> is <code>null</code>.
* @throws NullPointerException If {@code lexicalRepresentation} is {@code null}.
*/
public Duration newDurationDayTime(final String lexicalRepresentation) {
// 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">
* 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.
* 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
* and are available using the <code>get</code> methods of the created {@link Duration}.
* The values conform to and are defined by:</p>
* and are available using the {@code get} methods of the created {@link Duration}.
* The values conform to and are defined by:
* <ul>
* <li>ISO 8601:2000(E) Section 5.5.3.2 Alternative format</li>
* <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.
* 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}
* 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">
* 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
* <code>day</code>, <code>hour</code>, <code>minute</code> and <code>second</code> as defined in
* Create a {@code Duration} of type {@code xdt:dayTimeDuration} using the specified
* {@code day}, {@code hour}, {@code minute} and {@code second} as defined in
* <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.
* 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.
* 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
* 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.
* @param day Day of <code>Duration</code>.
* @param hour Hour of <code>Duration</code>.
* @param minute Minute of <code>Duration</code>.
* @param second Second of <code>Duration</code>.
* @param day Day of {@code Duration}.
* @param hour Hour of {@code Duration}.
* @param minute Minute of {@code Duration}.
* @param second Second of {@code Duration}.
*
* @return New <code>Duration</code> created with the specified <code>day</code>, <code>hour</code>, <code>minute</code>
* and <code>second</code>.
* @return New {@code Duration} created with the specified {@code day}, {@code hour}, {@code minute}
* and {@code second}.
*
* @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.
* @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
* <code>day</code>, <code>hour</code>, <code>minute</code> and <code>second</code> as defined in
* Create a {@code Duration} of type {@code xdt:dayTimeDuration} using the specified
* {@code day}, {@code hour}, {@code minute} and {@code second} as defined in
* <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.
* 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.
* @param day Day of <code>Duration</code>.
* @param hour Hour of <code>Duration</code>.
* @param minute Minute of <code>Duration</code>.
* @param second Second of <code>Duration</code>.
* @param day Day of {@code Duration}.
* @param hour Hour of {@code Duration}.
* @param minute Minute of {@code Duration}.
* @param second Second of {@code Duration}.
*
* @return New <code>Duration</code> created with the specified <code>day</code>, <code>hour</code>, <code>minute</code>
* and <code>second</code>.
* @return New {@code Duration} created with the specified {@code day}, {@code hour}, {@code minute}
* and {@code second}.
*
* @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(
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">
* 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.
* 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.
* 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
* if implementation capacities are exceeded.</p>
* 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
* if implementation capacities are exceeded.
*
* @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 NullPointerException If <code>lexicalRepresentation</code> is <code>null</code>.
* @throws NullPointerException If {@code lexicalRepresentation} is {@code null}.
*/
public Duration newDurationYearMonth(
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">
* 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.
* 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
* and are available using the <code>get</code> methods of the created {@link Duration}.
* The values conform to and are defined by:</p>
* and are available using the {@code get} methods of the created {@link Duration}.
* The values conform to and are defined by:
* <ul>
* <li>ISO 8601:2000(E) Section 5.5.3.2 Alternative format</li>
* <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.
* 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}
* 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(
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
* <code>year</code> and <code>month</code> as defined in
* Create a {@code Duration} of type {@code xdt:yearMonthDuration} using the specified
* {@code year} and {@code month} as defined in
* <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.
* 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
* 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.
* @param year Year of <code>Duration</code>.
* @param month Month of <code>Duration</code>.
* @param year Year of {@code Duration}.
* @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
* <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.
* @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
* <code>year</code> and <code>month</code> as defined in
* Create a {@code Duration} of type {@code xdt:yearMonthDuration} using the specified
* {@code year} and {@code month} as defined in
* <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.
* @param year Year of <code>Duration</code>.
* @param month Month of <code>Duration</code>.
* @param year Year of {@code Duration}.
* @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
* <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(
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.
*/
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
* <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
* the following holds for any lexically correct String x:</p>
* the following holds for any lexically correct String x:
* <pre>
* newXMLGregorianCalendar(x).toXMLFormat().equals(x)
* </pre>
* <p>Except for the noted lexical/canonical representation mismatches
* 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.
*
* @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 NullPointerException If <code>lexicalRepresentation</code> is <code>null</code>.
* @throws IllegalArgumentException If the {@code lexicalRepresentation} is not a valid {@code XMLGregorianCalendar}.
* @throws NullPointerException If {@code lexicalRepresentation} is {@code null}.
*/
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">
* <thead>
@ -764,30 +768,30 @@ public abstract class DatatypeFactory {
* </th>
* </tr>
* <tr>
* <th><code>java.util.GregorianCalendar</code> field</th>
* <th><code>javax.xml.datatype.XMLGregorianCalendar</code> field</th>
* <th>{@code java.util.GregorianCalendar} field</th>
* <th>{@code javax.xml.datatype.XMLGregorianCalendar} field</th>
* </tr>
* </thead>
* <tbody>
* <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>
* </tr>
* <tr>
* <td><code>MONTH + 1</code></td>
* <td>{@code MONTH + 1}</td>
* <td>{@link XMLGregorianCalendar#setMonth(int month)}</td>
* </tr>
* <tr>
* <td><code>DAY_OF_MONTH</code></td>
* <td>{@code DAY_OF_MONTH}</td>
* <td>{@link XMLGregorianCalendar#setDay(int day)}</td>
* </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>
* </tr>
* <tr>
* <td>
* <code>(ZONE_OFFSET + DST_OFFSET) / (60*1000)</code><br/>
* {@code (ZONE_OFFSET + DST_OFFSET) / (60*1000)}<br>
* <em>(in minutes)</em>
* </td>
* <td>{@link XMLGregorianCalendar#setTimezone(int offset)}<sup><em>*</em></sup>
@ -796,49 +800,50 @@ public abstract class DatatypeFactory {
* </tbody>
* </table>
* <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
* XML Schema 1.0 date/time datatype representation.</p>
* a {@code java.util.GregorianCalendar} daylight savings timezone id in the
* 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>
* <li>when <code>this.getTimezone() != FIELD_UNDEFINED</code>,
* create a <code>java.util.TimeZone</code> with a custom timezone id
* using the <code>this.getTimezone()</code>.</li>
* <li>else use the <code>GregorianCalendar</code> default timezone value
* <li>when {@code this.getTimezone() != FIELD_UNDEFINED},
* create a {@code java.util.TimeZone} with a custom timezone id
* using the {@code this.getTimezone()}.</li>
* <li>else use the {@code GregorianCalendar} default timezone value
* 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);
/**
* <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
* builtin datatypes. Note that <code>year</code> parameter supports
* builtin datatypes. Note that {@code year} parameter supports
* 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 month of <code>XMLGregorianCalendar</code> to be created.
* @param day of <code>XMLGregorianCalendar</code> to be created.
* @param hour of <code>XMLGregorianCalendar</code> to be created.
* @param minute of <code>XMLGregorianCalendar</code> to be created.
* @param second of <code>XMLGregorianCalendar</code> to be created.
* @param fractionalSecond of <code>XMLGregorianCalendar</code> to be created.
* @param timezone of <code>XMLGregorianCalendar</code> to be created.
* @param year of {@code XMLGregorianCalendar} to be created.
* @param month of {@code XMLGregorianCalendar} to be created.
* @param day of {@code XMLGregorianCalendar} to be created.
* @param hour of {@code XMLGregorianCalendar} to be created.
* @param minute of {@code XMLGregorianCalendar} to be created.
* @param second of {@code XMLGregorianCalendar} to be created.
* @param fractionalSecond of {@code XMLGregorianCalendar} 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
* 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()}.
*/
public abstract XMLGregorianCalendar newXMLGregorianCalendar(
@ -852,29 +857,29 @@ public abstract class DatatypeFactory {
final int timezone);
/**
* <p>Constructor of value spaces that a
* <code>java.util.GregorianCalendar</code> instance would need to convert to an
* <code>XMLGregorianCalendar</code> instance.</p>
* Constructor of value spaces that a
* {@code java.util.GregorianCalendar} instance would need to convert to an
* {@code XMLGregorianCalendar} instance.
*
* <p><code>XMLGregorianCalendar eon</code> and
* <code>fractionalSecond</code> are set to <code>null</code></p>
* <p>{@code XMLGregorianCalendar eon} and
* {@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 month of <code>XMLGregorianCalendar</code> to be created.
* @param day of <code>XMLGregorianCalendar</code> to be created.
* @param hour of <code>XMLGregorianCalendar</code> to be created.
* @param minute of <code>XMLGregorianCalendar</code> to be created.
* @param second of <code>XMLGregorianCalendar</code> to be created.
* @param millisecond of <code>XMLGregorianCalendar</code> to be created.
* @param timezone of <code>XMLGregorianCalendar</code> to be created.
* @param year of {@code XMLGregorianCalendar} to be created.
* @param month of {@code XMLGregorianCalendar} to be created.
* @param day of {@code XMLGregorianCalendar} to be created.
* @param hour of {@code XMLGregorianCalendar} to be created.
* @param minute of {@code XMLGregorianCalendar} to be created.
* @param second of {@code XMLGregorianCalendar} to be created.
* @param millisecond of {@code XMLGregorianCalendar} 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
* 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()}.
*/
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
* with <code>month</code> and <code>day</code> parameters set to
* {@link DatatypeConstants#FIELD_UNDEFINED}.</p>
* <p>For example, an instance of {@code gYear} can be created invoking this factory
* with {@code month} and {@code day} parameters set to
* {@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 month of <code>XMLGregorianCalendar</code> to be created.
* @param day of <code>XMLGregorianCalendar</code> to be created.
* @param year of {@code XMLGregorianCalendar} to be created.
* @param month of {@code XMLGregorianCalendar} 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.
*
* @return <code>XMLGregorianCalendar</code> created from parameter values.
* @return {@code XMLGregorianCalendar} created from parameter values.
*
* @see DatatypeConstants#FIELD_UNDEFINED
*
* @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}
* 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()}.
*/
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 minutes number of minutes
* @param seconds number of seconds
* @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
* 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()}.
*
* @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 {@link DatatypeConstants#FIELD_UNDEFINED} 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.
*
* @param hours number of hours
* @param minutes number of minutes
* @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.
*
* @return <code>XMLGregorianCalendar</code> created from parameter values.
* @return {@code XMLGregorianCalendar} created from parameter values.
*
* @see DatatypeConstants#FIELD_UNDEFINED
*
* @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}
* 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()}.
*/
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 minutes number of minutes
@ -1043,13 +1048,13 @@ public abstract class DatatypeFactory {
* @param milliseconds number of milliseconds
* @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
*
* @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}
* 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()}.
*/
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
* 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,
* 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),
* 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
* to use for the duration datatype of XML Schema 1.0 with
* the errata.</p>
* the errata.
*
* <h2>Order relationship</h2>
* <p>Duration objects only have partial order, where two values A and B
* maybe either:</p>
* maybe either:
* <ol>
* <li>A&lt;B (A is shorter than B)
* <li>A&gt;B (A is longer than B)
* <li>A{@literal <}B (A is shorter than B)
* <li>A{@literal >}B (A is longer than B)
* <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>
*
* <p>For example, 30 days cannot be meaningfully compared to one month.
* The {@link #compare(Duration duration)} method implements this
* relationship.</p>
* relationship.
*
* <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>
* <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
* fail for some combinations of operations. For example, you cannot
* 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
* the <code>Duration</code> class can only deal with finite precision
* decimal numbers. For example, one cannot represent 1 sec divided by 3.</p>
* the {@code Duration} class can only deal with finite precision
* decimal numbers. For example, one cannot represent 1 sec divided by 3.
*
* <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>
* <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,
* 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}.
*
* @author <a href="mailto:Joseph.Fialli@Sun.COM">Joseph Fialli</a>
@ -99,7 +99,7 @@ import javax.xml.namespace.QName;
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;
@ -107,24 +107,24 @@ public abstract class Duration {
* Default no-arg constructor.
*
* <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
* produce an object with a consistent state and may be
* removed in the future.</p>
* removed in the future.
*/
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,
* 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">
* <thead>
* <tr>
* <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>
* </th>
* </tr>
@ -238,16 +238,16 @@ public abstract class Duration {
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
* {@link #getField(DatatypeConstants.Field field) getField(DatatypeConstants.YEARS)}.</p>
* <p>{@code getYears()} is a convenience method for
* {@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
* with years that go beyond the range of an <code>int</code>.
* Use {@link #getField(DatatypeConstants.Field field) getField(DatatypeConstants.YEARS)} to avoid possible loss of precision.</p>
* <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}.
* 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() {
return getField(DatatypeConstants.YEARS).intValue();
@ -260,7 +260,7 @@ public abstract class Duration {
* This method works just like {@link #getYears()} except
* that this method works on the MONTHS field.
*
* @return Months of this <code>Duration</code>.
* @return Months of this {@code Duration}.
*/
public int getMonths() {
return getField(DatatypeConstants.MONTHS).intValue();
@ -273,7 +273,7 @@ public abstract class Duration {
* This method works just like {@link #getYears()} except
* that this method works on the DAYS field.
*
* @return Days of this <code>Duration</code>.
* @return Days of this {@code Duration}.
*/
public int getDays() {
return getField(DatatypeConstants.DAYS).intValue();
@ -286,7 +286,7 @@ public abstract class Duration {
* This method works just like {@link #getYears()} except
* that this method works on the HOURS field.
*
* @return Hours of this <code>Duration</code>.
* @return Hours of this {@code Duration}.
*
*/
public int getHours() {
@ -300,7 +300,7 @@ public abstract class Duration {
* This method works just like {@link #getYears()} except
* that this method works on the MINUTES field.
*
* @return Minutes of this <code>Duration</code>.
* @return Minutes of this {@code Duration}.
*
*/
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,
* 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>
* <code>new Duration("PT10.00099S").getTimeInMills(x) == 10000</code>.
* <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}
* </pre>
*
* <p>
* 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)}
* method for details.
*
* @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
* returns the difference between <code>startInstant</code> and
* <code>startInstant+duration</code>
* returns the difference between {@code startInstant} and
* {@code startInstant+duration}
*
* @return milliseconds between <code>startInstant</code> and
* <code>startInstant</code> plus this <code>Duration</code>
* @return milliseconds between {@code startInstant} and
* {@code startInstant} plus this {@code Duration}
*
* @throws NullPointerException if <code>startInstant</code> parameter
* @throws NullPointerException if {@code startInstant} parameter
* 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,
* 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>
* <code>new Duration("PT10.00099S").getTimeInMills(x) == 10000</code>.
* <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}
* </pre>
*
* <p>
* 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)}
* method for details.
*
* @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
* returns the difference between <code>startInstant</code> and
* <code>startInstant+duration</code>.
* returns the difference between {@code startInstant} and
* {@code startInstant+duration}.
*
* @throws NullPointerException
* If the startInstant parameter is null.
*
* @return milliseconds between <code>startInstant</code> and
* <code>startInstant</code> plus this <code>Duration</code>
* @return milliseconds between {@code startInstant} and
* {@code startInstant} plus this {@code Duration}
*
* @see #getTimeInMillis(Calendar)
*/
@ -418,7 +418,7 @@ public abstract class Duration {
* returns a {@link java.math.BigInteger} object. For SECONDS, this
* 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);
@ -440,9 +440,9 @@ public abstract class Duration {
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>
* "1 day" + "-3 days" = "-2 days"
* "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,
* there are cases where the operation fails in
* {@link IllegalStateException}.</p>
* {@link IllegalStateException}.
*
* <p>
* Formally, the computation is defined as follows.</p>
* Formally, the computation is defined as follows.
* <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.,
* <code>(-X)+Y=Y-X</code>, <code>X+(-Y)=X-Y</code>,
* <code>(-X)+(-Y)=-(X+Y)</code>)
* {@code (-X)+Y=Y-X}, {@code X+(-Y)=X-Y},
* {@code (-X)+(-Y)=-(X+Y)})
*
* <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.
* <p>
* A field of the resulting <code>Duration</code> will be unset if and
* only if respective fields of two input <code>Duration</code>s are unset.
* A field of the resulting {@code Duration} will be unset if and
* only if respective fields of two input {@code Duration}s are unset.
* <p>
* Note that <code>lhs.add(rhs)</code> will be always successful if
* <code>lhs.signum()*rhs.signum()!=-1</code> or both of them are
* normalized.</p>
* Note that {@code lhs.add(rhs)} will be always successful if
* {@code lhs.signum()*rhs.signum()!=-1} or both of them are
* normalized.
*
* @param rhs <code>Duration</code> to add to this <code>Duration</code>
* @param rhs {@code Duration} to add to this {@code Duration}
*
* @return
* non-null valid Duration object.
@ -501,25 +501,22 @@ public abstract class Duration {
* uses int to hold values, there are cases where this method
* won't work correctly (for example if values of fields
* exceed the range of int.)
* </p>
*
* <p>
* Also, since this duration class is a Gregorian duration, this
* method will not work correctly if the given {@link Calendar}
* object is based on some other calendar systems.
* </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
* this duration is "P1.23456S", then 1 is added to SECONDS,
* 234 is added to MILLISECONDS, and the rest will be unused.
* </p>
*
* <p>
* Note that because {@link Calendar#add(int, int)} is using
* <code>int</code>, <code>Duration</code> with values beyond the
* range of <code>int</code> in its fields
* {@code int}, {@code Duration} with values beyond the
* range of {@code int} in its fields
* will cause overflow/underflow to the given {@link Calendar}.
* {@link XMLGregorianCalendar#add(Duration)} provides the same
* 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>
* "1 day" - "-3 days" = "4 days"
* "1 year" - "1 day" = IllegalStateException
@ -583,31 +580,31 @@ public abstract class Duration {
* </pre>
*
* <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.
* 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.,
* <code>(-X)-Y=-(X+Y)</code>, <code>X-(-Y)=X+Y</code>,
* <code>(-X)-(-Y)=-(X-Y)</code>)</p>
* {@code (-X)-Y=-(X+Y)}, {@code X-(-Y)=X+Y},
* {@code (-X)-(-Y)=-(X-Y)})
*
* <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,
* 1 (if <code>F</code> is negative) or -1 (otherwise)
* will be borrowed from the next bigger unit of <code>F</code>.</p>
* 1 (if {@code F} is negative) or -1 (otherwise)
* will be borrowed from the next bigger unit of {@code F}.
*
* <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
* the computation needs to borrow 1 or -1 month to compensate
* 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
* 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
* longer than the value of this duration.</p>
* Computes a new duration whose value is {@code factor} times
* longer than the value of this duration.
*
* <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>
* multiply(new BigDecimal(String.valueOf(factor)))
* </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)
*/
@ -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.
*
* <p>
@ -656,7 +653,7 @@ public abstract class Duration {
* </pre>
*
* <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
* a new Duration object and returns it.
*
@ -671,7 +668,7 @@ public abstract class Duration {
* When fractions of month cannot be meaningfully carried down
* to days, or year to months, this will cause an
* {@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>
* To avoid {@link IllegalStateException}, use
@ -681,39 +678,39 @@ public abstract class Duration {
* @param factor to multiply by
*
* @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
* the months field.
*
* @throws NullPointerException if the <code>factor</code> parameter is
* <code>null</code>.
* @throws NullPointerException if the {@code factor} parameter is
* {@code null}.
*
*/
public abstract Duration multiply(final BigDecimal factor);
/**
* Returns a new <code>Duration</code> object whose
* value is <code>-this</code>.
* Returns a new {@code Duration} object whose
* value is {@code -this}.
*
* <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
* a new Duration object and returns it.
*
* @return
* always return a non-null valid <code>Duration</code> object.
* always return a non-null valid {@code Duration} object.
*/
public abstract Duration negate();
/**
* <p>Converts the years and months fields into the days field
* by using a specific time instant as the reference point.</p>
* Converts the years and months fields into the days field
* by using a specific time instant as the reference point.
*
* <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>
* <li>the given Calendar object is cloned</li>
* <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>
* </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
* 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.
*/
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
* <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>
* <li>{@link DatatypeConstants#LESSER} if this <code>Duration</code> is shorter than <code>duration</code> parameter</li>
* <li>{@link DatatypeConstants#EQUAL} if this <code>Duration</code> is equal to <code>duration</code> parameter</li>
* <li>{@link DatatypeConstants#GREATER} if this <code>Duration</code> is longer 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} is equal to {@code duration} 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>
* </ul>
*
* @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}
* or {@link DatatypeConstants#INDETERMINATE}.
*
@ -763,7 +760,7 @@ public abstract class Duration {
* cannot reasonably process the request, e.g. W3C XML Schema allows for
* arbitrarily large/small/precise values, the request may be beyond the
* implementations capability.
* @throws NullPointerException if <code>duration</code> is <code>null</code>.
* @throws NullPointerException if {@code duration} is {@code null}.
*
* @see #isShorterThan(Duration)
* @see #isLongerThan(Duration)
@ -771,23 +768,23 @@ public abstract class Duration {
public abstract int compare(final Duration duration);
/**
* <p>Checks if this duration object is strictly longer than
* another <code>Duration</code> object.</p>
* Checks if this duration object is strictly longer than
* 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
* specification.</p>
* specification.
*
* <p>For example, "P1D" (one day) > "PT12H" (12 hours) and
* "P2Y" (two years) > "P23M" (23 months).</p>
* <p>For example, "P1D" (one day) {@literal >} "PT12H" (12 hours) and
* "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
* cannot reasonably process the request, e.g. W3C XML Schema allows for
* arbitrarily large/small/precise values, the request may be beyond the
* implementations capability.
* @throws NullPointerException If <code>duration</code> is null.
* @throws NullPointerException If {@code duration} is null.
*
* @return
* 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
* another <code>Duration</code> object.</p>
* Checks if this duration object is strictly shorter than
* 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>,
* else <code>false</code>.
* @return {@code true} if {@code duration} parameter is shorter than this {@code Duration},
* else {@code false}.
*
* @throws UnsupportedOperationException If the underlying implementation
* cannot reasonably process the request, e.g. W3C XML Schema allows for
* arbitrarily large/small/precise values, the request may be beyond the
* implementations capability.
* @throws NullPointerException if <code>duration</code> is null.
* @throws NullPointerException if {@code duration} is null.
*
* @see #isLongerThan(Duration duration)
* @see #compare(Duration duration)
@ -823,19 +820,19 @@ public abstract class Duration {
}
/**
* <p>Checks if this duration object has the same duration
* as another <code>Duration</code> object.</p>
* Checks if this duration object has the same duration
* 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
* 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
* 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.
* For example,</p>
* For example,
* <pre>
* !new Duration("P1M").isShorterThan(new Duration("P30D"))
* !new Duration("P1M").isLongerThan(new Duration("P30D"))
@ -843,14 +840,14 @@ public abstract class Duration {
* </pre>
*
* @param duration
* The object to compare this <code>Duration</code> against.
* The object to compare this {@code Duration} against.
*
* @return
* <code>true</code> if this duration is the same length as
* <code>duration</code>.
* <code>false</code> if <code>duration</code> is <code>null</code>,
* {@code true} if this duration is the same length as
* {@code duration}.
* {@code false} if {@code duration} is {@code null},
* is not a
* <code>Duration</code> object,
* {@code Duration} object,
* or its length is different from this duration.
*
* @throws UnsupportedOperationException If the underlying implementation
@ -877,18 +874,19 @@ public abstract class Duration {
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
* equivalent <code>Duration</code> <code>Object</code> by {@link DatatypeFactory#newDuration(String lexicalRepresentation)}.</p>
* <p>The result is formatted according to the XML Schema 1.0 spec
* 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>
* <code>Object</code> x:</p>
* <p>Formally, the following holds for any {@code Duration}
* {@code Object} x:
* <pre>
* new Duration(x.toString()).equals(x)
* </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() {
@ -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()}
* 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) {
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
* 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) {
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#GDAY}
* 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
* <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
* date/time datatype fields and this class' fields. It also summarizes
* 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,
* <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">
* <thead>
* <tr>
@ -64,22 +64,22 @@ import java.util.GregorianCalendar;
* </thead>
* <tbody>
* <tr>
* <th>XML Schema 1.0<br/>
* datatype<br/>
* <th>XML Schema 1.0<br>
* datatype<br>
* field</th>
* <th>Related<br/>XMLGregorianCalendar<br/>Accessor(s)</th>
* <th>Related<br>XMLGregorianCalendar<br>Accessor(s)</th>
* <th>Value Range</th>
* </tr>
* <tr>
* <td><a name="datetimefield-year"/>year</td>
* <td> {@link #getYear()} + {@link #getEon()} or<br/>
* <td><a name="datetimefield-year">year</a></td>
* <td> {@link #getYear()} + {@link #getEon()} or<br>
* {@link #getEonAndYear}
* </td>
* <td> <code>getYear()</code> is a value between -(10^9-1) to (10^9)-1
* or {@link DatatypeConstants#FIELD_UNDEFINED}.<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).
* A value of null indicates field is undefined.</br>
* <td> {@code getYear()} is a value between -(10^9-1) to (10^9)-1
* or {@link DatatypeConstants#FIELD_UNDEFINED}.<br>
* {@link #getEon()} is high order year value in billion of years.<br>
* {@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>
* 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,
* this class allows the year field to be set to zero. Otherwise,
@ -89,20 +89,20 @@ import java.util.GregorianCalendar;
* </td>
* </tr>
* <tr>
* <td><a name="datetimefield-month"/>month</td>
* <td><a name="datetimefield-month">month</a></td>
* <td> {@link #getMonth()} </td>
* <td> 1 to 12 or {@link DatatypeConstants#FIELD_UNDEFINED} </td>
* </tr>
* <tr>
* <td><a name="datetimefield-day"/>day</td>
* <td><a name="datetimefield-day">day</a></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
* 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>
* </tr>
* <tr>
* <td><a name="datetimefield-hour"/>hour</td>
* <td><a name="datetimefield-hour">hour</a></td>
* <td>{@link #getHour()}</td>
* <td>
* 0 to 23 or {@link DatatypeConstants#FIELD_UNDEFINED}.
@ -114,28 +114,28 @@ import java.util.GregorianCalendar;
* </td>
* </tr>
* <tr>
* <td><a name="datetimefield-minute"/>minute</td>
* <td><a name="datetimefield-minute">minute</a></td>
* <td> {@link #getMinute()} </td>
* <td> 0 to 59 or {@link DatatypeConstants#FIELD_UNDEFINED} </td>
* </tr>
* <tr>
* <td><a name="datetimefield-second"/>second</td>
* <td><a name="datetimefield-second">second</a></td>
* <td>
* {@link #getSecond()} + {@link #getMillisecond()}/1000 or<br/>
* {@link #getSecond()} + {@link #getMillisecond()}/1000 or<br>
* {@link #getSecond()} + {@link #getFractionalSecond()}
* </td>
* <td>
* {@link #getSecond()} from 0 to 60 or {@link DatatypeConstants#FIELD_UNDEFINED}.<br/>
* <i>(Note: 60 only allowable for leap second.)</i><br/>
* {@link #getSecond()} from 0 to 60 or {@link DatatypeConstants#FIELD_UNDEFINED}.<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
* the {@link #getSecond()} is defined.<br/>
* <code>FractionalSecond</code> is optional and has a value of <code>null</code> when it is undefined.<br />
* the {@link #getSecond()} is defined.<br>
* {@code FractionalSecond} is optional and has a value of {@code null} when it is undefined.<br>
* {@link #getMillisecond()} is the convenience
* millisecond precision of value of {@link #getFractionalSecond()}.
* </td>
* </tr>
* <tr>
* <td><a name="datetimefield-timezone"/>timezone</td>
* <td><a name="datetimefield-timezone">timezone</a></td>
* <td> {@link #getTimezone()} </td>
* <td> Number of minutes or {@link DatatypeConstants#FIELD_UNDEFINED}.
* Value range from -14 hours (-14 * 60 minutes) to 14 hours (14 * 60 minutes).
@ -145,14 +145,13 @@ import java.util.GregorianCalendar;
* </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
* 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
* if the composite
* values constitute an invalid XMLGregorianCalendar instance (for example, if
* the 31st of June is specified).
* </p>
*
* <p>The following operations are defined for this class:
* <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>.
* </li>
* </ul>
* </p>
*
* @author <a href="mailto:Joseph.Fialli@Sun.com">Joseph Fialli</a>
* @author <a href="mailto:Kohsuke.Kawaguchi@Sun.com">Kohsuke Kawaguchi</a>
@ -187,26 +185,26 @@ public abstract class XMLGregorianCalendar
* Default no-arg constructor.
*
* <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
* produce an object with a consistent state and may be
* removed in the future.</p>
* removed in the future.
*/
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
* to null.</p>
* to null.
*/
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(String lexicalRepresentation)},
* {@link DatatypeFactory#newXMLGregorianCalendar(
@ -250,83 +248,82 @@ public abstract class XMLGregorianCalendar
* int seconds,
* int milliseconds,
* int timezone)}.
* </p>
*
* <p><code>reset()</code> is designed to allow the reuse of existing <code>XMLGregorianCalendar</code>s
* thus saving resources associated with the creation of new <code>XMLGregorianCalendar</code>s.</p>
* <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}s.
*/
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>.
*
* @throws IllegalArgumentException if <code>year</code> parameter is
* @throws IllegalArgumentException if {@code year} parameter is
* outside value constraints for the field as specified in
* <a href="#datetimefieldmapping">date/time field mapping table</a>.
*/
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
* {@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
* <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>.
* 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);
/**
* <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>.
*
* @throws IllegalArgumentException if <code>month</code> parameter is
* @throws IllegalArgumentException if {@code month} parameter is
* outside value constraints for the field as specified in
* <a href="#datetimefieldmapping">date/time field mapping table</a>.
*/
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>.
*
* @throws IllegalArgumentException if <code>day</code> parameter is
* @throws IllegalArgumentException if {@code day} parameter is
* outside value constraints for the field as specified in
* <a href="#datetimefieldmapping">date/time field mapping table</a>.
*/
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">
* 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
* <a href="#datetimefieldmapping">date/time field mapping table</a>.
*/
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
* <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>.
*
* @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>.
*/
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>.
*
* @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>.
*/
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>.
*
* @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>.
*/
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
* <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>.
*/
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
* <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>.
*/
public abstract void setFractionalSecond(BigDecimal fractional);
/**
* <p>Set time as one unit, including the optional infinite precision
* fractional seconds.</p>
* Set time as one unit, including the optional infinite precision
* fractional seconds.
*
* @param hour value constraints are summarized in
* <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>.
* @param second value constraints are summarized in
* <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.
*
* @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
* <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
* <code>year</code>.
* <code>null</code> if this optional part of the year field is not defined.</p>
* Return high order component for XML Schema 1.0 dateTime datatype field for
* {@code year}.
* {@code null} if this optional part of the year field is not defined.
*
* <p>Value constraints for this value are summarized in
* <a href="#datetimefield-year">year field of date/time field mapping table</a>.</p>
* @return eon of this <code>XMLGregorianCalendar</code>. The value
* <a href="#datetimefield-year">year field of date/time field mapping table</a>.
* @return eon of this {@code XMLGregorianCalendar}. The value
* returned is an integer multiple of 10^9.
*
* @see #getYear()
@ -484,13 +481,13 @@ public abstract class XMLGregorianCalendar
public abstract BigInteger getEon();
/**
* <p>Return low order component for XML Schema 1.0 dateTime datatype field for
* <code>year</code> or {@link DatatypeConstants#FIELD_UNDEFINED}.</p>
* Return low order component for XML Schema 1.0 dateTime datatype field for
* {@code year} or {@link DatatypeConstants#FIELD_UNDEFINED}.
*
* <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 #getEonAndYear()
@ -498,16 +495,16 @@ public abstract class XMLGregorianCalendar
public abstract int getYear();
/**
* <p>Return XML Schema 1.0 dateTime datatype field for
* <code>year</code>.</p>
* Return XML Schema 1.0 dateTime datatype field for
* {@code year}.
*
* <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>
* when both fields are defined. When only <code>year</code> is defined,
* return it. When both <code>eon</code> and <code>year</code> are not
* defined, return <code>null</code>.
* @return sum of {@code eon} and {@code BigInteger.valueOf(year)}
* when both fields are defined. When only {@code year} is defined,
* return it. When both {@code eon} and {@code year} are not
* defined, return {@code null}.
*
* @see #getEon()
* @see #getYear()
@ -515,21 +512,21 @@ public abstract class XMLGregorianCalendar
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
* <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();
/**
* 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
* <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)
*/
@ -540,7 +537,7 @@ public abstract class XMLGregorianCalendar
* {@link DatatypeConstants#FIELD_UNDEFINED} if this optional field is not defined.
*
* <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)
*/
@ -551,34 +548,34 @@ public abstract class XMLGregorianCalendar
* Returns {@link DatatypeConstants#FIELD_UNDEFINED} if this field is not defined.
*
* <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)
*/
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.
*
* <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)
*/
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.
* When this field is not defined, the optional xs:dateTime
* fractional seconds field, represented by
* {@link #getFractionalSecond()} and {@link #getMillisecond()},
* must not be defined.</p>
* must not be defined.
*
* <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 #getMillisecond()
@ -587,20 +584,20 @@ public abstract class XMLGregorianCalendar
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
* precision fractional second value returned by
* {@link #getFractionalSecond()}. The returned value is the rounded
* down to milliseconds value of
* {@link #getFractionalSecond()}. When {@link #getFractionalSecond()}
* returns <code>null</code>, this method must return
* {@link DatatypeConstants#FIELD_UNDEFINED}.</p>
* returns {@code null}, this method must return
* {@link DatatypeConstants#FIELD_UNDEFINED}.
*
* <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 #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
* <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
* 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 #setTime(int, int, int, BigDecimal)
@ -638,51 +635,51 @@ public abstract class XMLGregorianCalendar
// 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
* <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
* <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
* the specified <code>xmlGregorianCalendar</code> as
* @return The relationship between {@code this} {@code XMLGregorianCalendar} and
* the specified {@code xmlGregorianCalendar} as
* {@link DatatypeConstants#LESSER},
* {@link DatatypeConstants#EQUAL},
* {@link DatatypeConstants#GREATER} or
* {@link DatatypeConstants#INDETERMINATE}.
*
* @throws NullPointerException if <code>xmlGregorianCalendar</code> is null.
* @throws NullPointerException if {@code xmlGregorianCalendar} is null.
*/
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>Implements W3C XML Schema Part 2, Section 3.2.7.3 (A).</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).
*
* @return <code>this</code> <code>XMLGregorianCalendar</code> normalized to UTC.
* @return {@code this} {@code XMLGregorianCalendar} normalized to UTC.
*/
public abstract XMLGregorianCalendar normalize();
/**
* <p>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>XMLGregorianCalendar</code> object that represents the same
* instant in time as this object.</p>
* Compares this calendar to the specified object. The result is
* {@code true} if and only if the argument is not null and is an
* {@code XMLGregorianCalendar} object that represents the same
* instant in time as this object.
*
* @param obj to compare.
*
* @return <code>true</code> when <code>obj</code> is an instance of
* <code>XMLGregorianCalendar</code> and
* @return {@code true} when {@code obj} is an instance of
* {@code XMLGregorianCalendar} and
* {@link #compare(XMLGregorianCalendar obj)}
* returns {@link DatatypeConstants#EQUAL},
* otherwise <code>false</code>.
* otherwise {@code false}.
*/
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.
*/
@ -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
* <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
* {@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
* 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();
/**
* <p>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>
* Return the name of the XML Schema date/time type that this instance
* maps to. Type is computed based on fields that are set.
*
* <table border="2" rules="all" cellpadding="2">
* <thead>
* <tr>
* <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>
* </th>
* </tr>
@ -850,11 +847,11 @@ public abstract class XMLGregorianCalendar
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
* 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.
*/
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
* <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>
* defines the mapping from XML Schema 1.0 <code>dateTime</code> fields
* to this class' representation of those fields.</p>
* defines the mapping from XML Schema 1.0 {@code dateTime} fields
* 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);
/**
* <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
* conversion relies on the <code>java.util.GregorianCalendar</code> default
* <p>When {@code this} instance has an undefined field, this
* conversion relies on the {@code java.util.GregorianCalendar} default
* 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
* a required field for <code>java.util.GregorianCalendar</code>. See javadoc
* for <code>java.util.TimeZone.getDefault()</code> on how the default
* is determined. To explicitly specify the <code>TimeZone</code>
* a required field for {@code java.util.GregorianCalendar}. See javadoc
* for {@code java.util.TimeZone.getDefault()} on how the default
* is determined. To explicitly specify the {@code TimeZone}
* instance, see
* {@link #toGregorianCalendar(TimeZone, Locale, XMLGregorianCalendar)}.</p>
* {@link #toGregorianCalendar(TimeZone, Locale, XMLGregorianCalendar)}.
*
* <table border="2" rules="all" cellpadding="2">
* <thead>
* <tr>
* <th align="center" colspan="2">
* Field by Field Conversion from this class to
* <code>java.util.GregorianCalendar</code>
* {@code java.util.GregorianCalendar}
* </th>
* </tr>
* </thead>
* <tbody>
* <tr>
* <td><code>java.util.GregorianCalendar</code> field</td>
* <td><code>javax.xml.datatype.XMLGregorianCalendar</code> field</td>
* <td>{@code java.util.GregorianCalendar} field</td>
* <td>{@code javax.xml.datatype.XMLGregorianCalendar} field</td>
* </tr>
* <tr>
* <td><code>ERA</code></td>
* <td>{@link #getEonAndYear()}<code>.signum() < 0 ? GregorianCalendar.BC : GregorianCalendar.AD</code></td>
* <td>{@code ERA}</td>
* <td>{@link #getEonAndYear()}{@code .signum() < 0 ? GregorianCalendar.BC : GregorianCalendar.AD}</td>
* </tr>
* <tr>
* <td><code>YEAR</code></td>
* <td>{@link #getEonAndYear()}<code>.abs().intValue()</code><i>*</i></td>
* <td>{@code YEAR}</td>
* <td>{@link #getEonAndYear()}{@code .abs().intValue()}<i>*</i></td>
* </tr>
* <tr>
* <td><code>MONTH</code></td>
* <td>{@code MONTH}</td>
* <td>{@link #getMonth()} - {@link DatatypeConstants#JANUARY} + {@link GregorianCalendar#JANUARY}</td>
* </tr>
* <tr>
* <td><code>DAY_OF_MONTH</code></td>
* <td>{@code DAY_OF_MONTH}</td>
* <td>{@link #getDay()}</td>
* </tr>
* <tr>
* <td><code>HOUR_OF_DAY</code></td>
* <td>{@code HOUR_OF_DAY}</td>
* <td>{@link #getHour()}</td>
* </tr>
* <tr>
* <td><code>MINUTE</code></td>
* <td>{@code MINUTE}</td>
* <td>{@link #getMinute()}</td>
* </tr>
* <tr>
* <td><code>SECOND</code></td>
* <td>{@code SECOND}</td>
* <td>{@link #getSecond()}</td>
* </tr>
* <tr>
* <td><code>MILLISECOND</code></td>
* <td>{@code MILLISECOND}</td>
* <td>get millisecond order from {@link #getFractionalSecond()}<i>*</i> </td>
* </tr>
* <tr>
* <td><code>GregorianCalendar.setTimeZone(TimeZone)</code></td>
* <td>{@code GregorianCalendar.setTimeZone(TimeZone)}</td>
* <td>{@link #getTimezone()} formatted into Custom timezone id</td>
* </tr>
* </tbody>
@ -958,74 +955,74 @@ public abstract class XMLGregorianCalendar
* to source datatype having higher precision than target datatype.
*
* <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.
* <ul>
* <li>Using <code>timeZone</code> value as defined above, create a new
* <code>java.util.GregorianCalendar(timeZone,Locale.getDefault())</code>.
* <li>Using {@code timeZone} value as defined above, create a new
* {@code java.util.GregorianCalendar(timeZone,Locale.getDefault())}.
* </li>
* <li>Initialize all GregorianCalendar fields by calling {@link java.util.GregorianCalendar#clear()}.</li>
* <li>Obtain a pure Gregorian Calendar by invoking
* <code>GregorianCalendar.setGregorianChange(
* new Date(Long.MIN_VALUE))</code>.</li>
* {@code GregorianCalendar.setGregorianChange(
* new Date(Long.MIN_VALUE))}.</li>
* <li>Its fields ERA, YEAR, MONTH, DAY_OF_MONTH, HOUR_OF_DAY,
* MINUTE, SECOND and MILLISECOND are set using the method
* <code>Calendar.set(int,int)</code></li>
* {@code Calendar.set(int,int)}</li>
* </ul>
* </p>
*
* @see #toGregorianCalendar(java.util.TimeZone, java.util.Locale, XMLGregorianCalendar)
*/
public abstract GregorianCalendar toGregorianCalendar();
/**
* <p>Convert this <code>XMLGregorianCalendar</code> along with provided parameters
* to a {@link GregorianCalendar} instance.</p>
* Convert this {@code XMLGregorianCalendar} along with provided parameters
* to a {@link GregorianCalendar} instance.
*
* <p> Since XML Schema 1.0 date/time datetypes has no concept of
* timezone ids or daylight savings timezone ids, this conversion operation
* 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>
* <li>when parameter <code>timeZone</code> is non-null,
* <li>when parameter {@code timeZone} is non-null,
* it is the timezone field.</li>
* <li>else when <code>this.getTimezone() != FIELD_UNDEFINED</code>,
* create a <code>java.util.TimeZone</code> with a custom timezone id
* using the <code>this.getTimezone()</code>.</li>
* <li>else when <code>defaults.getTimezone() != FIELD_UNDEFINED</code>,
* create a <code>java.util.TimeZone</code> with a custom timezone id
* using <code>defaults.getTimezone()</code>.</li>
* <li>else use the <code>GregorianCalendar</code> default timezone value
* <li>else when {@code this.getTimezone() != FIELD_UNDEFINED},
* create a {@code java.util.TimeZone} with a custom timezone id
* using the {@code this.getTimezone()}.</li>
* <li>else when {@code defaults.getTimezone() != FIELD_UNDEFINED},
* create a {@code java.util.TimeZone} with a custom timezone id
* using {@code defaults.getTimezone()}.</li>
* <li>else use the {@code GregorianCalendar} default timezone value
* 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
* <code>GregorianCalendar</code> should be instantiated in following
* {@code GregorianCalendar} should be instantiated in following
* manner.
* <ul>
* <li>Create a new <code>java.util.GregorianCalendar(TimeZone,
* Locale)</code> with TimeZone set as specified above and the
* <code>Locale</code> parameter.
* <li>Create a new {@code java.util.GregorianCalendar(TimeZone,
* Locale)} with TimeZone set as specified above and the
* {@code Locale} parameter.
* </li>
* <li>Initialize all GregorianCalendar fields by calling {@link GregorianCalendar#clear()}</li>
* <li>Obtain a pure Gregorian Calendar by invoking
* <code>GregorianCalendar.setGregorianChange(
* new Date(Long.MIN_VALUE))</code>.</li>
* {@code GregorianCalendar.setGregorianChange(
* new Date(Long.MIN_VALUE))}.</li>
* <li>Its fields ERA, YEAR, MONTH, DAY_OF_MONTH, HOUR_OF_DAY,
* MINUTE, SECOND and MILLISECOND are set using the method
* <code>Calendar.set(int,int)</code></li>
* {@code Calendar.set(int,int)}</li>
* </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
* value is <code>null</code>.
* value is {@code null}.
* @param defaults provide default field values to use when corresponding
* field for this instance is FIELD_UNDEFINED or null.
* If <code>defaults</code>is <code>null</code> or a field
* within the specified <code>defaults</code> is undefined,
* just use <code>java.util.GregorianCalendar</code> defaults.
* If {@code defaults}is {@code null} or a field
* within the specified {@code defaults} is undefined,
* just use {@code java.util.GregorianCalendar} defaults.
* @return a java.util.GregorianCalendar conversion of this instance.
*/
public abstract GregorianCalendar toGregorianCalendar(
@ -1034,7 +1031,7 @@ public abstract class XMLGregorianCalendar
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,
* returns TimeZone initialized with custom timezone id
@ -1042,7 +1039,7 @@ public abstract class XMLGregorianCalendar
* try the defaultZoneoffset that was passed in.
* If defaultZoneoffset is FIELD_UNDEFINED, return
* 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
* {@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();
}

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;
/**
* <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>
* <li>Namespace URI:
* Namespace name expressed as a URI to which the prefix is bound</li>
* <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>
* </ul>
* <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
* for Namespace URI and prefix resolution.</p>
* <p>All {@code get*(*)} methods operate in the current scope
* for Namespace URI and prefix resolution.
*
* <p>Note that a Namespace URI can be bound to
* <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
* refer to the same Namespace URI. e.g.<br />
* <pre>
* &lt;element xmlns:prefix1="http://Namespace-name-URI"
* xmlns:prefix2="http://Namespace-name-URI"&gt;
* refer to the same Namespace URI. e.g.<br>
* <pre> {@code
* <element xmlns:prefix1="http://Namespace-name-URI"
* xmlns:prefix2="http://Namespace-name-URI"> }
* </pre>
* This can also occur when the same Namespace URI is used in multiple
* <code>XMLConstants.XMLNS_ATTRIBUTE</code> ("xmlns") Namespace
* declarations in the logical parent element hierarchy. e.g.<br />
* <pre>
* &lt;parent xmlns:prefix1="http://Namespace-name-URI">
* &lt;child xmlns:prefix2="http://Namespace-name-URI"&gt;
* {@code XMLConstants.XMLNS_ATTRIBUTE} ("xmlns") Namespace
* declarations in the logical parent element hierarchy. e.g.<br>
* <pre> {@code
* <parent xmlns:prefix1="http://Namespace-name-URI">
* <child xmlns:prefix2="http://Namespace-name-URI">
* ...
* &lt;/child&gt;
* &lt;/parent&gt;
* </pre></p>
* </child>
* </parent> }
* </pre>
*
* <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>
* @see javax.xml.XMLConstants
@ -82,17 +82,17 @@ import java.util.Iterator;
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
* table describes the returned Namespace URI value for all
* possible prefix values:</p>
* possible prefix values:
*
* <table border="2" rules="all" cellpadding="4">
* <thead>
* <tr>
* <td align="center" colspan="2">
* <code>getNamespaceURI(prefix)</code>
* {@code getNamespaceURI(prefix)}
* return value for specified prefixes
* </td>
* </tr>
@ -103,9 +103,9 @@ public interface NamespaceContext {
* </thead>
* <tbody>
* <tr>
* <td><code>DEFAULT_NS_PREFIX</code> ("")</td>
* <td>{@code DEFAULT_NS_PREFIX} ("")</td>
* <td>default Namespace URI in the current scope or
* <code>{@link
* <code> {@link
* javax.xml.XMLConstants#NULL_NS_URI XMLConstants.NULL_NS_URI("")}
* </code>
* when there is no default Namespace URI in the current scope</td>
@ -117,24 +117,24 @@ public interface NamespaceContext {
* <tr>
* <td>unbound prefix</td>
* <td>
* <code>{@link
* <code> {@link
* javax.xml.XMLConstants#NULL_NS_URI XMLConstants.NULL_NS_URI("")}
* </code>
* </td>
* </tr>
* <tr>
* <td><code>XMLConstants.XML_NS_PREFIX</code> ("xml")</td>
* <td><code>XMLConstants.XML_NS_URI</code>
* <td>{@code XMLConstants.XML_NS_PREFIX} ("xml")</td>
* <td>{@code XMLConstants.XML_NS_URI}
* ("http://www.w3.org/XML/1998/namespace")</td>
* </tr>
* <tr>
* <td><code>XMLConstants.XMLNS_ATTRIBUTE</code> ("xmlns")</td>
* <td><code>XMLConstants.XMLNS_ATTRIBUTE_NS_URI</code>
* <td>{@code XMLConstants.XMLNS_ATTRIBUTE} ("xmlns")</td>
* <td>{@code XMLConstants.XMLNS_ATTRIBUTE_NS_URI}
* ("http://www.w3.org/2000/xmlns/")</td>
* </tr>
* <tr>
* <td><code>null</code></td>
* <td><code>IllegalArgumentException</code> is thrown</td>
* <td>{@code null}</td>
* <td>{@code IllegalArgumentException} is thrown</td>
* </tr>
* </tbody>
* </table>
@ -143,26 +143,26 @@ public interface NamespaceContext {
*
* @return Namespace URI bound to prefix in the current scope
*
* @throws IllegalArgumentException When <code>prefix</code> is
* <code>null</code>
* @throws IllegalArgumentException When {@code prefix} is
* {@code null}
*/
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
* scope, use {@link #getPrefixes(String namespaceURI)}.</p>
* scope, use {@link #getPrefixes(String namespaceURI)}.
*
* <p>When requesting a prefix by Namespace URI, the following
* table describes the returned prefix value for all Namespace URI
* values:</p>
* values:
*
* <table border="2" rules="all" cellpadding="4">
* <thead>
* <tr>
* <th align="center" colspan="2">
* <code>getPrefix(namespaceURI)</code> return value for
* {@code getPrefix(namespaceURI)} return value for
* specified Namespace URIs
* </th>
* </tr>
@ -173,8 +173,8 @@ public interface NamespaceContext {
* </thead>
* <tbody>
* <tr>
* <td>&lt;default Namespace URI&gt;</td>
* <td><code>XMLConstants.DEFAULT_NS_PREFIX</code> ("")
* <td>{@code <default Namespace URI>}</td>
* <td>{@code XMLConstants.DEFAULT_NS_PREFIX} ("")
* </td>
* </tr>
* <tr>
@ -186,21 +186,21 @@ public interface NamespaceContext {
* </tr>
* <tr>
* <td>unbound Namespace URI</td>
* <td><code>null</code></td>
* <td>{@code null}</td>
* </tr>
* <tr>
* <td><code>XMLConstants.XML_NS_URI</code>
* <td>{@code XMLConstants.XML_NS_URI}
* ("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>
* <td><code>XMLConstants.XMLNS_ATTRIBUTE_NS_URI</code>
* <td>{@code XMLConstants.XMLNS_ATTRIBUTE_NS_URI}
* ("http://www.w3.org/2000/xmlns/")</td>
* <td><code>XMLConstants.XMLNS_ATTRIBUTE</code> ("xmlns")</td>
* <td>{@code XMLConstants.XMLNS_ATTRIBUTE} ("xmlns")</td>
* </tr>
* <tr>
* <td><code>null</code></td>
* <td><code>IllegalArgumentException</code> is thrown</td>
* <td>{@code null}</td>
* <td>{@code IllegalArgumentException} is thrown</td>
* </tr>
* </tbody>
* </table>
@ -209,32 +209,32 @@ public interface NamespaceContext {
*
* @return prefix bound to Namespace URI in current context
*
* @throws IllegalArgumentException When <code>namespaceURI</code> is
* <code>null</code>
* @throws IllegalArgumentException When {@code namespaceURI} is
* {@code null}
*/
String getPrefix(String namespaceURI);
/**
* <p>Get all prefixes bound to a Namespace URI in the current
* scope.</p>
* Get all prefixes bound to a Namespace URI in the current
* scope.
*
* <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
* <code>remove()</code> method will throw
* <code>UnsupportedOperationException</code>.</strong></p>
* {@code remove()} method will throw
* {@code UnsupportedOperationException}.</strong>
*
* <p>When requesting prefixes by Namespace URI, the following
* table describes the returned prefixes value for all Namespace
* URI values:</p>
* URI values:
*
* <table border="2" rules="all" cellpadding="4">
* <thead>
* <tr>
* <th align="center" colspan="2"><code>
* getPrefixes(namespaceURI)</code> return value for
* <th align="center" colspan="2">{@code
* getPrefixes(namespaceURI)} return value for
* specified Namespace URIs</th>
* </tr>
* <tr>
@ -245,9 +245,9 @@ public interface NamespaceContext {
* <tbody>
* <tr>
* <td>bound Namespace URI,
* including the &lt;default Namespace URI&gt;</td>
* including the {@code <default Namespace URI>}</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,
* <strong>implementation dependent</strong>,
* order
@ -255,34 +255,34 @@ public interface NamespaceContext {
* </tr>
* <tr>
* <td>unbound Namespace URI</td>
* <td>empty <code>Iterator</code></td>
* <td>empty {@code Iterator}</td>
* </tr>
* <tr>
* <td><code>XMLConstants.XML_NS_URI</code>
* <td>{@code XMLConstants.XML_NS_URI}
* ("http://www.w3.org/XML/1998/namespace")</td>
* <td><code>Iterator</code> with one element set to
* <code>XMLConstants.XML_NS_PREFIX</code> ("xml")</td>
* <td>{@code Iterator} with one element set to
* {@code XMLConstants.XML_NS_PREFIX} ("xml")</td>
* </tr>
* <tr>
* <td><code>XMLConstants.XMLNS_ATTRIBUTE_NS_URI</code>
* <td>{@code XMLConstants.XMLNS_ATTRIBUTE_NS_URI}
* ("http://www.w3.org/2000/xmlns/")</td>
* <td><code>Iterator</code> with one element set to
* <code>XMLConstants.XMLNS_ATTRIBUTE</code> ("xmlns")</td>
* <td>{@code Iterator} with one element set to
* {@code XMLConstants.XMLNS_ATTRIBUTE} ("xmlns")</td>
* </tr>
* <tr>
* <td><code>null</code></td>
* <td><code>IllegalArgumentException</code> is thrown</td>
* <td>{@code null}</td>
* <td>{@code IllegalArgumentException} is thrown</td>
* </tr>
* </tbody>
* </table>
*
* @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
*
* @throws IllegalArgumentException When <code>namespaceURI</code> is
* <code>null</code>
* @throws IllegalArgumentException When {@code namespaceURI} is
* {@code null}
*/
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;
/**
* <p>Protected constructor to prevent instantiation.
* Use {@link #newInstance()}.</p>
* Protected constructor to prevent instantiation.
* Use {@link #newInstance()}.
*/
protected DocumentBuilderFactory () {
}
@ -60,7 +60,6 @@ public abstract class DocumentBuilderFactory {
* This method uses the following ordered lookup procedure to determine
* the {@code DocumentBuilderFactory} implementation class to
* load:
* <p>
* <ul>
* <li>
* 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.
* It gives more control to the application as it can specify which provider
* should be loaded.
@ -143,21 +142,22 @@ public abstract class DocumentBuilderFactory {
* <h2>Tip for Trouble-shooting</h2>
* <p>Setting the {@code jaxp.debug} system property will cause
* 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>
* java -Djaxp.debug=1 YourProgram ....
* </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>
* current <code>Thread</code>'s context classLoader is used to load the factory class.
* @param classLoader {@code ClassLoader} used to load the factory class. If {@code null}
* current {@code Thread}'s context classLoader is used to load the factory class.
*
* @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.
*
* @see #newInstance()
@ -187,7 +187,7 @@ public abstract class DocumentBuilderFactory {
/**
* Specifies that the parser produced by this code will
* 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
* for XML namespaces; false otherwise.
@ -200,7 +200,7 @@ public abstract class DocumentBuilderFactory {
/**
* Specifies that the parser produced by this code will
* validate documents as they are parsed. By default the value of this
* is set to <code>false</code>.
* is set to {@code false}.
*
* <p>
* Note that "the validation" here means
@ -208,15 +208,13 @@ public abstract class DocumentBuilderFactory {
* parser</a> as defined in the XML recommendation.
* In other words, it essentially just controls the DTD validation.
* (except the legacy two properties defined in JAXP 1.2.)
* </p>
*
* <p>
* To use modern schema languages such as W3C XML Schema or
* RELAX NG instead of DTD, you can configure your parser to be
* 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.
* </p>
*
* @param validating true if the parser produced will validate documents
* 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
* 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
* 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
* 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
* 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
* reference nodes; false otherwise.
@ -259,11 +257,10 @@ public abstract class DocumentBuilderFactory {
}
/**
* <p>Specifies that the parser produced by this code will
* ignore comments. By default the value of this is set to <code>false
* </code>.</p>
* Specifies that the parser produced by this code will
* ignore comments. By default the value of this is set to {@code false}.
*
* @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) {
@ -274,7 +271,7 @@ public abstract class DocumentBuilderFactory {
* Specifies that the parser produced by this code will
* 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
* <code>false</code>
* {@code false}
*
* @param coalescing true if the parser produced will convert CDATA nodes
* 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
* support the {@link javax.xml.XMLConstants#ACCESS_EXTERNAL_DTD} and
* {@link javax.xml.XMLConstants#ACCESS_EXTERNAL_SCHEMA} properties.
* </p>
*
* <ul>
* <li>
* <p>
* Setting the {@link javax.xml.XMLConstants#ACCESS_EXTERNAL_DTD} property
* restricts the access to external DTDs, external Entity References to the
* protocols specified by the 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 javax.xml.parsers.DocumentBuilder}.
* </p>
* <p>
* </li>
* <li>
* Setting the {@link javax.xml.XMLConstants#ACCESS_EXTERNAL_SCHEMA} property
* restricts the access to external Schema set by the schemaLocation attribute to
* the protocols specified by the 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 javax.xml.parsers.DocumentBuilder}.
* </p>
* </li>
* </ul>
*
@ -413,61 +408,61 @@ public abstract class DocumentBuilderFactory {
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>
* Feature names are fully qualified {@link java.net.URI}s.
* Implementations may define their own features.
* 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.
* </p>
*
*
* <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>
* <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.
* 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)}.
* See {@link DocumentBuilder#setErrorHandler(org.xml.sax.ErrorHandler errorHandler)}.
* </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.
* </li>
* </ul>
*
* @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.
* @throws NullPointerException If the <code>name</code> parameter is null.
* @throws NullPointerException If the {@code name} parameter is null.
* @since 1.5
*/
public abstract void setFeature(String name, boolean value)
throws ParserConfigurationException;
/**
* <p>Get the state of the named feature.</p>
* Get the state of the named feature.
*
* <p>
* Feature names are fully qualified {@link java.net.URI}s.
* Implementations may define their own features.
* 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.
* </p>
*
* @param name Feature name.
*
* @return State of the named feature.
*
* @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
*/
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.
*
* <p>
@ -529,26 +524,26 @@ public abstract class DocumentBuilderFactory {
*
* <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
* the <code>http://java.sun.com/xml/jaxp/properties/schemaSource</code>
* property and/or the <code>http://java.sun.com/xml/jaxp/properties/schemaLanguage</code>
* the {@code http://java.sun.com/xml/jaxp/properties/schemaSource}
* property and/or the {@code http://java.sun.com/xml/jaxp/properties/schemaLanguage}
* property in conjunction with a {@link Schema} object.
* 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>
* A parser must be able to work with any {@link Schema}
* implementation. However, parsers and schemas are allowed
* to use implementation-specific custom mechanisms
* 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.
*
* @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
* 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
* <code>false</code>
* @param state Set XInclude processing to {@code true} or
* {@code false}
*
* @throws UnsupportedOperationException When implementation does not
* 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
*

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 {
/**
* <p>Should Parsers be validating?</p>
* Should Parsers be validating?
*/
private boolean validating = false;
/**
* <p>Should Parsers be namespace aware?</p>
* Should Parsers be namespace aware?
*/
private boolean namespaceAware = false;
/**
* <p>Protected constructor to force use of {@link #newInstance()}.</p>
* Protected constructor to force use of {@link #newInstance()}.
*/
protected SAXParserFactory () {
@ -64,7 +64,6 @@ public abstract class SAXParserFactory {
* This method uses the following ordered lookup procedure to determine
* the {@code SAXParserFactory} implementation class to
* load:
* <p>
* <ul>
* <li>
* 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.
* 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}
* 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>
* <p>Setting the {@code jaxp.debug} system property will cause
* 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:
@ -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 classLoader <code>ClassLoader</code> used to load the factory class. If <code>null</code>
* current <code>Thread</code>'s context classLoader is used to load the factory class.
* @param classLoader {@code ClassLoader} used to load the factory class. If {@code null}
* current {@code Thread}'s context classLoader is used to load the factory class.
*
* @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.
*
* @see #newInstance()
@ -179,8 +178,8 @@ public abstract class SAXParserFactory {
}
/**
* <p>Creates a new instance of a SAXParser using the currently
* configured factory parameters.</p>
* Creates a new instance of a SAXParser using the currently
* configured factory parameters.
*
* @return A new instance of a SAXParser.
*
@ -196,7 +195,7 @@ public abstract class SAXParserFactory {
/**
* Specifies that the parser produced by this code will
* 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
* provide support for XML namespaces; false otherwise.
@ -209,7 +208,7 @@ public abstract class SAXParserFactory {
/**
* Specifies that the parser produced by this code will
* validate documents as they are parsed. By default the value of this is
* set to <code>false</code>.
* set to {@code false}.
*
* <p>
* Note that "the validation" here means
@ -217,15 +216,13 @@ public abstract class SAXParserFactory {
* parser</a> as defined in the XML recommendation.
* In other words, it essentially just controls the DTD validation.
* (except the legacy two properties defined in JAXP 1.2.)
* </p>
*
* <p>
* To use modern schema languages such as W3C XML Schema or
* RELAX NG instead of DTD, you can configure your parser to be
* 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.
* </p>
*
* @param validating true if the parser produced by this code will
* validate documents as they are parsed; false otherwise.
@ -260,24 +257,23 @@ public abstract class SAXParserFactory {
}
/**
*
* <p>Sets the particular feature in the underlying implementation of
* Sets the particular feature in the underlying implementation of
* org.xml.sax.XMLReader.
* 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.
* When the feature is</p>
* When the feature is
* <ul>
* <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.
* 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)}.
* See {@link SAXParser} <code>parse</code> methods for handler specification.
* See {@link SAXParser} {@code parse} methods for handler specification.
* </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.
* </li>
* </ul>
@ -292,7 +288,7 @@ public abstract class SAXParserFactory {
* @throws SAXNotSupportedException When the underlying XMLReader
* recognizes the property name but doesn't support the
* 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
*/
@ -302,8 +298,8 @@ public abstract class SAXParserFactory {
/**
*
* <p>Returns the particular property requested for in the underlying
* implementation of org.xml.sax.XMLReader.</p>
* Returns the particular property requested for in the underlying
* implementation of org.xml.sax.XMLReader.
*
* @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
* from this factory.</p>
* Set the {@link Schema} to be used by parsers created
* from this factory.
*
* <p>When a {@link Schema} is non-null, a parser will use a validator
* 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
* 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
* adding default values that were missing in documents), and a parser
* 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
* the {@link #isValidating()} method returns <code>false</code>.
* the {@link #isValidating()} method returns {@code false}.
*
* <p>It is an error to use
* the <code>http://java.sun.com/xml/jaxp/properties/schemaSource</code>
* property and/or the <code>http://java.sun.com/xml/jaxp/properties/schemaLanguage</code>
* the {@code http://java.sun.com/xml/jaxp/properties/schemaSource}
* property and/or the {@code http://java.sun.com/xml/jaxp/properties/schemaLanguage}
* property in conjunction with a non-null {@link Schema} object.
* 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>
* A parser must be able to work with any {@link Schema}
* implementation. However, parsers and schemas are allowed
* to use implementation-specific custom mechanisms
* 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
* 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
* 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
* <code>false</code>
* @param state Set XInclude processing to {@code true} or
* {@code false}
*
* @throws UnsupportedOperationException When implementation does not
* 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
*

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 method uses the following ordered lookup procedure to determine
* the XMLEventFactory implementation class to load:
* <p>
* <ul>
* <li>
* Use the javax.xml.stream.XMLEventFactory system property.
@ -158,7 +157,6 @@ public abstract class XMLEventFactory {
* <p>
* This method uses the following ordered lookup procedure to determine
* the XMLEventFactory implementation class to load:
* <p>
* <ul>
* <li>
* 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 method uses the following ordered lookup procedure to determine
* the XMLInputFactory implementation class to load:
* </p>
*
* <ul>
* <li>
* <p>Use the javax.xml.stream.XMLInputFactory system property.
@ -201,12 +201,11 @@ public abstract class XMLInputFactory {
* <p>
* Once an application has obtained a reference to a XMLInputFactory it
* can use the factory to configure and obtain stream instances.
* </p>
* <p>
* 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
* the deprecated method.
* </p>
*
* @throws FactoryConfigurationError in case of {@linkplain
* java.util.ServiceConfigurationError service configuration error} or if
* the implementation is not available or cannot be instantiated.
@ -245,7 +244,6 @@ public abstract class XMLInputFactory {
* <p>
* This method uses the following ordered lookup procedure to determine
* the XMLInputFactory implementation class to load:
* <p>
* <ul>
* <li>
* <p>
@ -488,7 +486,6 @@ public abstract class XMLInputFactory {
* <p>
* All implementations that implement JAXP 1.5 or newer are required to
* support the {@link javax.xml.XMLConstants#ACCESS_EXTERNAL_DTD} property.
* </p>
* <ul>
* <li>
* <p>
@ -497,7 +494,7 @@ public abstract class XMLInputFactory {
* due to the restriction of this property, {@link javax.xml.stream.XMLStreamException}
* will be thrown by the {@link javax.xml.stream.XMLStreamReader#next()} or
* {@link javax.xml.stream.XMLEventReader#nextEvent()} method.
* </p>
*
* </li>
* </ul>
* @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>Required</th>
* </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>
* </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:
* <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.
* The default value is false. </p>
* The default value is false.
*
* <p>If a writer isRepairingNamespaces it will create a namespace declaration
* 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
* on the current StartElement. If the defaultNamespace is bound and in scope
* 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
* 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
* 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
* following attributes have their prefixes replaced with a
* 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
* bound to a different URI than that inherited from the
* namespace context of the parent of that element and there
* 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
* there is a namespace declaration that binds that prefix
* to a different URI then that namespace declaration is
* either removed if the correct mapping is inherited from
* 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
* @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
* following ordered lookup procedure to determine the XMLOutputFactory
* implementation class to load:
* <p>
* <ul>
* <li>
* Use the javax.xml.stream.XMLOutputFactory system property.
@ -177,6 +177,7 @@ public abstract class XMLOutputFactory {
* <p>
* Otherwise, the system-default implementation is returned.
* </li>
* </ul>
* <p>
* Once an application has obtained a reference to a XMLOutputFactory it
* can use the factory to configure and obtain stream instances.
@ -222,7 +223,6 @@ public abstract class XMLOutputFactory {
* <p>
* This method uses the following ordered lookup procedure to determine
* the XMLOutputFactory implementation class to load:
* <p>
* <ul>
* <li>
* 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.
* When the current event is a DTD the following call will return a
* 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:
* <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
* are defined to return null if the information is not available.
*
@ -97,12 +97,13 @@ import javax.xml.namespace.QName;
* getElementText(), nextTag()
* </td>
* </tr>
* <tr>
* <td> ATTRIBUTE </td>
* <td> next(), nextTag()
* getAttributeXXX(), isAttributeSpecified(),
* </td>
* </tr>
* </tr>
* <tr>
* <td> NAMESPACE </td>
* <td> next(), nextTag()
* 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.
*
* <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>
* 1- the comment (COMMENT)<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>
* 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
* 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.
* @see javax.xml.stream.events.XMLEvent
* @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
*/
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
* not a text-only element.
* Regardless of value of javax.xml.stream.isCoalescing this method always returns coalesced content.
* <br /> Precondition: the current event is START_ELEMENT.
* <br /> Postcondition: the current event is the corresponding END_ELEMENT.
* <br> Precondition: the current event is START_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):
* <pre>
* if(getEventType() != XMLStreamConstants.START_ELEMENT) {
* throw new XMLStreamException(
* "parser must be on START_ELEMENT to read next text", getLocation());
* throw new XMLStreamException(
* "parser must be on START_ELEMENT to read next text", getLocation());
* }
*
* int eventType = next();
* StringBuffer content = new StringBuffer();
* while(eventType != XMLStreamConstants.END_ELEMENT ) {
* if(eventType == XMLStreamConstants.CHARACTERS
* || eventType == XMLStreamConstants.CDATA
* || eventType == XMLStreamConstants.SPACE
* || eventType == XMLStreamConstants.ENTITY_REFERENCE) {
* buf.append(getText());
* } else if(eventType == XMLStreamConstants.PROCESSING_INSTRUCTION
* || eventType == XMLStreamConstants.COMMENT) {
* // skipping
* } else if(eventType == XMLStreamConstants.END_DOCUMENT) {
* throw new XMLStreamException(
* "unexpected end of document when reading element text content", this);
* } else if(eventType == XMLStreamConstants.START_ELEMENT) {
* throw new XMLStreamException(
* "element text content may not contain START_ELEMENT", getLocation());
* } else {
* throw new XMLStreamException(
* "Unexpected event type "+eventType, getLocation());
* }
* eventType = next();
* while(eventType != XMLStreamConstants.END_ELEMENT) {
* if(eventType == XMLStreamConstants.CHARACTERS
* || eventType == XMLStreamConstants.CDATA
* || eventType == XMLStreamConstants.SPACE
* || eventType == XMLStreamConstants.ENTITY_REFERENCE) {
* buf.append(getText());
* } else if(eventType == XMLStreamConstants.PROCESSING_INSTRUCTION
* || eventType == XMLStreamConstants.COMMENT) {
* // skipping
* } else if(eventType == XMLStreamConstants.END_DOCUMENT) {
* throw new XMLStreamException(
* "unexpected end of document when reading element text content", this);
* } else if(eventType == XMLStreamConstants.START_ELEMENT) {
* throw new XMLStreamException(
* "element text content may not contain START_ELEMENT", getLocation());
* } else {
* throw new XMLStreamException(
* "Unexpected event type "+eventType, getLocation());
* }
* eventType = next();
* }
* return buf.toString();
* </pre>
@ -268,33 +270,33 @@ public interface XMLStreamReader extends XMLStreamConstants {
* are encountered, an exception is thrown. This method should
* be used when processing element-only content seperated by white space.
*
* <br /> Precondition: none
* <br /> Postcondition: the current event is START_ELEMENT or END_ELEMENT
* <br> Precondition: none
* <br> Postcondition: the current event is START_ELEMENT or END_ELEMENT
* 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):
* <pre>
* <pre> {@code
* int eventType = next();
* while((eventType == XMLStreamConstants.CHARACTERS &amp;&amp; isWhiteSpace()) // skip whitespace
* || (eventType == XMLStreamConstants.CDATA &amp;&amp; isWhiteSpace())
* while((eventType == XMLStreamConstants.CHARACTERS && isWhiteSpace()) // skip whitespace
* || (eventType == XMLStreamConstants.CDATA && isWhiteSpace())
* // skip whitespace
* || eventType == XMLStreamConstants.SPACE
* || eventType == XMLStreamConstants.PROCESSING_INSTRUCTION
* || eventType == XMLStreamConstants.COMMENT
* ) {
* eventType = next();
* eventType = next();
* }
* if (eventType != XMLStreamConstants.START_ELEMENT &amp;&amp; eventType != XMLStreamConstants.END_ELEMENT) {
* throw new String XMLStreamException("expected start or end tag", getLocation());
* if (eventType != XMLStreamConstants.START_ELEMENT && eventType != XMLStreamConstants.END_ELEMENT) {
* throw new String XMLStreamException("expected start or end tag", getLocation());
* }
* return eventType;
* return eventType; }
* </pre>
*
* @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,
* 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;
@ -309,7 +311,7 @@ public interface XMLStreamReader extends XMLStreamConstants {
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.
* @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.
* Otherwise, subsequent calls need to be made until all text has been retrieved. For example:
*
*<code>
* <pre>{@code
* int length = 1024;
* char[] myBuffer = new char[ length ];
*
@ -553,7 +555,7 @@ public interface XMLStreamReader extends XMLStreamConstants {
* if (nCopied < length)
* break;
* }
* </code>
* } </pre>
* 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",
* 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
* @return the number of characters actually copied
* @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 length < 0 or targetStart + length > length of target
* @throws IndexOutOfBoundsException if targetStart {@literal <} 0 or {@literal >} than the 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 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
* 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
* 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.
*
* Each NAMESPACE
@ -44,12 +44,12 @@ import javax.xml.namespace.NamespaceContext;
* <table border="1" cellpadding="2" cellspacing="0">
* <thead>
* <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>
* <th>Method</th> <!-- method -->
* <th colspan="2"><code>isRepairingNamespaces</code> == true</th>
* <th colspan="2"><code>isRepairingNamespaces</code> == false</th>
* <th colspan="2">{@code isRepairingNamespaces} == true</th>
* <th colspan="2">{@code isRepairingNamespaces} == false</th>
* </tr>
* <tr>
* <th></th> <!-- method -->
@ -62,7 +62,7 @@ import javax.xml.namespace.NamespaceContext;
*
* <tbody>
* <tr>
* <th><code>writeAttribute(namespaceURI, localName, value)</code></th>
* <th>{@code writeAttribute(namespaceURI, localName, value)}</th>
* <!-- isRepairingNamespaces == true -->
* <td>
* <!-- namespaceURI bound -->
@ -79,19 +79,19 @@ import javax.xml.namespace.NamespaceContext;
* </td>
* <td>
* <!-- namespaceURI unbound -->
* <code>XMLStreamException</code>
* {@code XMLStreamException}
* </td>
* </tr>
*
* <tr>
* <th><code>writeAttribute(prefix, namespaceURI, localName, value)</code></th>
* <th>{@code writeAttribute(prefix, namespaceURI, localName, value)}</th>
* <!-- isRepairingNamespaces == true -->
* <td>
* <!-- namespaceURI bound -->
* bound to same prefix:<br />
* prefix:localName="value"&nbsp;<sup>[1]</sup><br />
* <br />
* bound to different prefix:<br />
* bound to same prefix:<br>
* prefix:localName="value"&nbsp;<sup>[1]</sup><br>
* <br>
* bound to different prefix:<br>
* xmlns:{generated}="namespaceURI" {generated}:localName="value"
* </td>
* <td>
@ -101,11 +101,11 @@ import javax.xml.namespace.NamespaceContext;
* <!-- isRepairingNamespaces == false -->
* <td>
* <!-- namespaceURI bound -->
* bound to same prefix:<br />
* prefix:localName="value"&nbsp;<sup>[1][2]</sup><br />
* <br />
* bound to different prefix:<br />
* <code>XMLStreamException</code><sup>[2]</sup>
* bound to same prefix:<br>
* prefix:localName="value"&nbsp;<sup>[1][2]</sup><br>
* <br>
* bound to different prefix:<br>
* {@code XMLStreamException}<sup>[2]</sup>
* </td>
* <td>
* <!-- namespaceURI unbound -->
@ -114,58 +114,58 @@ import javax.xml.namespace.NamespaceContext;
* </tr>
*
* <tr>
* <th><code>writeStartElement(namespaceURI, localName)</code><br />
* <br />
* <code>writeEmptyElement(namespaceURI, localName)</code></th>
* <th>{@code writeStartElement(namespaceURI, localName)}<br>
* <br>
* {@code writeEmptyElement(namespaceURI, localName)}</th>
* <!-- isRepairingNamespaces == true -->
* <td >
* <!-- namespaceURI bound -->
* &lt;prefix:localName&gt;&nbsp;<sup>[1]</sup>
* {@code <prefix:localName>}&nbsp;<sup>[1]</sup>
* </td>
* <td>
* <!-- namespaceURI unbound -->
* &lt;{generated}:localName xmlns:{generated}="namespaceURI"&gt;
* {@code <{generated}:localName xmlns:{generated}="namespaceURI">}
* </td>
* <!-- isRepairingNamespaces == false -->
* <td>
* <!-- namespaceURI bound -->
* &lt;prefix:localName&gt;&nbsp;<sup>[1]</sup>
* {@code prefix:localName>}&nbsp;<sup>[1]</sup>
* </td>
* <td>
* <!-- namespaceURI unbound -->
* <code>XMLStreamException</code>
* {@code XMLStreamException}
* </td>
* </tr>
*
* <tr>
* <th><code>writeStartElement(prefix, localName, namespaceURI)</code><br />
* <br />
* <code>writeEmptyElement(prefix, localName, namespaceURI)</code></th>
* <th>{@code writeStartElement(prefix, localName, namespaceURI)}<br>
* <br>
* {@code writeEmptyElement(prefix, localName, namespaceURI)}</th>
* <!-- isRepairingNamespaces == true -->
* <td>
* <!-- namespaceURI bound -->
* bound to same prefix:<br />
* &lt;prefix:localName&gt;&nbsp;<sup>[1]</sup><br />
* <br />
* bound to different prefix:<br />
* &lt;{generated}:localName xmlns:{generated}="namespaceURI"&gt;
* bound to same prefix:<br>
* {@code <prefix:localName>}&nbsp;<sup>[1]</sup><br>
* <br>
* bound to different prefix:<br>
* {@code <{generated}:localName xmlns:{generated}="namespaceURI">}
* </td>
* <td>
* <!-- namespaceURI unbound -->
* &lt;prefix:localName xmlns:prefix="namespaceURI"&gt;&nbsp;<sup>[4]</sup>
* {@code <prefix:localName xmlns:prefix="namespaceURI">}&nbsp;<sup>[4]</sup>
* </td>
* <!-- isRepairingNamespaces == false -->
* <td>
* <!-- namespaceURI bound -->
* bound to same prefix:<br />
* &lt;prefix:localName&gt;&nbsp;<sup>[1]</sup><br />
* <br />
* bound to different prefix:<br />
* <code>XMLStreamException</code>
* bound to same prefix:<br>
* {@code <prefix:localName>}&nbsp;<sup>[1]</sup><br>
* <br>
* bound to different prefix:<br>
* {@code XMLStreamException}
* </td>
* <td>
* <!-- namespaceURI unbound -->
* &lt;prefix:localName&gt;&nbsp;
* {@code <prefix:localName>}&nbsp;
* </td>
* </tr>
* </tbody>
@ -175,10 +175,14 @@ import javax.xml.namespace.NamespaceContext;
* Notes:
* <ul>
* <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>[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>[5] if prefix == "" || null, then it is treated as an invalid attempt to define the default Namespace and an XMLStreamException is thrown</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>[5] if prefix == "" || null, then it is treated as an invalid attempt to
* define the default Namespace and an XMLStreamException is thrown</li>
* </ul>
* </td>
* </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
* 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>
* @since 1.4
@ -38,7 +38,7 @@ public interface Result {
* The name of the processing instruction that is sent if the
* 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.
* This ensures that the output is well-formed XML. However,
* 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
* be transformed into well-formed XML by a subsequent non-XML aware
* 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
* 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>
*/
@ -71,7 +71,7 @@ public interface Result {
*
* <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
* 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.
*/

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
* {@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
* 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
* {@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:Neeraj.Bajaj@sun.com">Neeraj Bajaj</a>
@ -51,14 +51,11 @@ public abstract class TransformerFactory {
/**
* <p>
* Obtain a new instance of a {@code TransformerFactory}.
* This static method creates a new factory instance.
* <p>
* This method uses the following ordered lookup procedure to determine
* the {@code TransformerFactory} implementation class to
* load:
* <p>
* the {@code TransformerFactory} implementation class to load:
* <ul>
* <li>
* 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.
* 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 TransformerFactory} it can use the factory to configure
* and obtain transformer instances.</p>
* and obtain transformer instances.
*
* <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
* 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>
* java -Djaxp.debug=1 YourProgram ....
* </pre>
*
* @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>
* current <code>Thread</code>'s context classLoader is used to load the factory class.
* @param classLoader {@code ClassLoader} used to load the factory class. If {@code null}
* current {@code Thread}'s context classLoader is used to load the factory class.
*
* @return new TransformerFactory instance, never null.
*
* @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.
*
* @see #newInstance()
@ -160,29 +157,29 @@ public abstract class TransformerFactory {
factoryClassName, classLoader, false, false);
}
/**
* <p>Process the <code>Source</code> into a <code>Transformer</code>
* <code>Object</code>. The <code>Source</code> is an XSLT document that
* Process the {@code Source} into a {@code Transformer}
* {@code Object}. The {@code Source} is an XSLT document that
* conforms to <a href="http://www.w3.org/TR/xslt">
* XSL Transformations (XSLT) Version 1.0</a>. Care must
* be taken not to use this <code>Transformer</code> in multiple
* <code>Thread</code>s running concurrently.
* Different <code>TransformerFactories</code> can be used concurrently by
* different <code>Thread</code>s.</p>
* be taken not to use this {@code Transformer} in multiple
* {@code Thread}s running concurrently.
* Different {@code TransformerFactories} can be used concurrently by
* different {@code Thread}s.
*
* @param source <code>Source </code> of XSLT document used to create
* <code>Transformer</code>.
* Examples of XML <code>Source</code>s include
* @param source {@code Source } of XSLT document used to create
* {@code Transformer}.
* Examples of XML {@code Source}s include
* {@link javax.xml.transform.dom.DOMSource DOMSource},
* {@link javax.xml.transform.sax.SAXSource SAXSource}, and
* {@link javax.xml.transform.stream.StreamSource StreamSource}.
*
* @return A <code>Transformer</code> object that may be used to perform
* a transformation in a single <code>Thread</code>, never
* <code>null</code>.
* @return A {@code Transformer} object that may be used to perform
* a transformation in a single {@code Thread}, never
* {@code null}.
*
* @throws TransformerConfigurationException Thrown if there are errors when
* parsing the <code>Source</code> or it is not possible to create a
* <code>Transformer</code> instance.
* parsing the {@code Source} or it is not possible to create a
* {@code Transformer} instance.
*
* @see <a href="http://www.w3.org/TR/xslt">
* XSL Transformations (XSLT) Version 1.0</a>
@ -191,15 +188,15 @@ public abstract class TransformerFactory {
throws TransformerConfigurationException;
/**
* <p>Create a new <code>Transformer</code> that performs a copy
* of the <code>Source</code> to the <code>Result</code>.
* i.e. the "<em>identity transform</em>".</p>
* Create a new {@code Transformer} that performs a copy
* of the {@code Source} to the {@code Result}.
* i.e. the "<em>identity transform</em>".
*
* @return A Transformer object that may be used to perform a transformation
* in a single thread, never null.
*
* @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()
throws TransformerConfigurationException;
@ -215,7 +212,7 @@ public abstract class TransformerFactory {
* @param source An object that holds a URL, input stream, etc.
*
* @return A Templates object capable of being used for transformation
* purposes, never <code>null</code>.
* purposes, never {@code null}.
*
* @throws TransformerConfigurationException When parsing to
* construct the Templates object fails.
@ -224,13 +221,13 @@ public abstract class TransformerFactory {
throws TransformerConfigurationException;
/**
* <p>Get the stylesheet specification(s) associated with the
* XML <code>Source</code> document via the
* Get the stylesheet specification(s) associated with the
* XML {@code Source} document via the
* <a href="http://www.w3.org/TR/xml-stylesheet/">
* xml-stylesheet processing instruction</a> that match the given criteria.
* 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
* single stylesheet.</p>
* single stylesheet.
*
* @param source The XML source document.
* @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 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}.
*
* @throws TransformerConfigurationException An <code>Exception</code>
* @throws TransformerConfigurationException An {@code Exception}
* 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/">
* Associating Style Sheets with XML documents Version 1.0</a>
@ -275,22 +272,21 @@ public abstract class TransformerFactory {
//======= CONFIGURATION METHODS =======
/**
* <p>Set a feature for this {@code TransformerFactory} and <code>Transformer</code>s
* or <code>Template</code>s created by this factory.</p>
* <p>Set a feature for this {@code TransformerFactory} and {@code Transformer}s
* or {@code Template}s created by this factory.
*
* <p>
* Feature names are fully qualified {@link java.net.URI}s.
* Implementations may define their own features.
* 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.
* </p>
*
* <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>
* <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.
* 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
@ -298,17 +294,17 @@ public abstract class TransformerFactory {
* See {@link #setErrorListener(ErrorListener listener)}.
* </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.
* </li>
* </ul>
*
* @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}
* or the <code>Transformer</code>s or <code>Template</code>s it creates cannot support this feature.
* @throws NullPointerException If the <code>name</code> parameter is null.
* or the {@code Transformer}s or {@code Template}s it creates cannot support this feature.
* @throws NullPointerException If the {@code name} parameter is null.
*/
public abstract void setFeature(String name, boolean value)
throws TransformerConfigurationException;
@ -319,16 +315,15 @@ public abstract class TransformerFactory {
* <p>
* Feature names are fully qualified {@link java.net.URI}s.
* Implementations may define their own features.
* <code>false</code> is returned if this {@code TransformerFactory} or the
* <code>Transformer</code>s or <code>Template</code>s it creates cannot support the feature.
* {@code false} is returned if this {@code TransformerFactory} or the
* {@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.
* </p>
*
* @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);
@ -336,13 +331,13 @@ public abstract class TransformerFactory {
* Allows the user to set specific attributes on the underlying
* implementation. An attribute in this context is defined to
* 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.
* <p>
* All implementations that implement JAXP 1.5 or newer are required to
* support the {@link javax.xml.XMLConstants#ACCESS_EXTERNAL_DTD} and
* {@link javax.xml.XMLConstants#ACCESS_EXTERNAL_STYLESHEET} properties.
* </p>
*
* <ul>
* <li>
* <p>
@ -351,7 +346,7 @@ public abstract class TransformerFactory {
* 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.Transformer#transform(Source, Result)}.
* </p>
*
* <p>
* Access to external DTDs in the stylesheet is restricted to the protocols
* specified by the {@link javax.xml.XMLConstants#ACCESS_EXTERNAL_DTD} property.
@ -359,7 +354,7 @@ public abstract class TransformerFactory {
* restriction of this property,
* {@link javax.xml.transform.TransformerConfigurationException} will be thrown
* by the {@link #newTransformer(Source)} method.
* </p>
*
* <p>
* Access to external reference set by the stylesheet processing instruction,
* Import and Include element is restricted to the protocols specified by the
@ -368,14 +363,14 @@ public abstract class TransformerFactory {
* restriction of this property,
* {@link javax.xml.transform.TransformerConfigurationException} will be thrown
* by the {@link #newTransformer(Source)} method.
* </p>
*
* <p>
* Access to external document through XSLT document function is restricted
* to the protocols specified by the property. If access is denied during
* the transformation due to the restriction of this property,
* {@link javax.xml.transform.TransformerException} will be thrown by the
* {@link javax.xml.transform.Transformer#transform(Source, Result)} method.
* </p>
*
* </li>
* </ul>
*
@ -390,7 +385,7 @@ public abstract class TransformerFactory {
/**
* Allows the user to retrieve specific attributes on the underlying
* implementation.
* An <code>IllegalArgumentException</code> is thrown if the underlying
* An {@code IllegalArgumentException} is thrown if the underlying
* implementation doesn't recognize 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
* is used for the processing of transformation instructions,
* and not for the transformation itself.
* An <code>IllegalArgumentException</code> is thrown if the
* <code>ErrorListener</code> listener is <code>null</code>.
* An {@code IllegalArgumentException} is thrown if the
* {@code ErrorListener} listener is {@code null}.
*
* @param listener The new error listener.
*
* @throws IllegalArgumentException When <code>listener</code> is
* <code>null</code>
* @throws IllegalArgumentException When {@code listener} is
* {@code null}
*/
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;
/**
* <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,
* which may be retrieved with {@link #getNode()}.</p>
* <p>If no output DOM source is set, the transformation will create
* 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>
* @since 1.4
*/
public class DOMResult implements Result {
/** <p>If {@link javax.xml.transform.TransformerFactory#getFeature}
* returns <code>true</code> when passed this value as an argument,
* the <code>Transformer</code> supports <code>Result</code> output of this type.</p>
/**
* If {@link javax.xml.transform.TransformerFactory#getFeature}
* 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";
/**
* <p>Zero-argument default constructor.</p>
* Zero-argument default constructor.
*
* <p><code>node</code>,
* <code>siblingNode</code> and
* <code>systemId</code>
* will be set to <code>null</code>.</p>
* <p>{@code node},
* {@code siblingNode} and
* {@code systemId}
* will be set to {@code null}.
*/
public DOMResult() {
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
* a {@link org.w3c.dom.Document} node,
* a {@link org.w3c.dom.DocumentFragment} node, or
* 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
* <code>systemId</code>
* will be set to <code>null</code>.</p>
* <p>{@code siblingNode} and
* {@code systemId}
* will be set to {@code null}.
*
* @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
* a {@link org.w3c.dom.Document} node,
* a {@link org.w3c.dom.DocumentFragment} node, or
* 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 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.DocumentFragment} node, or
* 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.
* If <code>nextSibling</code> is not a sibling of <code>node</code>,
* then an <code>IllegalArgumentException</code> is thrown.
* If <code>node</code> is <code>null</code> and <code>nextSibling</code> is not <code>null</code>,
* then an <code>IllegalArgumentException</code> is thrown.
* If <code>nextSibling</code> is <code>null</code>,
* If {@code nextSibling} is not a sibling of {@code node},
* then an {@code IllegalArgumentException} is thrown.
* If {@code node} is {@code null} and {@code nextSibling} is not {@code null},
* then an {@code IllegalArgumentException} is thrown.
* If {@code nextSibling} is {@code null},
* 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 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
* <code>node</code> is <code>null</code> and <code>nextSibling</code>
* is not <code>null</code>.
* @throws IllegalArgumentException If {@code nextSibling} is not a sibling of {@code node} or
* {@code node} is {@code null} and {@code nextSibling}
* is not {@code null}.
*
* @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
* the specified System ID.</p>
* Use a DOM node to create a new output target specifying the child
* 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.DocumentFragment} node, or 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.
* If <code>nextSibling</code> is not a sibling of <code>node</code>,
* then an <code>IllegalArgumentException</code> is thrown.
* If <code>node</code> is <code>null</code> and <code>nextSibling</code> is not <code>null</code>,
* then an <code>IllegalArgumentException</code> is thrown.
* If <code>nextSibling</code> is <code>null</code>,
* If {@code nextSibling} is not a sibling of {@code node},
* then an {@code IllegalArgumentException} is thrown.
* If {@code node} is {@code null} and {@code nextSibling} is not {@code null},
* then an {@code IllegalArgumentException} is thrown.
* If {@code nextSibling} is {@code null},
* 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 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.
*
* @throws IllegalArgumentException If <code>nextSibling</code> is not a
* sibling of <code>node</code> or
* <code>node</code> is <code>null</code> and <code>nextSibling</code>
* is not <code>null</code>.
* @throws IllegalArgumentException If {@code nextSibling} is not a
* sibling of {@code node} or
* {@code node} is {@code null} and {@code nextSibling}
* is not {@code null}.
*
* @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
* a {@link org.w3c.dom.Document} node,
* a {@link org.w3c.dom.DocumentFragment} node, or
* 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
* <code>nextSibling</code> is not <code>null</code> and
* <code>node</code> is not a parent of <code>nextSibling</code>.
* An <code>IllegalStateException</code> is thrown if <code>node</code> is <code>null</code> and
* <code>nextSibling</code> is not <code>null</code>.</p>
* <p>An {@code IllegalStateException} is thrown if
* {@code nextSibling} is not {@code null} and
* {@code node} is not a parent of {@code nextSibling}.
* An {@code IllegalStateException} is thrown if {@code node} is {@code null} and
* {@code nextSibling} is not {@code null}.
*
* @param node The node to which the transformation will be appended.
*
* @throws IllegalStateException If <code>nextSibling</code> is not
* <code>null</code> and
* <code>nextSibling</code> is not a child of <code>node</code> or
* <code>node</code> is <code>null</code> and
* <code>nextSibling</code> is not <code>null</code>.
* @throws IllegalStateException If {@code nextSibling} is not
* {@code null} and
* {@code nextSibling} is not a child of {@code node} or
* {@code node} is {@code null} and
* {@code nextSibling} is not {@code null}.
*/
public void setNode(Node node) {
// 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
* {@link #DOMResult(Node node)},
@ -251,7 +257,7 @@ public class DOMResult implements Result {
* {@link #DOMResult(Node node, Node nextSibling, String systemId)} or
* {@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.
* 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.
*/
@ -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.
* If <code>nextSibling</code> is not a descendant of <code>node</code>,
* then an <code>IllegalArgumentException</code> is thrown.
* If <code>node</code> is <code>null</code> and <code>nextSibling</code> is not <code>null</code>,
* then an <code>IllegalStateException</code> is thrown.
* If <code>nextSibling</code> is <code>null</code>,
* If {@code nextSibling} is not a descendant of {@code node},
* then an {@code IllegalArgumentException} is thrown.
* If {@code node} is {@code null} and {@code nextSibling} is not {@code null},
* then an {@code IllegalStateException} is thrown.
* If {@code nextSibling} is {@code null},
* 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.
*
* @throws IllegalArgumentException If <code>nextSibling</code> is not a
* descendant of <code>node</code>.
* @throws IllegalStateException If <code>node</code> is <code>null</code>
* and <code>nextSibling</code> is not <code>null</code>.
* @throws IllegalArgumentException If {@code nextSibling} is not a
* descendant of {@code node}.
* @throws IllegalStateException If {@code node} is {@code null}
* and {@code nextSibling} is not {@code null}.
*
* @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
* {@link #DOMResult(Node node, Node nextSibling)},
* {@link #DOMResult(Node node, Node nextSibling, String systemId)} or
* {@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.
*
@ -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.
*/
@ -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
* {@link #DOMResult(Node node, String systemId)},
* {@link #DOMResult(Node node, Node nextSibling, String systemId)} or
* {@link #setSystemId(String systemId)},
* then <code>null</code> will be returned.</p>
* then {@code null} will be returned.
*
* @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;
/**
* <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
*/
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;
}

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

@ -65,9 +65,6 @@ questions.
<li>@see XMLEventReader</li>
</ul>
<p>
@since 1.6
</p>
@since 1.6
</body>
</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;
/**
* Factory that creates {@link Schema} objects&#x2E; Entry-point to
* Factory that creates {@link Schema} objects. Entry-point to
* the validation API.
*
* <p>
@ -49,12 +49,12 @@ import org.xml.sax.SAXParseException;
* it is the application's responsibility to ensure that at most
* one thread is using a {@link SchemaFactory} object at any
* 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>
* {@link SchemaFactory} is not re-entrant. While one of the
* <code>newSchema</code> methods is being invoked, applications
* may not attempt to recursively invoke the <code>newSchema</code> method,
* {@code newSchema} methods is being invoked, applications
* may not attempt to recursively invoke the {@code newSchema} method,
* even from the same thread.
*
* <h2><a name="schemaLanguage"></a>Schema Language</h2>
@ -92,11 +92,11 @@ import org.xml.sax.SAXParseException;
* </thead>
* <tbody>
* <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>
* </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>
* </tr>
* </tbody>
@ -112,24 +112,24 @@ public abstract class SchemaFactory {
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
* <code>null</code> {@link ErrorHandler} and
* <code>null</code> {@link LSResourceResolver}.</p>
* {@code null} {@link ErrorHandler} and
* {@code null} {@link LSResourceResolver}.
*/
protected SchemaFactory() {
}
/**
* <p>Lookup an implementation of the <code>SchemaFactory</code> that supports the specified
* schema language and return it.</p>
* Lookup an implementation of the {@code SchemaFactory} that supports the specified
* 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
* where "the class loader" refers to the context class loader:</p>
* where "the class loader" refers to the context class loader:
* <ol>
* <li>
* <p>
@ -178,9 +178,9 @@ public abstract class SchemaFactory {
* </li>
* <li>
* <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
* <code>SchemaFactory</code> for W3C XML Schema.
* {@code SchemaFactory} for W3C XML Schema.
* </li>
* </ol>
*
@ -201,12 +201,12 @@ public abstract class SchemaFactory {
* <a href="#schemaLanguage">the list of available
* schema languages</a> for the possible values.
*
* @return New instance of a <code>SchemaFactory</code>
* @return New instance of a {@code SchemaFactory}
*
* @throws IllegalArgumentException
* If no implementation of the schema language is available.
* @throws NullPointerException
* If the <code>schemaLanguage</code> parameter is null.
* If the {@code schemaLanguage} parameter is null.
* @throws SchemaFactoryConfigurationError
* 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.
* 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
* should be loaded.</p>
* should be loaded.
*
* <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
* 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>
* java -Djaxp.debug=1 YourProgram ....
* </pre>
*
* @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
* 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>
* current <code>Thread</code>'s context classLoader is used to load the factory class.
* @param classLoader {@code ClassLoader} used to load the factory class. If {@code null}
* 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
* 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
* support the schema language specified in <code>schemLanguage</code>
* support the schema language specified in {@code schemLanguage}
* parameter.
*
* @throws NullPointerException
* If the <code>schemaLanguage</code> parameter is null.
* If the {@code schemaLanguage} parameter is null.
*
* @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.
* <code>schemaLanguage</code> must specify a <a href="#schemaLanguage">valid</a> schema language.
* @param schemaLanguage Specifies the schema language which the returned {@code SchemaFactory} will understand.
* {@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 IllegalArgumentException If <code>schemaLanguage.length() == 0</code>
* or <code>schemaLanguage</code> does not specify a <a href="#schemaLanguage">valid</a> schema language.
* @throws NullPointerException If {@code schemaLanguage} is {@code null}.
* @throws IllegalArgumentException If {@code schemaLanguage.length() == 0}
* or {@code schemaLanguage} does not specify a <a href="#schemaLanguage">valid</a> schema language.
*/
public abstract boolean isSchemaLanguageSupported(String schemaLanguage);
@ -320,7 +320,7 @@ public abstract class SchemaFactory {
* temporarily be unable to return its value.
*
* <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.
*
@ -331,7 +331,7 @@ public abstract class SchemaFactory {
* @throws SAXNotSupportedException When the
* {@link SchemaFactory} recognizes the feature name but
* 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)
*/
@ -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 Validator}s and {@link ValidatorHandler}s created by
* those {@link Schema}s.
* </p>
*
* <p>Implementors and developers should pay particular attention
* to how the special {@link Schema} object returned by {@link
* #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
* for <code>SchemaFactory</code> features to be inherited automatically.
* for {@code SchemaFactory} features to be inherited automatically.
* Developers should
* 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
* 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.
* When the feature is:</p>
* When the feature is:
* <ul>
* <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.
* If XML processing is limited for security reasons, it will be reported via a call to the registered
* {@link ErrorHandler#fatalError(SAXParseException exception)}.
* See {@link #setErrorHandler(ErrorHandler errorHandler)}.
* </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.
* </li>
* </ul>
@ -389,7 +388,7 @@ public abstract class SchemaFactory {
* @throws SAXNotSupportedException When the
* {@link SchemaFactory} recognizes the feature name but
* 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)
*/
@ -405,15 +404,15 @@ public abstract class SchemaFactory {
/**
* 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
* to be unable to change the current value.</p>
* to be unable to change the current value.
*
* <p>
* All implementations that implement JAXP 1.5 or newer are required to
* support the {@link javax.xml.XMLConstants#ACCESS_EXTERNAL_DTD} and
* {@link javax.xml.XMLConstants#ACCESS_EXTERNAL_SCHEMA} properties.
* </p>
*
* <ul>
* <li>
* <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
* of this property, {@link org.xml.sax.SAXException} will be thrown by the
* {@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
* specified by the {@link javax.xml.XMLConstants#ACCESS_EXTERNAL_DTD} 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 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
* 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,
* {@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, Result)} method.</p>
* {@link javax.xml.validation.Validator#validate(Source, Result)} method.
*
* <p>Access to external reference set by the Import
* 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
* of this property, {@link org.xml.sax.SAXException} will be thrown by the
* {@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>
* </ul>
*
@ -456,7 +455,7 @@ public abstract class SchemaFactory {
* @throws SAXNotSupportedException When the
* {@link SchemaFactory} recognizes the property name but
* 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)
throws SAXNotRecognizedException, SAXNotSupportedException {
@ -472,13 +471,13 @@ public abstract class SchemaFactory {
*
* <p>The property name is any fully-qualified URI. It is
* 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
* property names.</p>
* property names.
*
* <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.
*
@ -489,7 +488,7 @@ public abstract class SchemaFactory {
* @throws SAXNotSupportedException When the
* XMLReader recognizes the property name but
* 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)
*/
@ -504,7 +503,7 @@ public abstract class SchemaFactory {
/**
* Sets the {@link ErrorHandler} to receive errors encountered
* during the <code>newSchema</code> method invocation.
* during the {@code newSchema} method invocation.
*
* <p>
* Error handler can be used to customize the error handling process
@ -521,7 +520,7 @@ public abstract class SchemaFactory {
* <p>
* If any {@link Throwable} (or instances of its derived classes)
* 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.
*
* <p>
@ -557,7 +556,7 @@ public abstract class SchemaFactory {
* {@link ValidatorHandler}s that are created from this {@link SchemaFactory}.
*
* @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);
@ -583,7 +582,7 @@ public abstract class SchemaFactory {
* when it needs to locate external resources while parsing schemas,
* although exactly what constitutes "locating external resources" is
* 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.
*
* <p>
@ -607,7 +606,7 @@ public abstract class SchemaFactory {
* If a {@link LSResourceResolver} throws a {@link RuntimeException}
* (or instances of its derived classes),
* 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}.
*
* <p>
@ -635,48 +634,48 @@ public abstract class SchemaFactory {
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.
*
* @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 NullPointerException if <code>schema</code> is null.
* @throws NullPointerException if {@code schema} is null.
*/
public Schema newSchema(Source schema) throws SAXException {
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.
*
* @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 NullPointerException if <code>schema</code> is null.
* @throws NullPointerException if {@code schema} is null.
*/
public Schema newSchema(File schema) throws SAXException {
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 NullPointerException if <code>schema</code> is null.
* @throws NullPointerException if {@code schema} is null.
*/
public Schema newSchema(URL schema) throws SAXException {
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
* JAXP schema sources and XML Schema imports, the behaviour between
* 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.
*
* <p>
@ -721,7 +720,7 @@ public abstract class SchemaFactory {
* <h2>RELAX NG</h2>
*
* <p>For RELAX NG, this method must throw {@link UnsupportedOperationException}
* if <code>schemas.length!=1</code>.
* if {@code schemas.length!=1}.
*
*
* @param schemas
@ -748,7 +747,7 @@ public abstract class SchemaFactory {
* When an {@link ErrorHandler} is set, errors are reported to
* there first. See {@link #setErrorHandler(ErrorHandler)}.
* @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.
* @throws IllegalArgumentException
* If any item in the array is not recognized by this method.
@ -765,7 +764,7 @@ public abstract class SchemaFactory {
* is created.
*
* <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
* 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.
* Developers should
* 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>
* <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;
/**
* <p>A processor that checks an XML document against {@link Schema}.</p>
* A processor that checks an XML document against {@link Schema}.
*
* <p>
* A validator object is not thread-safe and not reentrant.
* In other words, it is the application's responsibility to make
* 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
* the <code>validate</code> method.
* <p>
* the {@code validate} method.
*
*
* @author <a href="mailto:Kohsuke.Kawaguchi@Sun.com">Kohsuke Kawaguchi</a>
@ -57,27 +56,28 @@ public abstract class Validator {
/**
* 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
* <code>null</code> {@link ErrorHandler} and
* <code>null</code> {@link LSResourceResolver}.
* </p>
* {@code null} {@link ErrorHandler} and
* {@code null} {@link LSResourceResolver}.
*/
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()}.
* <code>reset()</code> is designed to allow the reuse of existing <code>Validator</code>s
* thus saving resources associated with the creation of new <code>Validator</code>s.</p>
* {@code reset()} is designed to allow the reuse of existing {@code Validator}s
* 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}
* <code>Object</code>s, e.g. {@link Object#equals(Object obj)}. It is guaranteed to have a functionally equal
* <code>LSResourceResolver</code> and <code>ErrorHandler</code>.</p>
* <p>The reset {@code Validator} is not guaranteed to have
* the same {@link LSResourceResolver} or {@link ErrorHandler}
* {@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();
@ -86,7 +86,7 @@ public abstract class Validator {
*
* <p>This is just a convenience method for
* {@link #validate(Source source, Result result)}
* with <code>result</code> of <code>null</code>.</p>
* with {@code result} of {@code null}.
*
* @param source
* XML to be validated. Must be an XML document or
@ -97,7 +97,7 @@ public abstract class Validator {
* or throw an IllegalArgumentException.
*
* @throws IllegalArgumentException
* If the <code>Source</code>
* If the {@code Source}
* is an XML artifact that the implementation cannot
* validate (for example, a processing instruction).
*
@ -113,8 +113,8 @@ public abstract class Validator {
* {@link IOException}.
*
*
* @throws NullPointerException If <code>source</code> is
* <code>null</code>.
* @throws NullPointerException If {@code source} is
* {@code null}.
*
* @see #validate(Source source, Result result)
*/
@ -125,16 +125,16 @@ public abstract class Validator {
}
/**
* <p>Validates the specified input and send the augmented validation
* result to the specified output.</p>
* Validates the specified input and send the augmented validation
* result to the specified output.
*
* <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>
* <thead>
* <tr>
* <th colspan="5"><code>Source</code> / <code>Result</code> Accepted</th>
* <th colspan="5">{@code Source} / {@code Result} Accepted</th>
* </tr>
* <tr>
* <th></th>
@ -146,7 +146,7 @@ public abstract class Validator {
* </thead>
* <tbody align="center">
* <tr>
* <td><code>null</code></td>
* <td>{@code null}</td>
* <td>OK</td>
* <td>OK</td>
* <td>OK</td>
@ -155,44 +155,44 @@ public abstract class Validator {
* <tr>
* <th>{@link javax.xml.transform.stream.StreamResult}</th>
* <td>OK</td>
* <td><code>IllegalArgumentException</code></td>
* <td><code>IllegalArgumentException</code></td>
* <td><code>IllegalArgumentException</code></td>
* <td>{@code IllegalArgumentException}</td>
* <td>{@code IllegalArgumentException}</td>
* <td>{@code IllegalArgumentException}</td>
* </tr>
* <tr>
* <th>{@link javax.xml.transform.sax.SAXResult}</th>
* <td><code>IllegalArgumentException</code></td>
* <td>{@code IllegalArgumentException}</td>
* <td>OK</td>
* <td><code>IllegalArgumentException</code></td>
* <td><code>IllegalArgumentException</code></td>
* <td>{@code IllegalArgumentException}</td>
* <td>{@code IllegalArgumentException}</td>
* </tr>
* <tr>
* <th>{@link javax.xml.transform.dom.DOMResult}</th>
* <td><code>IllegalArgumentException</code></td>
* <td><code>IllegalArgumentException</code></td>
* <td>{@code IllegalArgumentException}</td>
* <td>{@code IllegalArgumentException}</td>
* <td>OK</td>
* <td><code>IllegalArgumentException</code></td>
* <td>{@code IllegalArgumentException}</td>
* </tr>
* <tr>
* <th>{@link javax.xml.transform.stax.StAXResult}</th>
* <td><code>IllegalArgumentException</code></td>
* <td><code>IllegalArgumentException</code></td>
* <td><code>IllegalArgumentException</code></td>
* <td>{@code IllegalArgumentException}</td>
* <td>{@code IllegalArgumentException}</td>
* <td>{@code IllegalArgumentException}</td>
* <td>OK</td>
* </tr>
* </tbody>
* </table>
*
* <p>To validate one <code>Source</code> into another kind of
* <code>Result</code>, use the identity transformer (see
* {@link javax.xml.transform.TransformerFactory#newTransformer()}).</p>
* <p>To validate one {@code Source} into another kind of
* {@code Result}, use the identity transformer (see
* {@link javax.xml.transform.TransformerFactory#newTransformer()}).
*
* <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
* but none of them were fatal and the <code>ErrorHandler</code> didn't
* throw any exception, then the method returns normally.</p>
* but none of them were fatal and the {@code ErrorHandler} didn't
* throw any exception, then the method returns normally.
*
* @param source
* XML to be validated. Must be an XML document or
@ -203,34 +203,34 @@ public abstract class Validator {
* or throw an IllegalArgumentException.
*
* @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
* 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
* <code>DOMSource</code> to <code>DOMResult</code>
* (in which case <code>source.getNode()==result.getNode()</code>),
* {@code DOMSource} to {@code DOMResult}
* (in which case {@code source.getNode()==result.getNode()}),
* it might copy the entire DOM tree, or it might alter the
* node given by the source.
*
* @throws IllegalArgumentException
* If the <code>Result</code> type doesn't match the
* <code>Source</code> type of if the <code>Source</code>
* If the {@code Result} type doesn't match the
* {@code Source} type of if the {@code Source}
* is an XML artifact that the implementation cannot
* validate (for example, a processing instruction).
* @throws SAXException
* If the <code>ErrorHandler</code> throws a
* <code>SAXException</code> or
* if a fatal error is found and the <code>ErrorHandler</code> returns
* If the {@code ErrorHandler} throws a
* {@code SAXException} or
* if a fatal error is found and the {@code ErrorHandler} returns
* normally.
* @throws IOException
* If the validator is processing a
* <code>SAXSource</code> and the
* {@code SAXSource} and the
* underlying {@link org.xml.sax.XMLReader} throws an
* <code>IOException</code>.
* {@code IOException}.
* @throws NullPointerException
* If the <code>source</code> parameter is <code>null</code>.
* If the {@code source} parameter is {@code null}.
*
* @see #validate(Source source)
*/
@ -239,7 +239,7 @@ public abstract class Validator {
/**
* Sets the {@link ErrorHandler} to receive errors encountered
* during the <code>validate</code> method invocation.
* during the {@code validate} method invocation.
*
* <p>
* Error handler can be used to customize the error handling process
@ -255,7 +255,7 @@ public abstract class Validator {
*
* <p>
* 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.
*
* <p>
@ -329,7 +329,7 @@ public abstract class Validator {
* If a {@link LSResourceResolver} throws a {@link RuntimeException}
* (or instances of its derived classes),
* 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}.
*
* <p>
@ -366,7 +366,7 @@ public abstract class Validator {
* contexts, such as before, during, or after a validation.
*
* <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.
*
@ -398,14 +398,14 @@ public abstract class Validator {
* <p>
* Feature can be used to control the way a {@link Validator}
* 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
* possible for a {@link Validator} to expose a feature value but
* to be unable to change the current value.
* Some feature values may be immutable or mutable only
* 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 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.
* Some property values may be immutable or mutable only
* in specific contexts, such as before, during, or after
* a validation.</p>
* a validation.
*
* <p>
* All implementations that implement JAXP 1.5 or newer are required to
* support the {@link javax.xml.XMLConstants#ACCESS_EXTERNAL_DTD} and
* {@link javax.xml.XMLConstants#ACCESS_EXTERNAL_SCHEMA} properties.
* </p>
*
* <ul>
* <li>
* <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}
* 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 #validate(Source)} method.</p>
* {@link #validate(Source)} method.
*
* <p>Access to external reference set by the schemaLocation attribute is
* restricted to the protocols specified by the
* {@link javax.xml.XMLConstants#ACCESS_EXTERNAL_SCHEMA} 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 #validate(Source)} method.</p>
* {@link #validate(Source)} method.
* </li>
* </ul>
*
@ -490,13 +490,13 @@ public abstract class Validator {
* possible for a {@link Validator} to recognize a property name but
* temporarily be unable to return its value.
* 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
* property names.</p>
* property names.
*
* <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.
*

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.
*
* <a name="XPath-evaluation"/>
* <a name="XPath-evaluation"></a>
* <table border="1" cellpadding="2">
* <thead>
* <tr>
@ -90,7 +90,6 @@ import org.xml.sax.InputSource;
* more than one thread at any given time, and while the {@code evaluate}
* method is invoked, applications may not recursively call
* the {@code evaluate} method.
* <p>
*
* @author <a href="Norman.Walsh@Sun.com">Norman Walsh</a>
* @author <a href="Jeff.Suttor@Sun.com">Jeff Suttor</a>
@ -462,7 +461,6 @@ public interface XPath {
* <pre> {@code
* evaluateExpression(expression, item, XPathEvaluationResult.class);
* }</pre>
* <p>
*
* @implSpec
* 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.
* The evaluation of an XPath expression can result in various result types as
* defined in XML Path Language (XPath) Version 1.0.
* <p>
*
* @param <T> the object type returned by the XPath evaluation.
* @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();
/**
* 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.
*/

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;
/**
* <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="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;
/**
* <p>Constructs a new <code>XPathException</code>
* with the specified detail <code>message</code>.</p>
* Constructs a new {@code XPathException}
* 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>,
* then a <code>NullPointerException</code> is thrown.</p>
* <p>If {@code message} is {@code null},
* then a {@code NullPointerException} is thrown.
*
* @param message The detail message.
*
* @throws NullPointerException When <code>message</code> is
* <code>null</code>.
* @throws NullPointerException When {@code message} is
* {@code null}.
*/
public XPathException(String message) {
super(message);
@ -72,15 +72,15 @@ public class XPathException extends Exception {
}
/**
* <p>Constructs a new <code>XPathException</code>
* with the specified <code>cause</code>.</p>
* Constructs a new {@code XPathException}
* with the specified {@code cause}.
*
* <p>If <code>cause</code> is <code>null</code>,
* then a <code>NullPointerException</code> is thrown.</p>
* <p>If {@code cause} is {@code null},
* then a {@code NullPointerException} is thrown.
*
* @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) {
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.
*/
@ -103,7 +103,7 @@ public class XPathException extends Exception {
* The cause is got from the parent class.
*
* @param out stream used for serialization.
* @throws IOException thrown by <code>ObjectOutputStream</code>
* @throws IOException thrown by {@code ObjectOutputStream}
*
*/
private void writeObject(ObjectOutputStream out)
@ -120,8 +120,8 @@ public class XPathException extends Exception {
* done before.
*
* @param in stream used for deserialization
* @throws IOException thrown by <code>ObjectInputStream</code>
* @throws ClassNotFoundException thrown by <code>ObjectInputStream</code>
* @throws IOException thrown by {@code ObjectInputStream}
* @throws ClassNotFoundException thrown by {@code ObjectInputStream}
*/
private void readObject(ObjectInputStream in)
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) {
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() {
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) {

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;
/**
* <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">
* <thead>
* <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}.
* An {@link XPathExpressionException} is raised if the variable resolver is undefined or
* 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>
* </tr>
* <tr>
@ -62,7 +62,7 @@ import org.xml.sax.InputSource;
* <td>
* 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
* the function resolver returns {@code null} for the function.</p>
* the function resolver returns {@code null} for the function.
* </td>
* </tr>
* <tr>
@ -76,9 +76,10 @@ import org.xml.sax.InputSource;
* <td>
* This result of evaluating an expression is converted to an instance of the desired return type.
* 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>
* </tr>
* </tbody>
* </table>
*
* <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}
* method is invoked, applications may not recursively call
* the {@code evaluate} method.
* <p>
*
* @author <a href="mailto:Norman.Walsh@Sun.com">Norman Walsh</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,
* variable, function and QName resolution and return type conversion.</p>
* variable, function and QName resolution and return type conversion.
*
* <p>
* The parameter {@code item} represents the context the XPath expression
@ -126,13 +126,13 @@ public interface XPathExpression {
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
* {@link XPathConstants#STRING}.</p>
* {@link XPathConstants#STRING}.
*
* <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>
* The parameter {@code item} represents the context the XPath expression
@ -153,20 +153,21 @@ public interface XPathExpression {
throws XPathExpressionException;
/**
* <p>Evaluate the compiled XPath expression in the context of the specified {@code InputSource} and return the result as the
* specified type.</p>
* Evaluate the compiled XPath expression in the context
* 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
* {@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,
* 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},
* then an {@code IllegalArgumentException} is thrown.</p>
* then an {@code IllegalArgumentException} is thrown.
*
* <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 returnType The desired return type.
@ -182,16 +183,17 @@ public interface XPathExpression {
throws XPathExpressionException;
/**
* <p>Evaluate the compiled XPath expression in the context of the specified {@code InputSource} and return the result as a
* {@code String}.</p>
* Evaluate the compiled XPath expression in the context
* 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
* {@link XPathConstants#STRING}.</p>
* {@link XPathConstants#STRING}.
*
* <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.
*
@ -351,7 +353,6 @@ public interface XPathExpression {
* <pre> {@code
* evaluateExpression(source, XPathEvaluationResult.class);
* }</pre>
* <p>
*
* @implSpec
* 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;
/**
* <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:Jeff.Suttor@Sun.com">Jeff Suttor</a>
@ -35,38 +35,38 @@ package javax.xml.xpath;
public class XPathExpressionException extends XPathException {
/**
* <p>Stream Unique Identifier.</p>
* Stream Unique Identifier.
*/
private static final long serialVersionUID = -1837080260374986980L;
/**
* <p>Constructs a new <code>XPathExpressionException</code>
* with the specified detail <code>message</code>.</p>
* Constructs a new {@code XPathExpressionException}
* 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>,
* then a <code>NullPointerException</code> is thrown.</p>
* <p>If {@code message} is {@code null},
* then a {@code NullPointerException} is thrown.
*
* @param message The detail message.
*
* @throws NullPointerException When <code>message</code> is
* <code>null</code>.
* @throws NullPointerException When {@code message} is
* {@code null}.
*/
public XPathExpressionException(String message) {
super(message);
}
/**
* <p>Constructs a new <code>XPathExpressionException</code>
* with the specified <code>cause</code>.</p>
* Constructs a new {@code XPathExpressionException}
* with the specified {@code cause}.
*
* <p>If <code>cause</code> is <code>null</code>,
* then a <code>NullPointerException</code> is thrown.</p>
* <p>If {@code cause} is {@code null},
* then a {@code NullPointerException} is thrown.
*
* @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) {
super(cause);

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

@ -26,7 +26,8 @@
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:Jeff.Suttor@Sun.com">Jeff Suttor</a>
@ -35,37 +36,38 @@ package javax.xml.xpath;
public class XPathFactoryConfigurationException extends XPathException {
/**
* <p>Stream Unique Identifier.</p>
* Stream Unique Identifier.
*/
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>,
* then a <code>NullPointerException</code> is thrown.</p>
* <p>If {@code message} is {@code null},
* then a {@code NullPointerException} is thrown.
*
* @param message The detail message.
*
* @throws NullPointerException When <code>message</code> is
* <code>null</code>.
* @throws NullPointerException When {@code message} is
* {@code null}.
*/
public XPathFactoryConfigurationException(String message) {
super(message);
}
/**
* <p>Constructs a new <code>XPathFactoryConfigurationException</code>
* with the specified <code>cause</code>.</p>
* Constructs a new {@code XPathFactoryConfigurationException}
* with the specified {@code cause}.
*
* <p>If <code>cause</code> is <code>null</code>,
* then a <code>NullPointerException</code> is thrown.</p>
* <p>If {@code cause} is {@code null},
* then a {@code NullPointerException} is thrown.
*
* @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) {
super(cause);

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

@ -26,7 +26,7 @@
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:Jeff.Suttor@Sun.com">Jeff Suttor</a>
@ -35,36 +35,36 @@ package javax.xml.xpath;
public class XPathFunctionException extends XPathExpressionException {
/**
* <p>Stream Unique Identifier.</p>
* Stream Unique Identifier.
*/
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>,
* then a <code>NullPointerException</code> is thrown.</p>
* <p>If {@code message} is {@code null},
* then a {@code NullPointerException} is thrown.
*
* @param message The detail message.
*
* @throws NullPointerException When <code>message</code> is
* <code>null</code>.
* @throws NullPointerException When {@code message} is
* {@code null}.
*/
public XPathFunctionException(String 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>,
* then a <code>NullPointerException</code> is thrown.</p>
* <p>If {@code cause} is {@code null},
* then a {@code NullPointerException} is thrown.
*
* @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) {
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>
Consider the following XML document:
<p>
<blockquote>
<pre>
&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
such operations, the XPath API allows Integer and Long to be used in
{@code evaluateExpression} method such as the following code:
<p>
<blockquote>
<pre>
int count = xpath.evaluate("count(/widgets/widget)", document, Integer.class);