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

Merge

Browse Source
This commit is contained in:
Lana Steuck 2015-04-23 16:12:16 -07:00
commit c3d9eb46c4
68 changed files with 3905 additions and 1412 deletions
Show Stats 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);

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

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

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

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

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

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

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

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

142
jaxp/test/javax/xml/jaxp/functional/test/astro/AstroTest.java Normal file
View File

@ -0,0 +1,142 @@
/*
* Copyright (c) 2002, 2015, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
package test.astro;
import static java.lang.String.valueOf;
import static org.testng.Assert.assertEquals;
import static test.astro.AstroConstants.ASTROCAT;
import static test.astro.AstroConstants.GOLDEN_DIR;
import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.List;
import javax.xml.transform.sax.TransformerHandler;
import jaxp.library.JAXPFileBaseTest;
import org.testng.annotations.BeforeClass;
import org.testng.annotations.DataProvider;
import org.testng.annotations.Test;
/*
* @summary run astro application, test xslt
*
* There are vast amounts of textual astronomical data, typically user is
* interested in a small subset, which is the result from carrying out a query.
* A query can be composed of one or more filters, for example, the user could
* query the database for all stars of visual magnitude down to 6.5 that lie
* between right ascensions 0 h to 2 h, and between declinations of 45 to 90 degrees.
*
* Astro application uses JAXP to query astronomical data saved in an XML dataset.
* A FilterFactory implementation creates filter(A filter is an instance of a JAXP
* TransformerHandler) from an XSL stylesheet.
* A InputSourceFactory implementation creates a new sax input source from an XML file.
* AstroProcessor leverages InputSourceFactory to parse catalog.xml, which saves
* textual astronomical data, and then creates filters with specified parameters
* from FilterFactory, all of the filters are chained together, AstroProcessor
* appends the HTML filter at the end of filter chain, and hooks up the chain to
* the input source, finally processes and outputs to the user specified output file.
*
* AstroTest drives AstroProcessor to run the specified queries(total 4 in setup),
* and then compares the output with the golden files to determine PASS or FAIL.
* It provides variant implementations of FilterFactory and InputSourceFactory to
* AstroProcessor to test different JAXP classes and features.
*
*/
public class AstroTest extends JAXPFileBaseTest {
private FiltersAndGolden[] data;
@BeforeClass
public void setup() throws Exception {
data = new FiltersAndGolden[4];
data[0] = new FiltersAndGolden(getGoldenFileContent(1), astro -> astro.getRAFilter(0.106, 0.108));
data[1] = new FiltersAndGolden(getGoldenFileContent(2), astro -> astro.getStellarTypeFilter("K0IIIbCN-0.5"));
data[2] = new FiltersAndGolden(getGoldenFileContent(3), astro -> astro.getStellarTypeFilter("G"), astro -> astro.getDecFilter(-5.0, 60.0));
data[3] = new FiltersAndGolden(getGoldenFileContent(4), astro -> astro.getRADECFilter(0.084, 0.096, -5.75, 14.0));
}
/*
* Provide permutations of InputSourceFactory and FilterFactory for test.
*/
@DataProvider(name = "factories")
public Object[][] getQueryFactories() {
return new Object[][] {
{ StreamFilterFactoryImpl.class, InputSourceFactoryImpl.class },
{ SAXFilterFactoryImpl.class, InputSourceFactoryImpl.class },
{ DOMFilterFactoryImpl.class, InputSourceFactoryImpl.class },
{ TemplatesFilterFactoryImpl.class, InputSourceFactoryImpl.class },
{ StreamFilterFactoryImpl.class, DOML3InputSourceFactoryImpl.class } };
}
@Test(dataProvider = "factories")
public void test(Class<FilterFactory> fFactClass, Class<InputSourceFactory> isFactClass) throws Exception {
System.out.println(fFactClass.getName() +" : " + isFactClass.getName());
AstroProcessor astro = new AstroProcessor(fFactClass, ASTROCAT, isFactClass);
for (int i = 0; i < data.length; i++) {
runProcess(astro, valueOf(i + 1), data[i].getGolden(), data[i].getFilters());
}
}
private void runProcess(AstroProcessor astro, String processNum, List<String> goldenfileContent, FilterCreator... filterCreators) throws Exception {
System.out.println("run process " + processNum);
TransformerHandler[] filters = new TransformerHandler[filterCreators.length];
for (int i = 0; i < filterCreators.length; i++)
filters[i] = filterCreators[i].createFilter(astro);
String outputfile = Files.createTempFile(Paths.get("").toAbsolutePath(), "query" + processNum + ".out.", null).toString();
System.out.println("output file: " + outputfile);
astro.process(outputfile, filters);
assertEquals(Files.readAllLines(Paths.get(outputfile)), goldenfileContent);
}
private List<String> getGoldenFileContent(int num) throws IOException {
return Files.readAllLines(Paths.get(GOLDEN_DIR + "query" + num + ".out"));
}
@FunctionalInterface
private interface FilterCreator {
TransformerHandler createFilter(AstroProcessor astro) throws Exception;
}
private static class FiltersAndGolden {
private FilterCreator[] filters;
private List<String> golden;
FiltersAndGolden(List<String> golden, FilterCreator... filters) {
this.filters = filters;
this.golden = golden;
}
FilterCreator[] getFilters() {
return filters;
}
List<String> getGolden() {
return golden;
}
}
}

180
jaxp/test/javax/xml/jaxp/functional/test/astro/DocumentLSTest.java Normal file
View File

@ -0,0 +1,180 @@
/*
* Copyright (c) 2002, 2015, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
package test.astro;
import static jaxp.library.JAXPTestUtilities.filenameToURL;
import static org.testng.Assert.assertEquals;
import static org.testng.Assert.assertNotNull;
import static org.testng.Assert.assertNull;
import static org.testng.Assert.assertTrue;
import static org.w3c.dom.ls.DOMImplementationLS.MODE_SYNCHRONOUS;
import static test.astro.AstroConstants.ASTROCAT;
import java.io.FileInputStream;
import java.io.FileOutputStream;
import java.io.InputStream;
import java.io.OutputStream;
import java.io.Writer;
import javax.xml.parsers.DocumentBuilder;
import javax.xml.parsers.DocumentBuilderFactory;
import javax.xml.parsers.ParserConfigurationException;
import jaxp.library.JAXPFileBaseTest;
import org.testng.annotations.Test;
import org.w3c.dom.Document;
import org.w3c.dom.Element;
import org.w3c.dom.ls.DOMImplementationLS;
import org.w3c.dom.ls.LSInput;
import org.w3c.dom.ls.LSOutput;
import org.w3c.dom.ls.LSParser;
import org.w3c.dom.ls.LSSerializer;
/*
* @summary org.w3c.dom.ls tests
*/
public class DocumentLSTest extends JAXPFileBaseTest {
/*
* Test creating an empty Document
*/
@Test
public void testNewDocument() throws ParserConfigurationException {
Document doc = getDocumentBuilder().newDocument();
assertNull(doc.getDocumentElement());
}
/*
* Test creating an LSInput instance, and parsing ByteStream
*/
@Test
public void testLSInputParsingByteStream() throws Exception {
DOMImplementationLS impl = (DOMImplementationLS) getDocumentBuilder().getDOMImplementation();
LSParser domParser = impl.createLSParser(MODE_SYNCHRONOUS, null);
LSInput src = impl.createLSInput();
try (InputStream is = new FileInputStream(ASTROCAT)) {
src.setByteStream(is);
assertNotNull(src.getByteStream());
// set certified accessor methods
boolean origCertified = src.getCertifiedText();
src.setCertifiedText(true);
assertTrue(src.getCertifiedText());
src.setCertifiedText(origCertified); // set back to orig
src.setSystemId(filenameToURL(ASTROCAT));
Document doc = domParser.parse(src);
Element result = doc.getDocumentElement();
assertEquals(result.getTagName(), "stardb");
}
}
/*
* Test creating an LSInput instance, and parsing String
*/
@Test
public void testLSInputParsingString() throws Exception {
DOMImplementationLS impl = (DOMImplementationLS) getDocumentBuilder().getDOMImplementation();
String xml = "<?xml version='1.0'?><test>runDocumentLS_Q6</test>";
LSParser domParser = impl.createLSParser(MODE_SYNCHRONOUS, null);
LSSerializer domSerializer = impl.createLSSerializer();
// turn off xml decl in serialized string for comparison
domSerializer.getDomConfig().setParameter("xml-declaration", Boolean.FALSE);
LSInput src = impl.createLSInput();
src.setStringData(xml);
assertEquals(src.getStringData(), xml);
Document doc = domParser.parse(src);
String result = domSerializer.writeToString(doc);
assertEquals(result, "<test>runDocumentLS_Q6</test>");
}
/*
* Test writing with an LSOutput instance
*/
@Test
public void testLSOutput() throws Exception {
DocumentBuilder db = getDocumentBuilder();
// Create the Document using the supplied builder...
Document doc = db.parse(ASTROCAT);
DOMImplementationLS impl = null;
impl = (DOMImplementationLS) db.getDOMImplementation();
LSSerializer domSerializer = impl.createLSSerializer();
MyDOMOutput mydomoutput = new MyDOMOutput();
try (OutputStream os = new FileOutputStream("test.out")) {
mydomoutput.setByteStream(os);
mydomoutput.setEncoding("UTF-8");
assertTrue(domSerializer.write(doc, mydomoutput));
}
}
private static class MyDOMOutput implements LSOutput {
private OutputStream bytestream = null;
private String encoding = null;
private String sysId = null;
private Writer writer = null;
public OutputStream getByteStream() {
return bytestream;
}
public Writer getCharacterStream() {
return writer;
}
public String getEncoding() {
return encoding;
}
public String getSystemId() {
return sysId;
}
public void setByteStream(OutputStream bs) {
bytestream = bs;
}
public void setCharacterStream(Writer cs) {
writer = cs;
}
public void setEncoding(String enc) {
encoding = enc;
}
public void setSystemId(String sysId) {
this.sysId = sysId;
}
}
private DocumentBuilder getDocumentBuilder() throws ParserConfigurationException {
DocumentBuilderFactory dbf = DocumentBuilderFactory.newInstance();
dbf.setNamespaceAware(true);
return dbf.newDocumentBuilder();
}
}

87
jaxp/test/javax/xml/jaxp/functional/test/astro/NamespaceContextTest.java Normal file
View File

@ -0,0 +1,87 @@
/*
* Copyright (c) 2002, 2015, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
package test.astro;
import static javax.xml.XMLConstants.DEFAULT_NS_PREFIX;
import static javax.xml.XMLConstants.NULL_NS_URI;
import static org.testng.Assert.assertEquals;
import javax.xml.namespace.QName;
import jaxp.library.JAXPBaseTest;
import org.testng.annotations.Test;
/*
* @summary javax.xml.namespace.QName tests
*/
public class NamespaceContextTest extends JAXPBaseTest {
private static final String PREFIX = "astro";
private static final String LOCAL_PART = "stardb";
private static final String NS_URI = "http://www.astro.com";
/*
* Test QName(String, String, String) and accessors.
*/
@Test
public void testQNameConstructor() {
QName qname = new QName(NS_URI, LOCAL_PART, PREFIX);
assertEquals(qname.getNamespaceURI(), NS_URI);
assertEquals(qname.getLocalPart(), LOCAL_PART);
assertEquals(qname.getPrefix(), PREFIX);
}
/*
* Construct QName(String localpart), then test for default ns_uri and
* prefix constant.
*/
@Test
public void testDefaultFields() {
QName qname = new QName(LOCAL_PART); // just the local part specified
assertEquals(qname.getNamespaceURI(), NULL_NS_URI);
assertEquals(qname.getLocalPart(), LOCAL_PART);
assertEquals(qname.getPrefix(), DEFAULT_NS_PREFIX);
}
/*
* Construct QName(String ns,String localpart), then test for default prefix
* constant.
*/
@Test
public void testDefaultPrefix() {
QName qname = new QName(NS_URI, LOCAL_PART); // no pref
assertEquals(qname.getNamespaceURI(), NS_URI);
assertEquals(qname.getLocalPart(), LOCAL_PART);
assertEquals(qname.getPrefix(), DEFAULT_NS_PREFIX);
}
/*
* Round trip testing of QName to String, String to QName and test for
* equality.
*/
@Test
public void testQNameString() {
QName qname = new QName(NS_URI, LOCAL_PART, PREFIX);
assertEquals(QName.valueOf(qname.toString()), qname);
}
}

46
jaxp/test/javax/xml/jaxp/functional/test/astro/SAX201Test.java Normal file
View File

@ -0,0 +1,46 @@
/*
* Copyright (c) 2002, 2015, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
package test.astro;
import javax.xml.parsers.SAXParserFactory;
import jaxp.library.JAXPBaseTest;
import org.testng.annotations.Test;
import org.xml.sax.XMLReader;
/*
* @summary verify SAX 2.0.1 allows to use null in setters
*/
public class SAX201Test extends JAXPBaseTest {
@Test
public void test() throws Exception {
SAXParserFactory spf = SAXParserFactory.newInstance();
spf.setNamespaceAware(true);
XMLReader reader = spf.newSAXParser().getXMLReader();
reader.setErrorHandler(null); // SAX 2.0.1 allows
reader.setContentHandler(null); // SAX 2.0.1 allows
reader.setEntityResolver(null); // SAX 2.0.1 allows
reader.setDTDHandler(null); // SAX 2.0.1 allows
}
}

74
jaxp/test/javax/xml/jaxp/functional/test/astro/SchemaValidationTest.java Normal file
View File

@ -0,0 +1,74 @@
/*
* Copyright (c) 2002, 2015, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
package test.astro;
import static javax.xml.XMLConstants.W3C_XML_SCHEMA_NS_URI;
import static test.astro.AstroConstants.ASTROCAT;
import static test.astro.AstroConstants.JAXP_SCHEMA_LANGUAGE;
import static test.astro.AstroConstants.JAXP_SCHEMA_SOURCE;
import java.io.File;
import javax.xml.parsers.ParserConfigurationException;
import javax.xml.parsers.SAXParser;
import javax.xml.parsers.SAXParserFactory;
import jaxp.library.JAXPFileBaseTest;
import org.testng.annotations.Test;
import org.xml.sax.SAXException;
import org.xml.sax.helpers.DefaultHandler;
/*
* @summary test parser sets schema related properties to do validation
*/
public class SchemaValidationTest extends JAXPFileBaseTest {
/*
* Only set the schemaLanguage, without setting schemaSource. It should
* work.
*/
@Test
public void testSchemaValidation() throws Exception {
SAXParser sp = getValidatingParser();
sp.setProperty(JAXP_SCHEMA_LANGUAGE, W3C_XML_SCHEMA_NS_URI);
sp.parse(new File(ASTROCAT), new DefaultHandler());
}
/*
* Test SAXException shall be thrown if schemaSource is set but
* schemaLanguage is not set.
*/
@Test(expectedExceptions = SAXException.class)
public void testSchemaValidationNeg() throws Exception {
SAXParser sp = getValidatingParser();
sp.setProperty(JAXP_SCHEMA_SOURCE, "catalog.xsd");
sp.parse(new File(ASTROCAT), new DefaultHandler());
}
private SAXParser getValidatingParser() throws ParserConfigurationException, SAXException {
SAXParserFactory spf = SAXParserFactory.newInstance();
spf.setNamespaceAware(true);
spf.setValidating(true);
return spf.newSAXParser();
}
}

169
jaxp/test/javax/xml/jaxp/functional/test/astro/XPathAPITest.java Normal file
View File

@ -0,0 +1,169 @@
/*
* Copyright (c) 2002, 2015, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
package test.astro;
import static javax.xml.XMLConstants.W3C_XML_SCHEMA_NS_URI;
import static javax.xml.xpath.XPathConstants.DOM_OBJECT_MODEL;
import static javax.xml.xpath.XPathConstants.NODESET;
import static jaxp.library.JAXPTestUtilities.filenameToURL;
import static org.testng.Assert.assertEquals;
import static test.astro.AstroConstants.ASTROCAT;
import static test.astro.AstroConstants.JAXP_SCHEMA_LANGUAGE;
import static test.astro.AstroConstants.JAXP_SCHEMA_SOURCE;
import java.net.MalformedURLException;
import java.util.ArrayList;
import java.util.Iterator;
import javax.xml.namespace.NamespaceContext;
import javax.xml.namespace.QName;
import javax.xml.parsers.DocumentBuilder;
import javax.xml.parsers.DocumentBuilderFactory;
import javax.xml.xpath.XPath;
import javax.xml.xpath.XPathExpression;
import javax.xml.xpath.XPathExpressionException;
import javax.xml.xpath.XPathFactory;
import javax.xml.xpath.XPathVariableResolver;
import jaxp.library.JAXPFileBaseTest;
import org.testng.annotations.BeforeClass;
import org.testng.annotations.DataProvider;
import org.testng.annotations.Test;
import org.w3c.dom.Document;
import org.w3c.dom.NodeList;
import org.xml.sax.InputSource;
/*
* @summary test XPath API
*/
@Test(singleThreaded = true)
public class XPathAPITest extends JAXPFileBaseTest {
private static final String STARDB_STAR_3_CONSTELLATION = "//astro:stardb/astro:star[3]/astro:constellation";
private static final String STARDB_STAR = "//astro:stardb/astro:star";
private Document doc;
private XPathFactory xpf;
private NamespaceContext nsContext;
@BeforeClass
public void setup() throws Exception {
DocumentBuilderFactory df = DocumentBuilderFactory.newInstance();
df.setNamespaceAware(true);
df.setValidating(true);
df.setAttribute(JAXP_SCHEMA_LANGUAGE, W3C_XML_SCHEMA_NS_URI);
df.setAttribute(JAXP_SCHEMA_SOURCE, "catalog.xsd");
DocumentBuilder bldr = df.newDocumentBuilder();
doc = bldr.parse(ASTROCAT);
xpf = XPathFactory.newInstance(DOM_OBJECT_MODEL);
nsContext = new MyNamespaceContext();
}
@DataProvider(name = "nodelist-evaluator")
public Object[][] getNodeListEvaluator() throws MalformedURLException {
return new Object[][] { { (XPathEvaluator) expression -> getXPath().evaluate(expression, doc.getDocumentElement(), NODESET) },
{ (XPathEvaluator) expression -> getXPath().evaluate(expression, createXMLInputSource(), NODESET) },
{ (XPathEvaluator) expression -> getXPathExpression(expression).evaluate(doc.getDocumentElement(), NODESET) },
{ (XPathEvaluator) expression -> getXPathExpression(expression).evaluate(createXMLInputSource(), NODESET) } };
}
/*
* Test xpath expression evaluations method that returns type indicated by
* QName
*/
@Test(dataProvider = "nodelist-evaluator")
public void testEvaluateNodeList(XPathEvaluator evaluator) throws Exception {
NodeList o = (NodeList) evaluator.evaluate(STARDB_STAR);
assertEquals(o.getLength(), 10);
}
@DataProvider(name = "string-evaluator")
public Object[][] getStringEvaluator() throws MalformedURLException {
return new Object[][] { { (XPathEvaluator) expression -> getXPath().evaluate(expression, doc.getDocumentElement()) },
{ (XPathEvaluator) expression -> getXPath().evaluate(expression, createXMLInputSource()) },
{ (XPathEvaluator) expression -> getXPathExpression(expression).evaluate(doc.getDocumentElement()) },
{ (XPathEvaluator) expression -> getXPathExpression(expression).evaluate(createXMLInputSource()) } };
}
/*
* Test xpath expression evaluations method that returns String
*/
@Test(dataProvider = "string-evaluator")
public void testEvaluateString(XPathEvaluator evaluator) throws Exception {
assertEquals(evaluator.evaluate(STARDB_STAR_3_CONSTELLATION), "Psc");
}
@Test
public void testXPathVariableResolver() throws Exception {
XPath xpath = getXPath();
xpath.setXPathVariableResolver(new MyXPathVariableResolver());
assertEquals(xpath.evaluate("//astro:stardb/astro:star[astro:hr=$id]/astro:constellation", doc.getDocumentElement()), "Peg");
}
private static class MyXPathVariableResolver implements XPathVariableResolver {
public Object resolveVariable(QName vname) {
return "4"; // resolve $id as 4, xpath will locate to star[hr=4]
}
}
/*
* Implementation of a NamespaceContext interface for the Xpath api tests.
* Used in xpath.setNamespaceContext(...)
*/
private static class MyNamespaceContext implements NamespaceContext {
public String getNamespaceURI(String prefix) {
return "astro".equals(prefix) ? "http://www.astro.com/astro" : "";
}
public String getPrefix(String nsURI) {
return "http://www.astro.com/astro".equals(nsURI) ? "astro" : "";
}
public Iterator getPrefixes(String nsURI) {
ArrayList list = new ArrayList();
list.add("astro");
return list.iterator();
}
}
@FunctionalInterface
private interface XPathEvaluator {
Object evaluate(String expression) throws XPathExpressionException;
}
private XPath getXPath() {
XPath xpath = xpf.newXPath();
xpath.setNamespaceContext(nsContext);
return xpath;
}
private XPathExpression getXPathExpression(String expression) throws XPathExpressionException {
return getXPath().compile(expression);
}
private InputSource createXMLInputSource() {
return new InputSource(filenameToURL(ASTROCAT));
}
}

17
jaxp/test/javax/xml/jaxp/functional/test/astro/xmlfiles/catalog.xml Normal file
View File

@ -0,0 +1,17 @@
<?xml version="1.1" encoding="UTF-8"?>
<stardb xmlns="http://www.astro.com/astro" xmlns:astro="http://www.astro.com/astro" xsi:schemaLocation="http://www.astro.com/astro catalog.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<_test01></_test01>
<test-02 xmlns:xsi=""></test-02>
<test.03></test.03>
<_test-04>T%e!s#t$</_test-04>
<star><hr>1</hr><constellation/><fullname/><ra><h>00</h><m>05</m><s>09.9</s><dv>0.08608333333333333</dv></ra><dec><sgn/><d>45</d><m>13</m><s>45</s><dv>45.22916666666667</dv></dec><glng>114.44</glng><glat>-16.88</glat><vmag>6.70</vmag><spec>A1Vn</spec></star>
<star><hr>2</hr><constellation/><fullname/><ra><h>00</h><m>05</m><s>03.8</s><dv>0.08438888888888889</dv></ra><dec><sgn>-</sgn><d>00</d><m>30</m><s>11</s><dv>-0.5030555555555556</dv></dec><glng>98.33</glng><glat>-61.14</glat><vmag>6.29</vmag><spec>gG9</spec></star>
<star><hr>3</hr><constellation>Psc</constellation><fullname>33 Psc</fullname><ra><h>00</h><m>05</m><s>20.1</s><dv>0.08891666666666666</dv></ra><dec><sgn>-</sgn><d>05</d><m>42</m><s>27</s><dv>-5.7075000000000005</dv></dec><glng>93.75</glng><glat>-65.93</glat><vmag>4.61</vmag><spec>K0IIIbCN-0.5</spec></star>
<star><hr>4</hr><constellation>Peg</constellation><fullname>86 Peg</fullname><ra><h>00</h><m>05</m><s>42.0</s><dv>0.095</dv></ra><dec><sgn/><d>13</d><m>23</m><s>46</s><dv>13.39611111111111</dv></dec><glng>106.19</glng><glat>-47.98</glat><vmag>5.51</vmag><spec>G5III</spec></star>
<star><hr>5</hr><constellation/><fullname/><ra><h>00</h><m>06</m><s>16.0</s><dv>0.10444444444444445</dv></ra><dec><sgn/><d>58</d><m>26</m><s>12</s><dv>58.43666666666666</dv></dec><glng>117.03</glng><glat>-03.92</glat><vmag>5.96</vmag><spec>G5V</spec></star>
<star><hr>6</hr><constellation/><fullname/><ra><h>00</h><m>06</m><s>19.0</s><dv>0.10527777777777779</dv></ra><dec><sgn>-</sgn><d>49</d><m>04</m><s>30</s><dv>-49.075</dv></dec><glng>321.61</glng><glat>-66.38</glat><vmag>5.70</vmag><spec>G1IV</spec></star>
<star><hr>7</hr><constellation>Cas</constellation><fullname>10 Cas</fullname><ra><h>00</h><m>06</m><s>26.5</s><dv>0.10736111111111112</dv></ra><dec><sgn/><d>64</d><m>11</m><s>46</s><dv>64.19611111111111</dv></dec><glng>118.06</glng><glat>1.75</glat><vmag>5.59</vmag><spec>B9III</spec></star>
<star><hr>8</hr><constellation/><fullname/><ra><h>00</h><m>06</m><s>36.8</s><dv>0.11022222222222222</dv></ra><dec><sgn/><d>29</d><m>01</m><s>17</s><dv>29.02138888888889</dv></dec><glng>111.26</glng><glat>-32.83</glat><vmag>6.13</vmag><spec>K0V</spec></star>
<star><hr>9</hr><constellation/><fullname/><ra><h>00</h><m>06</m><s>50.1</s><dv>0.11391666666666667</dv></ra><dec><sgn>-</sgn><d>23</d><m>06</m><s>27</s><dv>-23.1075</dv></dec><glng>52.21</glng><glat>-79.14</glat><vmag>6.18</vmag><spec>A7V</spec></star>
<star><hr>10</hr><constellation/><fullname/><ra><h>00</h><m>07</m><s>18.2</s><dv>0.12172222222222222</dv></ra><dec><sgn>-</sgn><d>17</d><m>23</m><s>11</s><dv>-17.386388888888888</dv></dec><glng>74.36</glng><glat>-75.90</glat><vmag>6.19</vmag><spec>A6Vn</spec></star>
</stardb>

2
jaxp/test/javax/xml/jaxp/functional/test/astro/xmlfiles/catalog.xml.bak Normal file
View File

@ -0,0 +1,2 @@
<?xml version="1.1" encoding="UTF-8"?>
<stardb xmlns="http://www.astro.com/astro" xmlns:astro="http://www.astro.com/astro" xsi:schemaLocation="http://www.astro.com/astro catalog.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"><_test01></_test01><test-02 xmlns:xsi=""></test-02><test.03></test.03><_test-04>T%e!s#t$</_test-04><star><hr>1</hr><constellation/><fullname/><ra><h>00</h><m>05</m><s>09.9</s><dv>0.08608333333333333</dv></ra><dec><sgn/><d>45</d><m>13</m><s>45</s><dv>45.22916666666667</dv></dec><glng>114.44</glng><glat>-16.88</glat><vmag>6.70</vmag><spec>A1Vn</spec></star><star><hr>2</hr><constellation/><fullname/><ra><h>00</h><m>05</m><s>03.8</s><dv>0.08438888888888889</dv></ra><dec><sgn>-</sgn><d>00</d><m>30</m><s>11</s><dv>-0.5030555555555556</dv></dec><glng>98.33</glng><glat>-61.14</glat><vmag>6.29</vmag><spec>gG9</spec></star><star><hr>3</hr><constellation>Psc</constellation><fullname>33 Psc</fullname><ra><h>00</h><m>05</m><s>20.1</s><dv>0.08891666666666666</dv></ra><dec><sgn>-</sgn><d>05</d><m>42</m><s>27</s><dv>-5.7075000000000005</dv></dec><glng>93.75</glng><glat>-65.93</glat><vmag>4.61</vmag><spec>K0IIIbCN-0.5</spec></star><star><hr>4</hr><constellation>Peg</constellation><fullname>86 Peg</fullname><ra><h>00</h><m>05</m><s>42.0</s><dv>0.095</dv></ra><dec><sgn/><d>13</d><m>23</m><s>46</s><dv>13.39611111111111</dv></dec><glng>106.19</glng><glat>-47.98</glat><vmag>5.51</vmag><spec>G5III</spec></star><star><hr>5</hr><constellation/><fullname/><ra><h>00</h><m>06</m><s>16.0</s><dv>0.10444444444444445</dv></ra><dec><sgn/><d>58</d><m>26</m><s>12</s><dv>58.43666666666666</dv></dec><glng>117.03</glng><glat>-03.92</glat><vmag>5.96</vmag><spec>G5V</spec></star><star><hr>6</hr><constellation/><fullname/><ra><h>00</h><m>06</m><s>19.0</s><dv>0.10527777777777779</dv></ra><dec><sgn>-</sgn><d>49</d><m>04</m><s>30</s><dv>-49.075</dv></dec><glng>321.61</glng><glat>-66.38</glat><vmag>5.70</vmag><spec>G1IV</spec></star><star><hr>7</hr><constellation>Cas</constellation><fullname>10 Cas</fullname><ra><h>00</h><m>06</m><s>26.5</s><dv>0.10736111111111112</dv></ra><dec><sgn/><d>64</d><m>11</m><s>46</s><dv>64.19611111111111</dv></dec><glng>118.06</glng><glat>1.75</glat><vmag>5.59</vmag><spec>B9III</spec></star><star><hr>8</hr><constellation/><fullname/><ra><h>00</h><m>06</m><s>36.8</s><dv>0.11022222222222222</dv></ra><dec><sgn/><d>29</d><m>01</m><s>17</s><dv>29.02138888888889</dv></dec><glng>111.26</glng><glat>-32.83</glat><vmag>6.13</vmag><spec>K0V</spec></star><star><hr>9</hr><constellation/><fullname/><ra><h>00</h><m>06</m><s>50.1</s><dv>0.11391666666666667</dv></ra><dec><sgn>-</sgn><d>23</d><m>06</m><s>27</s><dv>-23.1075</dv></dec><glng>52.21</glng><glat>-79.14</glat><vmag>6.18</vmag><spec>A7V</spec></star><star><hr>10</hr><constellation/><fullname/><ra><h>00</h><m>07</m><s>18.2</s><dv>0.12172222222222222</dv></ra><dec><sgn>-</sgn><d>17</d><m>23</m><s>11</s><dv>-17.386388888888888</dv></dec><glng>74.36</glng><glat>-75.90</glat><vmag>6.19</vmag><spec>A6Vn</spec></star></stardb>

122
jaxp/test/javax/xml/jaxp/functional/test/astro/xmlfiles/catalog.xsd Normal file
View File

@ -0,0 +1,122 @@
<xs:schema
xmlns:xs="http://www.w3.org/2001/XMLSchema"
targetNamespace="http://www.astro.com/astro"
xmlns:astro="http://www.astro.com/astro"
elementFormDefault="qualified"
attributeFormDefault="qualified"
>
<!-- Star Identification String Type -->
<xs:simpleType name="staridType">
<xs:restriction base="xs:string">
<xs:maxLength value="4"/>
</xs:restriction>
</xs:simpleType>
<!-- Hour Type -->
<xs:simpleType name="hourType">
<xs:restriction base="xs:decimal">
<xs:minInclusive value="0.0"/>
<xs:maxInclusive value="24.0"/>
</xs:restriction>
</xs:simpleType>
<!-- Minute Type -->
<xs:simpleType name="minuteType">
<xs:restriction base="xs:decimal">
<xs:minInclusive value="0.0"/>
<xs:maxInclusive value="60.0"/>
</xs:restriction>
</xs:simpleType>
<!-- Second Type -->
<xs:simpleType name="secondType">
<xs:restriction base="xs:decimal">
<xs:minInclusive value="0.0"/>
<xs:maxInclusive value="60.0"/>
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="decimalValueType">
<xs:restriction base="xs:decimal">
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="degType">
<xs:restriction base="xs:decimal">
<xs:minInclusive value="-90.0"/>
<xs:maxInclusive value="90.0"/>
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="vmagType">
<xs:restriction base="xs:decimal">
<xs:minInclusive value="-3.0"/>
<xs:maxInclusive value="12.0"/>
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="signType">
<xs:restriction base="xs:string">
<xs:enumeration value="+"/>
<xs:enumeration value="-"/>
<xs:enumeration value=""/>
</xs:restriction>
</xs:simpleType>
<xs:complexType name="raType">
<xs:sequence>
<xs:element name="h" type="astro:hourType"/>
<xs:element name="m" type="astro:minuteType"/>
<xs:element name="s" type="astro:secondType"/>
<xs:element name="dv" type="astro:decimalValueType"/>
</xs:sequence>
</xs:complexType>
<xs:complexType name="decType">
<xs:sequence>
<xs:element name="sgn" type="astro:signType"/>
<xs:element name="d" type="astro:degType"/>
<xs:element name="m" type="astro:minuteType"/>
<xs:element name="s" type="astro:secondType"/>
<xs:element name="dv" type="astro:decimalValueType"/>
</xs:sequence>
</xs:complexType>
<xs:complexType name="starType">
<xs:sequence>
<xs:element name="hr" type="astro:staridType"/>
<xs:element name="constellation" type="xs:string"/>
<xs:element name="fullname" type="xs:string"/>
<xs:element name="ra" type="astro:raType"/>
<xs:element name="dec" type="astro:decType"/>
<xs:element name="glng" type="xs:decimal"/>
<xs:element name="glat" type="xs:decimal"/>
<xs:element name="vmag" type="astro:vmagType"/>
<xs:element name="spec" type="xs:string"/>
</xs:sequence>
</xs:complexType>
<!-- The real part of the catalog starts here -->
<xs:element name="stardb">
<xs:complexType>
<xs:sequence>
<!-- for testing purposes -->
<xs:element name="_test01" type="xs:string"
minOccurs="0" maxOccurs="1"/>
<xs:element name="test-02" type="xs:string"/>
<xs:element name="test.03" type="xs:string"/>
<xs:element name="_test-04" type="xs:string"/>
<!-- astro data elements -->
<xs:element name="star" type="astro:starType"
minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<!-- The real part of the catalog ends here -->
</xs:schema>

15
jaxp/test/javax/xml/jaxp/functional/test/astro/xmlfiles/gold/query1.out Normal file
View File

@ -0,0 +1,15 @@
<html xmlns:astro="http://www.astro.com/astro">
<h1>Bright Star Catalog Extract</h1>
<body>
<b>Star Id: </b>7<br>
<b>Constellation: </b>Cas<br>
<b>Description: </b>10 Cas<br>
<b>RA J2000: </b>00:06:26.5<br>
<b>DEC J2000: </b>64:11:46<br>
<b>Visual Magnitude: </b>5.59<br>
<b>Spectral Type: </b>B9III<br>
<b>Galactic Longitude: </b>118.06<br>
<b>Galactic Latitude: </b>1.75<br>
<hr>
</body>
</html>

15
jaxp/test/javax/xml/jaxp/functional/test/astro/xmlfiles/gold/query2.out Normal file
View File

@ -0,0 +1,15 @@
<html xmlns:astro="http://www.astro.com/astro">
<h1>Bright Star Catalog Extract</h1>
<body>
<b>Star Id: </b>3<br>
<b>Constellation: </b>Psc<br>
<b>Description: </b>33 Psc<br>
<b>RA J2000: </b>00:05:20.1<br>
<b>DEC J2000: </b>05:42:27<br>
<b>Visual Magnitude: </b>4.61<br>
<b>Spectral Type: </b>K0IIIbCN-0.5<br>
<b>Galactic Longitude: </b>93.75<br>
<b>Galactic Latitude: </b>-65.93<br>
<hr>
</body>
</html>

39
jaxp/test/javax/xml/jaxp/functional/test/astro/xmlfiles/gold/query3.out Normal file
View File

@ -0,0 +1,39 @@
<html xmlns:astro="http://www.astro.com/astro">
<h1>Bright Star Catalog Extract</h1>
<body>
<b>Star Id: </b>2<br>
<b>Constellation: </b>
<br>
<b>Description: </b>
<br>
<b>RA J2000: </b>00:05:03.8<br>
<b>DEC J2000: </b>00:30:11<br>
<b>Visual Magnitude: </b>6.29<br>
<b>Spectral Type: </b>gG9<br>
<b>Galactic Longitude: </b>98.33<br>
<b>Galactic Latitude: </b>-61.14<br>
<hr>
<b>Star Id: </b>4<br>
<b>Constellation: </b>Peg<br>
<b>Description: </b>86 Peg<br>
<b>RA J2000: </b>00:05:42.0<br>
<b>DEC J2000: </b>13:23:46<br>
<b>Visual Magnitude: </b>5.51<br>
<b>Spectral Type: </b>G5III<br>
<b>Galactic Longitude: </b>106.19<br>
<b>Galactic Latitude: </b>-47.98<br>
<hr>
<b>Star Id: </b>5<br>
<b>Constellation: </b>
<br>
<b>Description: </b>
<br>
<b>RA J2000: </b>00:06:16.0<br>
<b>DEC J2000: </b>58:26:12<br>
<b>Visual Magnitude: </b>5.96<br>
<b>Spectral Type: </b>G5V<br>
<b>Galactic Longitude: </b>117.03<br>
<b>Galactic Latitude: </b>-03.92<br>
<hr>
</body>
</html>

37
jaxp/test/javax/xml/jaxp/functional/test/astro/xmlfiles/gold/query4.out Normal file
View File

@ -0,0 +1,37 @@
<html xmlns:astro="http://www.astro.com/astro">
<h1>Bright Star Catalog Extract</h1>
<body>
<b>Star Id: </b>2<br>
<b>Constellation: </b>
<br>
<b>Description: </b>
<br>
<b>RA J2000: </b>00:05:03.8<br>
<b>DEC J2000: </b>00:30:11<br>
<b>Visual Magnitude: </b>6.29<br>
<b>Spectral Type: </b>gG9<br>
<b>Galactic Longitude: </b>98.33<br>
<b>Galactic Latitude: </b>-61.14<br>
<hr>
<b>Star Id: </b>3<br>
<b>Constellation: </b>Psc<br>
<b>Description: </b>33 Psc<br>
<b>RA J2000: </b>00:05:20.1<br>
<b>DEC J2000: </b>05:42:27<br>
<b>Visual Magnitude: </b>4.61<br>
<b>Spectral Type: </b>K0IIIbCN-0.5<br>
<b>Galactic Longitude: </b>93.75<br>
<b>Galactic Latitude: </b>-65.93<br>
<hr>
<b>Star Id: </b>4<br>
<b>Constellation: </b>Peg<br>
<b>Description: </b>86 Peg<br>
<b>RA J2000: </b>00:05:42.0<br>
<b>DEC J2000: </b>13:23:46<br>
<b>Visual Magnitude: </b>5.51<br>
<b>Spectral Type: </b>G5III<br>
<b>Galactic Longitude: </b>106.19<br>
<b>Galactic Latitude: </b>-47.98<br>
<hr>
</body>
</html>

36
jaxp/test/javax/xml/jaxp/functional/test/astro/xmlfiles/xsl/dec-ent.xsl Normal file
View File

@ -0,0 +1,36 @@
<!-- This is the external entity version of dec.xsl
in which the top level template has been removed
and referenced as an external entity
-->
<!DOCTYPE xsl:transform [
<!ENTITY toplevel SYSTEM "http://astro.com/stylesheets/toptemplate">
]>
<xsl:transform
xmlns:astro="http://www.astro.com/astro"
xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
<xsl:output method="xml"/>
<!-- dec between 00:00:00 and 01:00:00 -->
<xsl:param name="dec_min_deg" select="0.0"/>
<xsl:param name="dec_max_deg" select="1.0"/>
<!-- introduce the external entity -->
&toplevel;
<xsl:template match="astro:star">
<xsl:if test="(
(number(astro:dec/astro:dv) &gt;= $dec_min_deg) and
(number(astro:dec/astro:dv) &lt;= $dec_max_deg))" >
<xsl:copy-of select="."/>
</xsl:if>
</xsl:template>
<xsl:template match="astro:_test-04">
<!-- discard text contents -->
</xsl:template>
</xsl:transform>

32
jaxp/test/javax/xml/jaxp/functional/test/astro/xmlfiles/xsl/dec.xsl Normal file
View File

@ -0,0 +1,32 @@
<xsl:transform
xmlns:astro="http://www.astro.com/astro"
xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
<xsl:output method="xml"/>
<!-- dec between 00:00:00 and 01:00:00 -->
<xsl:param name="dec_min_deg" select="0.0"/>
<xsl:param name="dec_max_deg" select="1.0"/>
<xsl:template match="astro:stardb">
<stardb xmlns="http://www.astro.com/astro"
xsi:schemaLocation="http://www.astro.com/astro catalog.xsd"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<xsl:apply-templates/>
</stardb>
</xsl:template>
<xsl:template match="astro:star">
<xsl:if test="(
(number(astro:dec/astro:dv) &gt;= $dec_min_deg) and
(number(astro:dec/astro:dv) &lt;= $dec_max_deg))" >
<xsl:copy-of select="."/>
</xsl:if>
</xsl:template>
<xsl:template match="astro:_test-04">
<!-- discard text contents -->
</xsl:template>
</xsl:transform>

26
jaxp/test/javax/xml/jaxp/functional/test/astro/xmlfiles/xsl/dec_frag.xsl Normal file
View File

@ -0,0 +1,26 @@
<xsl:transform
xmlns:astro="http://www.astro.com/astro"
xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
<!-- dec_frag.xsl = fragment used in radec.xsl -->
<xsl:output method="xml"/>
<xsl:param name="dec_min_deg" select="-5.75"/>
<xsl:param name="dec_max_deg" select="14.0"/>
<xsl:template match="astro:star" mode="RA_PASSED" >
<xsl:if test="(
(number(astro:dec/astro:dv) &gt;= $dec_min_deg) and
(number(astro:dec/astro:dv) &lt;= $dec_max_deg))" >
<xsl:copy-of select="."/>
</xsl:if>
</xsl:template>
<xsl:template match="astro:_test-04">
<!-- discard text contents -->
</xsl:template>
</xsl:transform>

38
jaxp/test/javax/xml/jaxp/functional/test/astro/xmlfiles/xsl/html.xsl Normal file
View File

@ -0,0 +1,38 @@
<xsl:transform
xmlns=""
xmlns:astro="http://www.astro.com/astro"
xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
<xsl:strip-space elements="*"/>
<xsl:output method="html"/>
<xsl:template match="astro:stardb">
<html>
<h1>Bright Star Catalog Extract</h1>
<body>
<xsl:apply-templates/>
</body>
</html>
</xsl:template>
<xsl:template match="astro:star">
<b>Star Id: </b><xsl:value-of select="astro:hr"/><br/>
<b>Constellation: </b><xsl:value-of select="astro:constellation"/><br/>
<b>Description: </b><xsl:value-of select="astro:fullname"/><br/>
<b>RA J2000: </b><xsl:value-of select="astro:ra/astro:h"/><xsl:text>:</xsl:text><xsl:value-of select="astro:ra/astro:m"/><xsl:text>:</xsl:text><xsl:value-of select="astro:ra/astro:s"/><br/>
<b>DEC J2000: </b><xsl:value-of select="astro:ra/astro:sgn"/><xsl:value-of select="astro:dec/astro:d"/><xsl:text>:</xsl:text><xsl:value-of select="astro:dec/astro:m"/><xsl:text>:</xsl:text><xsl:value-of select="astro:dec/astro:s"/><br/>
<b>Visual Magnitude: </b><xsl:value-of select="astro:vmag"/><br/>
<b>Spectral Type: </b><xsl:value-of select="astro:spec"/><br/>
<b>Galactic Longitude: </b><xsl:value-of select="astro:glng"/><br/>
<b>Galactic Latitude: </b><xsl:value-of select="astro:glat"/><br/>
<hr></hr>
</xsl:template>
<xsl:template match="astro:_test-04">
<!-- discard text contents -->
</xsl:template>
</xsl:transform>

29
jaxp/test/javax/xml/jaxp/functional/test/astro/xmlfiles/xsl/ra-ent.xsl Normal file
View File

@ -0,0 +1,29 @@
<!DOCTYPE xsl:transform [
<!ENTITY toplevel SYSTEM "http://astro.com/stylesheets/toptemplate">
]>
<xsl:transform
xmlns:astro="http://www.astro.com/astro"
xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
<xsl:output method="xml"/>
<!-- ra between 00:00:00 and 01:00:00 -->
<xsl:param name="ra_min_hr" select="0.106"/>
<xsl:param name="ra_max_hr" select="0.108"/>
&toplevel;
<xsl:template match="astro:star">
<xsl:if test="(
(number(astro:ra/astro:dv) &gt;= $ra_min_hr) and
(number(astro:ra/astro:dv) &lt;= $ra_max_hr))" >
<xsl:copy-of select="."/>
</xsl:if>
</xsl:template>
<xsl:template match="astro:_test-04">
<!-- discard text contents -->
</xsl:template>
</xsl:transform>

27
jaxp/test/javax/xml/jaxp/functional/test/astro/xmlfiles/xsl/ra-uri.xsl Normal file
View File

@ -0,0 +1,27 @@
<xsl:transform
xmlns:astro="http://www.astro.com/astro"
xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
<xsl:output method="xml"/>
<!-- ra between 00:00:00 and 01:00:00 -->
<xsl:param name="ra_min_hr" select="0.106"/>
<xsl:param name="ra_max_hr" select="0.108"/>
<!-- will use the uri resolver to resolve to 'toptemplate.xsl' -->
<xsl:include href="http://astro.com/stylesheets/topleveltemplate"/>
<xsl:template match="astro:star">
<xsl:if test="(
(number(astro:ra/astro:dv) &gt;= $ra_min_hr) and
(number(astro:ra/astro:dv) &lt;= $ra_max_hr))" >
<xsl:copy-of select="."/>
</xsl:if>
</xsl:template>
<xsl:template match="astro:_test-04">
<!-- discard text contents -->
</xsl:template>
</xsl:transform>

32
jaxp/test/javax/xml/jaxp/functional/test/astro/xmlfiles/xsl/ra.xsl Normal file
View File

@ -0,0 +1,32 @@
<xsl:transform
xmlns:astro="http://www.astro.com/astro"
xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
<xsl:output method="xml"/>
<!-- ra between 00:00:00 and 01:00:00 -->
<xsl:param name="ra_min_hr" select="0.106"/>
<xsl:param name="ra_max_hr" select="0.108"/>
<xsl:template match="astro:stardb">
<stardb xmlns="http://www.astro.com/astro"
xsi:schemaLocation="http://www.astro.com/astro catalog.xsd"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<xsl:apply-templates/>
</stardb>
</xsl:template>
<xsl:template match="astro:star">
<xsl:if test="(
(number(astro:ra/astro:dv) &gt;= $ra_min_hr) and
(number(astro:ra/astro:dv) &lt;= $ra_max_hr))" >
<xsl:copy-of select="."/>
</xsl:if>
</xsl:template>
<xsl:template match="astro:_test-04">
<!-- discard text contents -->
</xsl:template>
</xsl:transform>

26
jaxp/test/javax/xml/jaxp/functional/test/astro/xmlfiles/xsl/ra_frag.xsl Normal file
View File

@ -0,0 +1,26 @@
<xsl:transform
xmlns:astro="http://www.astro.com/astro"
xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
<!-- ra_frag = fragment used in radec.xsl -->
<xsl:output method="xml"/>
<xsl:param name="ra_min_hr" select="0.084"/>
<xsl:param name="ra_max_hr" select="0.096"/>
<xsl:template match="astro:star">
<xsl:if test="(
(number(astro:ra/astro:dv) &gt;= $ra_min_hr) and
(number(astro:ra/astro:dv) &lt;= $ra_max_hr))" >
<xsl:apply-templates select="." mode="RA_PASSED"/>
</xsl:if>
</xsl:template>
<xsl:template match="astro:_test-04">
<!-- discard text contents -->
</xsl:template>
</xsl:transform>

28
jaxp/test/javax/xml/jaxp/functional/test/astro/xmlfiles/xsl/radec.xsl Normal file
View File

@ -0,0 +1,28 @@
<xsl:transform
xmlns:astro="http://www.astro.com/astro"
xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
<!-- radec.xsl = filters on both RA and DEC using modes -->
<xsl:output method="xml"/>
<!-- include the fragments for ra and dec filtering -->
<xsl:include href="ra_frag.xsl"/>
<xsl:include href="dec_frag.xsl"/>
<xsl:template match="astro:stardb">
<stardb xmlns="http://www.astro.com/astro"
xsi:schemaLocation="http://www.astro.com/astro catalog.xsd"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" >
<xsl:apply-templates/>
</stardb>
</xsl:template>
<xsl:template match="astro:_test-04">
<!-- discard text contents -->
</xsl:template>
</xsl:transform>

29
jaxp/test/javax/xml/jaxp/functional/test/astro/xmlfiles/xsl/stellartype.xsl Normal file
View File

@ -0,0 +1,29 @@
<xsl:transform
xmlns:astro="http://www.astro.com/astro"
xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
<xsl:output method="xml"/>
<!-- search stars of a particular type -->
<xsl:param name="type" select="G"/>
<xsl:template match="astro:stardb">
<stardb xmlns="http://www.astro.com/astro"
xsi:schemaLocation="http://www.astro.com/astro catalog.xsd"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" >
<xsl:apply-templates/>
</stardb>
</xsl:template>
<xsl:template match="astro:star">
<xsl:if test="(contains(astro:spec,$type))" >
<xsl:copy-of select="."/>
</xsl:if>
</xsl:template>
<xsl:template match="astro:_test-04">
<!-- discard text contents -->
</xsl:template>
</xsl:transform>

17
jaxp/test/javax/xml/jaxp/functional/test/astro/xmlfiles/xsl/toptemplate.xsl Normal file
View File

@ -0,0 +1,17 @@
<!--
<xsl:transform
xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
-->
<xsl:template match="astro:stardb">
<stardb xmlns="http://www.astro.com/astro"
xsi:schemaLocation="http://www.astro.com/astro catalog.xsd"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" >
<xsl:apply-templates/>
</stardb>
</xsl:template>
<!--
</xsl:transform>
-->

24
jaxp/test/javax/xml/jaxp/functional/test/astro/xmlfiles/xsl/toptemplateinc.xsl Normal file
View File

@ -0,0 +1,24 @@
<xsl:transform
xmlns:astro="http://www.astro.com/astro"
xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
<!--
- toptemplateinc.xsl = toptemplate used in an xsl:include element
- which demands that this is a complete stylesheet.
- The related toptemplate.xsl is not a complete stylesheet
- as it is used in ext entity references.
-->
<xsl:template match="astro:stardb">
<stardb xmlns="http://www.astro.com/astro"
xsi:schemaLocation="http://www.astro.com/astro catalog.xsd"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" >
<xsl:apply-templates/>
</stardb>
</xsl:template>
<xsl:template match="astro:_test-04">
<!-- discard text contents -->
</xsl:template>
</xsl:transform>

93
jaxp/test/javax/xml/jaxp/libs/test/astro/AbstractFilterFactory.java Normal file
View File

@ -0,0 +1,93 @@
/*
* Copyright (c) 2015, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
package test.astro;
import static test.astro.AstroConstants.HTMLXSL;
import java.io.IOException;
import javax.xml.parsers.ParserConfigurationException;
import javax.xml.transform.Transformer;
import javax.xml.transform.TransformerConfigurationException;
import javax.xml.transform.sax.TransformerHandler;
import org.xml.sax.SAXException;
public abstract class AbstractFilterFactory implements FilterFactory {
@Override
public TransformerHandler newRAFilter(double min, double max) throws TransformerConfigurationException, SAXException, ParserConfigurationException,
IOException {
TransformerHandler retval = getTransformerHandler(getRAXsl());
Transformer xformer = retval.getTransformer();
xformer.setParameter("ra_min_hr", String.valueOf(min));
xformer.setParameter("ra_max_hr", String.valueOf(max));
return retval;
}
@Override
public TransformerHandler newDECFilter(double min, double max) throws TransformerConfigurationException, SAXException, ParserConfigurationException,
IOException {
TransformerHandler retval = getTransformerHandler(getDECXsl());
Transformer xformer = retval.getTransformer();
xformer.setParameter("dec_min_deg", String.valueOf(min));
xformer.setParameter("dec_max_deg", String.valueOf(max));
return retval;
}
@Override
public TransformerHandler newRADECFilter(double rmin, double rmax, double dmin, double dmax) throws TransformerConfigurationException, SAXException,
ParserConfigurationException, IOException {
TransformerHandler retval = getTransformerHandler(getRADECXsl());
Transformer xformer = retval.getTransformer();
xformer.setParameter("ra_min_hr", String.valueOf(rmin));
xformer.setParameter("ra_max_hr", String.valueOf(rmax));
xformer.setParameter("dec_min_deg", String.valueOf(dmin));
xformer.setParameter("dec_max_deg", String.valueOf(dmax));
return retval;
}
@Override
public TransformerHandler newStellarTypeFilter(String type) throws TransformerConfigurationException, SAXException, ParserConfigurationException,
IOException {
TransformerHandler retval = getTransformerHandler(getStellarXsl());
Transformer xformer = retval.getTransformer();
xformer.setParameter("type", type);
return retval;
}
@Override
public TransformerHandler newHTMLOutput() throws TransformerConfigurationException, SAXException, ParserConfigurationException, IOException {
return getTransformerHandler(HTMLXSL);
}
abstract protected TransformerHandler getTransformerHandler(String xslFileName) throws SAXException, ParserConfigurationException,
TransformerConfigurationException, IOException;
abstract protected String getRAXsl();
abstract protected String getDECXsl();
abstract protected String getRADECXsl();
abstract protected String getStellarXsl();
}

60
jaxp/test/javax/xml/jaxp/libs/test/astro/AstroConstants.java Normal file
View File

@ -0,0 +1,60 @@
/*
* Copyright (c) 2002, 2015, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
package test.astro;
import static java.io.File.separator;
import static jaxp.library.JAXPTestUtilities.getPathByClassName;
public class AstroConstants {
// Query parameters :
public static final double RA_MIN = 0.0; // hours
public static final double RA_MAX = 24.0; // hours
public static final double DEC_MIN = -90.000; // degrees
public static final double DEC_MAX = 90.000; // degrees
// Stylesheet source paths:
public static final String XSLPATH = getPathByClassName(AstroConstants.class, "xmlfiles" + separator + "xsl");
public static final String RAXSL = XSLPATH + "ra.xsl";
public static final String DECXSL = XSLPATH + "dec.xsl";
public static final String RADECXSL = XSLPATH + "radec.xsl";
public static final String STYPEXSL = XSLPATH + "stellartype.xsl";
public static final String HTMLXSL = XSLPATH + "html.xsl";
public static final String RAENTXSL = XSLPATH + "ra-ent.xsl";
public static final String DECENTXSL = XSLPATH + "dec-ent.xsl";
public static final String RAURIXSL = XSLPATH + "ra-uri.xsl";
public static final String TOPTEMPLXSL = XSLPATH + "toptemplate.xsl";
public static final String TOPTEMPLINCXSL = XSLPATH + "toptemplateinc.xsl";
// Catalog references
public static final String ASTROCAT = getPathByClassName(AstroConstants.class, "xmlfiles") + "catalog.xml";
public static final String GOLDEN_DIR = getPathByClassName(AstroConstants.class, "xmlfiles" + separator + "gold");
public static final String JAXP_SCHEMA_LANGUAGE = "http://java.sun.com/xml/jaxp/properties/schemaLanguage";
public static final String JAXP_SCHEMA_SOURCE = "http://java.sun.com/xml/jaxp/properties/schemaSource";
}

279
jaxp/test/javax/xml/jaxp/libs/test/astro/AstroProcessor.java Normal file
View File

@ -0,0 +1,279 @@
/*
* Copyright (c) 2002, 2015, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
package test.astro;
import static javax.xml.XMLConstants.W3C_XML_SCHEMA_NS_URI;
import static test.astro.AstroConstants.DEC_MAX;
import static test.astro.AstroConstants.DEC_MIN;
import static test.astro.AstroConstants.JAXP_SCHEMA_LANGUAGE;
import static test.astro.AstroConstants.JAXP_SCHEMA_SOURCE;
import static test.astro.AstroConstants.RA_MAX;
import static test.astro.AstroConstants.RA_MIN;
import java.io.File;
import java.io.IOException;
import javax.xml.parsers.ParserConfigurationException;
import javax.xml.parsers.SAXParser;
import javax.xml.parsers.SAXParserFactory;
import javax.xml.transform.TransformerConfigurationException;
import javax.xml.transform.sax.SAXResult;
import javax.xml.transform.sax.TransformerHandler;
import javax.xml.transform.stream.StreamResult;
import org.xml.sax.ErrorHandler;
import org.xml.sax.InputSource;
import org.xml.sax.SAXException;
import org.xml.sax.SAXParseException;
import org.xml.sax.XMLReader;
/*
* AstroProcessor is to carry out the user's query with filters and produce a table of
* star records that match the criterion, and finally output with HTML format.
*/
public class AstroProcessor {
private String catalogFileName;
private FilterFactory ffact;
private InputSourceFactory isfact;
private SAXParserFactory spf;
/*
* Constructor for the Main astro class.
*
* @param fFactClass the class of the FilterFactory implementation
*
* @param catalogfilename the name of the XML input document (database)
*
* @param isFactClass the class of the Input Source Factory implementation
*/
public AstroProcessor(Class<FilterFactory> fFactClass, String catalogFileName, Class<InputSourceFactory> isFactClass) throws Exception {
// create the Filter Factory instance...
ffact = fFactClass.newInstance();
// create the Input Source Instance
isfact = isFactClass.newInstance();
spf = SAXParserFactory.newInstance();
spf.setNamespaceAware(true);
spf.setValidating(true);
// All XML Readers are required to recognize these two:
spf.setFeature("http://xml.org/sax/features/namespaces", true);
spf.setFeature("http://xml.org/sax/features/namespace-prefixes", true);
// Other features...
spf.setFeature("http://xml.org/sax/features/validation", true);
spf.setFeature("http://apache.org/xml/features/validation/schema", true);
spf.setFeature("http://apache.org/xml/features/validation/schema-full-checking", true);
this.catalogFileName = catalogFileName;
}
/*
* Sets the star stellar type query.
*
* @param arg stellar type string, can be a substring.
*/
public TransformerHandler getStellarTypeFilter(String arg) throws TransformerConfigurationException, SAXException, ParserConfigurationException,
IOException {
String stellarType = null;
if (arg != null && arg.length() != 0) {
stellarType = arg; // set value of query
} else {
throw new IllegalArgumentException("\n Stellar type string of length zero found.");
}
return ffact.newStellarTypeFilter(stellarType);
}
/*
* Sets the right ascension parameters for a query. Parameters are validated
* to be in the range of 0h and 24h inclusive.
*
* @param min minimum right ascension in hours.
*
* @param max maximum right ascension in hours.
*/
public TransformerHandler getRAFilter(double min, double max) throws TransformerConfigurationException, SAXException, ParserConfigurationException,
IOException {
double raMin = RA_MIN; // hours
double raMax = RA_MAX; // hours
if (min < max) {
if ((min >= RA_MIN && min <= RA_MAX) && (max >= RA_MIN && max <= RA_MAX)) {
raMin = min; // set value of query
raMax = max; // set value of query
}
} else {
throw new IllegalArgumentException("min must be less than max.\n" + "min=" + min + ", max=" + max);
}
return ffact.newRAFilter(raMin, raMax);
}
/*
* Sets the right ascension and dec parameters for a query. Parameters are
* validated to be in the range of ra 0h and 24h and dec -90 to +90
* inclusive.
*
* @param rmin minimum right ascension in hours.
*
* @param rmax maximum right ascension in hours.
*
* @param dmin minimum declination in degs.
*
* @param dmax maximum declination in degs.
*/
public TransformerHandler getRADECFilter(double rmin, double rmax, double dmin, double dmax) throws TransformerConfigurationException, SAXException,
ParserConfigurationException, IOException {
double raMin = RA_MIN; // hours
double raMax = RA_MAX; // hours
double decMin = DEC_MIN; // degrees
double decMax = DEC_MAX; // degrees
if (rmin < rmax && dmin < dmax) {
if ((rmin >= RA_MIN && rmin <= RA_MAX) && (rmax >= RA_MIN && rmax <= RA_MAX)) {
raMin = rmin; // set value of query
raMax = rmax; // set value of query
}
if ((dmin >= DEC_MIN && dmin <= DEC_MAX) && (dmax >= DEC_MIN && dmax <= DEC_MAX)) {
decMin = dmin; // set value of query
decMax = dmax; // set value of query
}
} else {
throw new IllegalArgumentException("min must be less than max.\n" + "rmin=" + rmin + ", rmax=" + rmax + ", dmin=" + dmin + ", dmax=" + dmax);
}
return ffact.newRADECFilter(raMin, raMax, decMin, decMax);
}
/*
* Sets the declination parameters for a query. Parameters are validated to
* be in the range of -90 and +90 degrees inclusive.
*
* @param min minimum declination in degrees.
*
* @param max maximum declination in degrees.
*/
public TransformerHandler getDecFilter(double min, double max) throws TransformerConfigurationException, SAXException, ParserConfigurationException,
IOException {
double decMin = DEC_MIN; // degrees
double decMax = DEC_MAX; // degrees
if (min < max) {
if ((min >= DEC_MIN && min <= DEC_MAX) && (max >= DEC_MIN && max <= DEC_MAX)) {
decMin = min; // set value of query
decMax = max; // set value of query
}
} else {
throw new IllegalArgumentException("min must be less than max.\n" + "min=" + min + ", max=" + max);
}
return ffact.newDECFilter(decMin, decMax);
}
/*
* Runs the filter process against the astronomical database.
*
* @throws Exception
*/
public void process(String outputfile, TransformerHandler... filters) throws Exception {
XMLReader catparser = getXMLReader();
File catalogfile = new File(catalogFileName);
InputSource catsrc = isfact.newInputSource(catalogfile.getPath());
TransformerHandler outfilter = ffact.newHTMLOutput();
// create an array from the Vector of filters...
// hook the filters up to each other, there may be zero filters
int nfilters = filters.length;
if (nfilters != 0) {
TransformerHandler prev = null;
for (int i = 0; i < filters.length; i++) {
TransformerHandler curr = filters[i];
if (prev != null) {
prev.setResult(new SAXResult(curr));
}
prev = curr;
}
// hook up the last filter to the output filter
prev.setResult(new SAXResult(outfilter));
// hook up the catalog parser to the first filter...
catparser.setContentHandler(filters[0]);
} else {
// There are no query filters,
// hook up the catalog parser directly to output filter...
catparser.setContentHandler(outfilter);
}
// hook up the output filter to the output file or std out
if (outputfile != null) {
outfilter.setResult(new StreamResult(outputfile));
} else {
outfilter.setResult(new StreamResult(System.out));
}
catparser.parse(catsrc);
}
private XMLReader getXMLReader() throws Exception {
SAXParser parser = spf.newSAXParser();
parser.setProperty(JAXP_SCHEMA_LANGUAGE, W3C_XML_SCHEMA_NS_URI);
parser.setProperty(JAXP_SCHEMA_SOURCE, "catalog.xsd");
XMLReader catparser = parser.getXMLReader();
catparser.setErrorHandler(new CatalogErrorHandler());
return catparser;
}
/*
* Error Handler for the parsing of the XML astronomical catalog.
*/
private static class CatalogErrorHandler implements ErrorHandler {
private String getParseExceptionInfo(SAXParseException spe) {
String systemId = spe.getSystemId();
if (systemId == null) {
systemId = "null";
}
String info = "Catalog URI=" + systemId + " Line=" + spe.getLineNumber() + ": " + spe.getMessage();
return info;
}
public void warning(SAXParseException spe) throws SAXException {
String message = "Warning: " + getParseExceptionInfo(spe);
throw new SAXException(message);
}
public void error(SAXParseException spe) throws SAXException {
String message = "Error: " + getParseExceptionInfo(spe);
throw new SAXException(message);
}
public void fatalError(SAXParseException spe) throws SAXException {
String message = "Fatal Error: " + getParseExceptionInfo(spe);
throw new SAXException(message);
}
}
}

80
jaxp/test/javax/xml/jaxp/libs/test/astro/DOMFilterFactoryImpl.java Normal file
View File

@ -0,0 +1,80 @@
/*
* Copyright (c) 2002, 2015, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
package test.astro;
import static jaxp.library.JAXPTestUtilities.filenameToURL;
import static test.astro.AstroConstants.DECXSL;
import static test.astro.AstroConstants.RAXSL;
import static test.astro.AstroConstants.STYPEXSL;
import java.io.IOException;
import javax.xml.parsers.DocumentBuilderFactory;
import javax.xml.parsers.ParserConfigurationException;
import javax.xml.transform.Source;
import javax.xml.transform.dom.DOMSource;
import org.w3c.dom.Document;
import org.xml.sax.SAXException;
/*
* Implementation of the filter factory interface that utilizes DOM
* sources rather than Stream or SAX sources. This factory utilizes a
* DocumentBuilder to read in the stylesheets and create the DOM used
* to create the filters for the query pipeline.
*
*/
public class DOMFilterFactoryImpl extends SourceFilterFactory {
@Override
protected Source getSource(String xslFileName) throws SAXException, ParserConfigurationException, IOException {
Document document = getStylesheetDOM(xslFileName);
return new DOMSource(document);
}
@Override
protected String getRAXsl() {
return RAXSL;
}
@Override
protected String getDECXsl() {
return DECXSL;
}
@Override
protected String getRADECXsl() {
return DECXSL;
}
@Override
protected String getStellarXsl() {
return STYPEXSL;
}
private Document getStylesheetDOM(String xslfilename) throws SAXException, IOException, ParserConfigurationException {
DocumentBuilderFactory dbf = DocumentBuilderFactory.newInstance();
dbf.setNamespaceAware(true);
return dbf.newDocumentBuilder().parse(filenameToURL(xslfilename));
}
}

172
jaxp/test/javax/xml/jaxp/libs/test/astro/DOML3InputSourceFactoryImpl.java Normal file
View File

@ -0,0 +1,172 @@
/*
* Copyright (c) 2002, 2015, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
package test.astro;
import static jaxp.library.JAXPTestUtilities.filenameToURL;
import static org.w3c.dom.ls.DOMImplementationLS.MODE_SYNCHRONOUS;
import static org.w3c.dom.traversal.NodeFilter.SHOW_ELEMENT;
import java.io.ByteArrayInputStream;
import java.io.FileReader;
import java.io.FileWriter;
import java.io.InputStreamReader;
import java.io.Reader;
import java.nio.file.Files;
import java.nio.file.Paths;
import javax.xml.parsers.DocumentBuilder;
import javax.xml.parsers.DocumentBuilderFactory;
import org.w3c.dom.DOMConfiguration;
import org.w3c.dom.Document;
import org.w3c.dom.Element;
import org.w3c.dom.Node;
import org.w3c.dom.ls.DOMImplementationLS;
import org.w3c.dom.ls.LSInput;
import org.w3c.dom.ls.LSParser;
import org.w3c.dom.ls.LSParserFilter;
import org.w3c.dom.ls.LSSerializer;
import org.w3c.dom.ls.LSSerializerFilter;
import org.xml.sax.InputSource;
/*
* A specialized implementation of an Input Source factory that utilizes
* DOM Level 3 implementations to build a Document (DOM) from the
* astro input file (XML) and then will serialize the DOM. The serialized DOM
* of the astro input file is then used to create the sax InputSource
* and set it's system id. It is then returned to the caller.
*
*/
public class DOML3InputSourceFactoryImpl implements InputSourceFactory {
public InputSource newInputSource(String filename) throws Exception {
// Create DOMImplementationLS, and DOM L3 LSParser
DocumentBuilderFactory fact = DocumentBuilderFactory.newInstance();
DocumentBuilder bldr = fact.newDocumentBuilder();
DOMImplementationLS impl = (DOMImplementationLS) bldr.getDOMImplementation();
LSParser domparser = impl.createLSParser(MODE_SYNCHRONOUS, null);
domparser.setFilter(new MyDOMBuilderFilter());
// Parse the xml document to create the DOM Document using
// the DOM L3 LSParser and a LSInput (formerly LSInputSource)
Document doc = null;
LSInput src = impl.createLSInput();
// register the input file with the input source...
String systemId = filenameToURL(filename);
src.setSystemId(systemId);
try (Reader reader = new FileReader(filename)) {
src.setCharacterStream(reader);
src.setEncoding("UTF-8");
doc = domparser.parse(src);
}
// Use DOM L3 LSSerializer (previously called a DOMWriter)
// to serialize the xml doc DOM to a file stream.
String tmpCatalog = Files.createTempFile(Paths.get("").toAbsolutePath(), "catalog.xml", null).toString();
LSSerializer domserializer = impl.createLSSerializer();
domserializer.setFilter(new MyDOMWriterFilter());
domserializer.getNewLine();
DOMConfiguration config = domserializer.getDomConfig();
config.setParameter("xml-declaration", Boolean.TRUE);
String result = domserializer.writeToString(doc);
try (FileWriter os = new FileWriter(tmpCatalog, false)) {
os.write(result);
os.flush();
}
// Return the Input Source created from the Serialized DOM L3 Document.
InputSource catsrc = new InputSource(new InputStreamReader(new ByteArrayInputStream(Files.readAllBytes(Paths.get(tmpCatalog)))));
catsrc.setSystemId(systemId);
return catsrc;
}
/*
* Implementation of a DOM L3 DOM Builder Filter. The filter is capable of
* examining nodes as they are available during the parse. This
* implementation both rejects (filters) and modifies particular nodes
* during the parse of the document. As such, the document in memory will
* become a subset of the document on the stream in accordance with the DOM
* Level 3 Load and Save Specification, v1.0, sect. 1.3 Load Interfaces.
*/
private static class MyDOMBuilderFilter implements LSParserFilter {
/*
* Filter the DOM. Define element(s) and their children that should be
* efficiently skipped thereby filtering them out of the stream.
*/
@Override
public short startElement(Element e) {
return "_test01".equals(e.getTagName()) ? FILTER_REJECT : FILTER_ACCEPT;
}
/*
* Modify the DOM 'in situ'. Find a particular Node and change the Node
* value of its child, allow other nodes to pass through unchanged.
*/
@Override
public short acceptNode(Node n) {
String localname = n.getLocalName();
if (localname.equals("_test-04")) {
Node child = n.getFirstChild();
String text = child.getNodeValue();
if (text.equals("T%e!s#t$")) {
child.setNodeValue("T%E!S#T$");
}
}
return FILTER_ACCEPT;
}
/*
* Tells the DOMBuilder what types of nodes to show to the filter.
*/
@Override
public int getWhatToShow() {
return SHOW_ELEMENT;
}
}
/*
* Implementation of a DOM Serializer Filter (previously called a DOM Writer
* Filter) which is a specialization of the NodeFilter interface.
*/
private static class MyDOMWriterFilter implements LSSerializerFilter {
public MyDOMWriterFilter() {
}
/*
* Must implement method from NodeFilter interface
*/
@Override
public short acceptNode(Node node) {
return FILTER_ACCEPT;
}
/*
* Tells the DOMBuilder what types of nodes to show to the filter.
*/
@Override
public int getWhatToShow() {
return SHOW_ELEMENT;
}
}
}

78
jaxp/test/javax/xml/jaxp/libs/test/astro/FilterFactory.java Normal file
View File

@ -0,0 +1,78 @@
/*
* Copyright (c) 2002, 2015, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
package test.astro;
import java.io.IOException;
import javax.xml.parsers.ParserConfigurationException;
import javax.xml.transform.sax.TransformerHandler;
import javax.xml.transform.TransformerConfigurationException;
import org.xml.sax.SAXException;
/*
* Defines the interface for all concrete implementations of a Filter
* Factory.
*/
public interface FilterFactory {
/*
* Allows only the stars between right ascension (R.A.) of min and max to
* pass. Filters out all stars that are not in that range of right
* ascension. Units of right ascension are hours (h), range of parameters is
* 0h to 24h.
*
* @param min minimum R.A.
*
* @param max maxmimum R.A.
*/
TransformerHandler newRAFilter(double min, double max) throws TransformerConfigurationException, SAXException, ParserConfigurationException, IOException;
/*
* Allows only the stars between declination (DEC) of min and max to pass.
* Filters out all stars that are not in that range of declination. Units of
* declination are degrees (degs), range of parameters is -90 and +90 degs.
*
* @param min minimum DEC
*
* @param max maxmimum DEC
*/
TransformerHandler newDECFilter(double min, double max) throws TransformerConfigurationException, SAXException, ParserConfigurationException, IOException;
/*
* Combines the usage of newRAFilter and newDECFilter into one.
*
* @param rmin minimum R.A.
*
* @param rmax maxmimum R.A.
*
* @param dmin minimum DEC
*
* @param dmax maxmimum DEC
*/
TransformerHandler newRADECFilter(double rmin, double rmax, double dmin, double dmax) throws TransformerConfigurationException, SAXException,
ParserConfigurationException, IOException;
TransformerHandler newStellarTypeFilter(String type) throws TransformerConfigurationException, SAXException, ParserConfigurationException, IOException;
TransformerHandler newHTMLOutput() throws TransformerConfigurationException, SAXException, ParserConfigurationException, IOException;
}

40
jaxp/test/javax/xml/jaxp/libs/test/astro/InputSourceFactory.java Normal file
View File

@ -0,0 +1,40 @@
/*
* Copyright (c) 2002, 2015, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
package test.astro;
import org.xml.sax.InputSource;
/*
* Interface for all input source factory objects. The default implementation
* 'InputSourceFactoryImpl' is provided as a straight forward factory
* class that creates a new sax input source from a filename.
*
*/
public interface InputSourceFactory {
/*
* Creates a new sax InputSource object from a filename.
* Also sets the system id of the input source.
* @param file filename of the XML input to create the input source.
*/
InputSource newInputSource(String file) throws Exception;
}

44
jaxp/test/javax/xml/jaxp/libs/test/astro/InputSourceFactoryImpl.java Normal file
View File

@ -0,0 +1,44 @@
/*
* Copyright (c) 2002, 2015, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
package test.astro;
import static jaxp.library.JAXPTestUtilities.filenameToURL;
import org.xml.sax.InputSource;
/*
* Default implementation of a input source factory. This is the most
* straight forward way to create a sax input source and set it's
* system id.
*
*/
public class InputSourceFactoryImpl implements InputSourceFactory {
public InputSourceFactoryImpl() {
}
public InputSource newInputSource(String filename) {
InputSource catSrc = new InputSource(filename);
catSrc.setSystemId(filenameToURL(filename));
return catSrc;
}
}

119
jaxp/test/javax/xml/jaxp/libs/test/astro/SAXFilterFactoryImpl.java Normal file
View File

@ -0,0 +1,119 @@
/*
* Copyright (c) 2002, 2015, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
package test.astro;
import static jaxp.library.JAXPTestUtilities.filenameToURL;
import static test.astro.AstroConstants.DECENTXSL;
import static test.astro.AstroConstants.DECXSL;
import static test.astro.AstroConstants.RAENTXSL;
import static test.astro.AstroConstants.STYPEXSL;
import static test.astro.AstroConstants.TOPTEMPLXSL;
import javax.xml.parsers.ParserConfigurationException;
import javax.xml.parsers.SAXParserFactory;
import javax.xml.transform.Source;
import javax.xml.transform.sax.SAXSource;
import org.xml.sax.EntityResolver;
import org.xml.sax.InputSource;
import org.xml.sax.SAXException;
import org.xml.sax.XMLReader;
/*
* Implementation of the filter factory interface that utilizes SAX
* sources rather than Stream sources. This factory utilizes a
* SAX parser factory and XMLReader to read in the stylesheets used
* to create the filters for the query pipeline.
* The XMLReader has been equipped with an entity resolver
* SAXFilterFactoryEntityResolver, it is used to resolve external
* entities in two specialized stylesheets, ra-ent.xsl (derived from
* ra.xsl) and dec-ent.xsl (derived from dec.xsl).
*
*/
public class SAXFilterFactoryImpl extends SourceFilterFactory {
private EntityResolver entityResolver;
public SAXFilterFactoryImpl() {
super();
entityResolver = new SAXFilterFactoryEntityResolver();
}
@Override
protected Source getSource(String xslFileName) throws SAXException, ParserConfigurationException {
SAXSource saxsource = new SAXSource(new InputSource(filenameToURL(xslFileName)));
saxsource.setXMLReader(getXMLReader());
return saxsource;
}
@Override
protected String getRAXsl() {
return RAENTXSL;
}
@Override
protected String getDECXsl() {
return DECENTXSL;
}
@Override
protected String getRADECXsl() {
return DECXSL;
}
@Override
protected String getStellarXsl() {
return STYPEXSL;
}
/*
* Entity resolver implementation that is used in the SAXFilterFactory
* implementation for handling external entities that appear in two
* specialized stylesheets, 'ra-ent.xsl' and 'dec-ent.xsl'. Both of these
* stylesheets contain an external entity reference to the top level
* stylesheet template, which is stored in a separate file,
* 'toptemplate.xsl'.
*/
private static class SAXFilterFactoryEntityResolver implements EntityResolver {
public InputSource resolveEntity(String publicid, String sysId) {
if (sysId.equals("http://astro.com/stylesheets/toptemplate")) {
InputSource retval = new InputSource(TOPTEMPLXSL);
retval.setSystemId(filenameToURL(TOPTEMPLXSL));
return retval;
} else {
return null; // use default behavior
}
}
}
private XMLReader getXMLReader() throws SAXException, ParserConfigurationException {
SAXParserFactory pfactory = SAXParserFactory.newInstance();
pfactory.setNamespaceAware(true);
// pfactory.setValidating(true);
XMLReader xmlreader = pfactory.newSAXParser().getXMLReader();
// entity resolver is used in stylesheets ra-ent.xsl,
// dec-ent.xsl. Other stylehsheets will not use it
// since they do not contain ext entities.
xmlreader.setEntityResolver(entityResolver);
return xmlreader;
}
}

48
jaxp/test/javax/xml/jaxp/libs/test/astro/SourceFilterFactory.java Normal file
View File

@ -0,0 +1,48 @@
/*
* Copyright (c) 2015, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
package test.astro;
import java.io.IOException;
import javax.xml.parsers.ParserConfigurationException;
import javax.xml.transform.Source;
import javax.xml.transform.TransformerConfigurationException;
import javax.xml.transform.TransformerFactory;
import javax.xml.transform.sax.SAXTransformerFactory;
import javax.xml.transform.sax.TransformerHandler;
import org.xml.sax.SAXException;
public abstract class SourceFilterFactory extends AbstractFilterFactory {
@Override
protected TransformerHandler getTransformerHandler(String xslFileName) throws SAXException, ParserConfigurationException,
TransformerConfigurationException, IOException {
return getFactory().newTransformerHandler(getSource(xslFileName));
}
abstract protected Source getSource(String xslFileName) throws SAXException, ParserConfigurationException, IOException;
private SAXTransformerFactory getFactory() {
return (SAXTransformerFactory) TransformerFactory.newInstance();
}
}

59
jaxp/test/javax/xml/jaxp/libs/test/astro/StreamFilterFactoryImpl.java Normal file
View File

@ -0,0 +1,59 @@
/*
* Copyright (c) 2002, 2015, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
package test.astro;
import static jaxp.library.JAXPTestUtilities.filenameToURL;
import static test.astro.AstroConstants.DECXSL;
import static test.astro.AstroConstants.RADECXSL;
import static test.astro.AstroConstants.RAXSL;
import static test.astro.AstroConstants.STYPEXSL;
import javax.xml.transform.Source;
import javax.xml.transform.stream.StreamSource;
public class StreamFilterFactoryImpl extends SourceFilterFactory {
@Override
protected Source getSource(String xslFileName) {
return new StreamSource(filenameToURL(xslFileName));
}
@Override
protected String getRAXsl() {
return RAXSL;
}
@Override
protected String getDECXsl() {
return DECXSL;
}
@Override
protected String getRADECXsl() {
return RADECXSL;
}
@Override
protected String getStellarXsl() {
return STYPEXSL;
}
}

123
jaxp/test/javax/xml/jaxp/libs/test/astro/TemplatesFilterFactoryImpl.java Normal file
View File

@ -0,0 +1,123 @@
/*
* Copyright (c) 2002, 2015, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
package test.astro;
import static jaxp.library.JAXPTestUtilities.filenameToURL;
import static test.astro.AstroConstants.DECXSL;
import static test.astro.AstroConstants.RAURIXSL;
import static test.astro.AstroConstants.STYPEXSL;
import static test.astro.AstroConstants.TOPTEMPLINCXSL;
import java.io.IOException;
import javax.xml.parsers.ParserConfigurationException;
import javax.xml.parsers.SAXParserFactory;
import javax.xml.transform.Source;
import javax.xml.transform.TransformerConfigurationException;
import javax.xml.transform.TransformerException;
import javax.xml.transform.TransformerFactory;
import javax.xml.transform.URIResolver;
import javax.xml.transform.sax.SAXTransformerFactory;
import javax.xml.transform.sax.TemplatesHandler;
import javax.xml.transform.sax.TransformerHandler;
import javax.xml.transform.stream.StreamSource;
import org.xml.sax.InputSource;
import org.xml.sax.SAXException;
import org.xml.sax.XMLReader;
/*
* Implementation of the filter factory interface that utilizes
* a TemplatesHandler and creates Templates from the stylesheets.
* The Templates objects are then used to create a TransformerHandler
* a.k.a Filter which is returned to the caller.
* This factory uses a Uri resolver which is registered with the
* Transformer factory.
*
*/
public class TemplatesFilterFactoryImpl extends AbstractFilterFactory {
private final URIResolver uriResolver = new TemplatesFilterFactoryURIResolver();
@Override
protected String getRAXsl() {
return RAURIXSL;
}
@Override
protected String getDECXsl() {
return DECXSL;
}
@Override
protected String getRADECXsl() {
return DECXSL;
}
@Override
protected String getStellarXsl() {
return STYPEXSL;
}
@Override
protected TransformerHandler getTransformerHandler(String xslFileName) throws SAXException, ParserConfigurationException,
TransformerConfigurationException, IOException {
SAXTransformerFactory factory = (SAXTransformerFactory) TransformerFactory.newInstance();
factory.setURIResolver(uriResolver);
TemplatesHandler templatesHandler = factory.newTemplatesHandler();
SAXParserFactory pFactory = SAXParserFactory.newInstance();
pFactory.setNamespaceAware(true);
XMLReader xmlreader = pFactory.newSAXParser().getXMLReader();
// create the stylesheet input source
InputSource xslSrc = new InputSource(xslFileName);
xslSrc.setSystemId(filenameToURL(xslFileName));
// hook up the templates handler as the xsl content handler
xmlreader.setContentHandler(templatesHandler);
// call parse on the xsl input source
xmlreader.parse(xslSrc);
// extract the Templates object created from the xsl input source
return factory.newTransformerHandler(templatesHandler.getTemplates());
}
/*
* Uri resolver used to resolve stylesheet used by the Templates filter
* factory.
*/
private static class TemplatesFilterFactoryURIResolver implements URIResolver {
public Source resolve(String href, String base) throws TransformerException {
if ("http://astro.com/stylesheets/topleveltemplate".equals(href)) {
StreamSource ss = new StreamSource(TOPTEMPLINCXSL);
ss.setSystemId(filenameToURL(TOPTEMPLINCXSL));
return ss;
} else {
return null;
}
}
}
}

40
jaxp/test/javax/xml/jaxp/unittest/org/w3c/dom/JdkXmlDomTest.java Normal file
View File

@ -0,0 +1,40 @@
/*
* Copyright (c) 2015, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
package org.w3c.dom;
import org.testng.Assert;
import org.testng.annotations.Test;
/*
* @bug 8078139
* @summary Verifies that jdk.xml.dom classes are loaded by the ext class loader.
*/
public class JdkXmlDomTest {
@Test
public void test() throws ClassNotFoundException {
ClassLoader cl = ClassLoader.getSystemClassLoader().getParent();
Class<?> cls = Class.forName("org.w3c.dom.xpath.XPathEvaluator", false, cl);
Assert.assertTrue(cls.getClassLoader() != null);
}
}