+ * The Catalog API defines a standard solution for resolving external resources + * referenced by XML documents. It is fully supported by the XML Processors + * allowing application developers to configure a catalog through an XML processor + * or system property or the jaxp.properties file to take advantage of the feature. + *
+ * The XML Catalog API defines the following interfaces: + *
+ * Unless otherwise noted, passing a null argument to + * a constructor or method in any class or interface in this package will + * cause a {@code NullPointerException} to be thrown. + * + * @since 9 + * + */ + +package javax.xml.catalog; diff --git a/jaxp/src/java.xml/share/classes/javax/xml/catalog/package.html b/jaxp/src/java.xml/share/classes/javax/xml/catalog/package.html deleted file mode 100644 index 043cf6f1678..00000000000 --- a/jaxp/src/java.xml/share/classes/javax/xml/catalog/package.html +++ /dev/null @@ -1,44 +0,0 @@ - - -
- - - - - Provides the classes for implementing - - XML Catalogs OASIS Standard V1.1, 7 October 2005. - -
- Unless otherwise noted, passing a null argument to
- a constructor or method in any class or interface in this package will
- cause a NullPointerException to be thrown.
-
+ * Defines XML/Java Type Mappings. + * + *
+ * This API provides XML/Java type mappings. + * + *
+ * The following XML standards apply: + * + *
| W3C XML Schema Data Type | + *Java Data Type | + *
|---|---|
| xs:date | + *{@link javax.xml.datatype.XMLGregorianCalendar} | + *
| xs:dateTime | + *{@link javax.xml.datatype.XMLGregorianCalendar} | + *
| xs:duration | + *{@link javax.xml.datatype.Duration} | + *
| xs:gDay | + *{@link javax.xml.datatype.XMLGregorianCalendar} | + *
| xs:gMonth | + *{@link javax.xml.datatype.XMLGregorianCalendar} | + *
| xs:gMonthDay | + *{@link javax.xml.datatype.XMLGregorianCalendar} | + *
| xs:gYear | + *{@link javax.xml.datatype.XMLGregorianCalendar} | + *
| xs:gYearMonth | + *{@link javax.xml.datatype.XMLGregorianCalendar} | + *
| xs:time | + *{@link javax.xml.datatype.XMLGregorianCalendar} | + *
| XQuery 1.0 and XPath 2.0 Data Model | + *Java Data Type | + *
|---|---|
| xdt:dayTimeDuration | + *{@link javax.xml.datatype.Duration} | + *
| xdt:yearMonthDuration | + *{@link javax.xml.datatype.Duration} | + *
+ * W3C XML Schema data types that have a "natural" mapping to Java types are defined by + * JSR 31: Java™ Architecture for XML Binding (JAXB) Specification, Binding XML Schema to Java Representations. + * JAXB defined mappings for XML Schema built-in data types include: + * + *
XML/Java Type Mappings.
- -javax.xml.datatypeAPI provides XML/Java type mappings.
The following XML standards apply:
-| W3C XML Schema Data Type | -Java Data Type | -
|---|---|
| xs:date | -{@link javax.xml.datatype.XMLGregorianCalendar} | -
| xs:dateTime | -{@link javax.xml.datatype.XMLGregorianCalendar} | -
| xs:duration | -{@link javax.xml.datatype.Duration} | -
| xs:gDay | -{@link javax.xml.datatype.XMLGregorianCalendar} | -
| xs:gMonth | -{@link javax.xml.datatype.XMLGregorianCalendar} | -
| xs:gMonthDay | -{@link javax.xml.datatype.XMLGregorianCalendar} | -
| xs:gYear | -{@link javax.xml.datatype.XMLGregorianCalendar} | -
| xs:gYearMonth | -{@link javax.xml.datatype.XMLGregorianCalendar} | -
| xs:time | -{@link javax.xml.datatype.XMLGregorianCalendar} | -
| XQuery 1.0 and XPath 2.0 Data Model | -Java Data Type | -
|---|---|
| xdt:dayTimeDuration | -{@link javax.xml.datatype.Duration} | -
| xdt:yearMonthDuration | -{@link javax.xml.datatype.Duration} | -
- W3C XML Schema data types that have a "natural" mapping to Java types are defined by - JSR 31: Java™ Architecture for XML Binding (JAXB) Specification, Binding XML Schema to Java Representations. - JAXB defined mappings for XML Schema built-in data types include: -
-+ * Defines XML Namespace processing. + * + *
+ * The following XML standards apply: + * + *
XML Namespace processing.
- -The following XML standards apply:
- - - - diff --git a/jaxp/src/java.xml/share/classes/javax/xml/package-info.java b/jaxp/src/java.xml/share/classes/javax/xml/package-info.java new file mode 100644 index 00000000000..b267667bb79 --- /dev/null +++ b/jaxp/src/java.xml/share/classes/javax/xml/package-info.java @@ -0,0 +1,34 @@ +/* + * Copyright (c) 2015, 2017, 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. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * 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. + */ + +/** + * + * Defines constants for XML processing. + * + * @since 1.5 + * + */ + +package javax.xml; diff --git a/jaxp/src/java.xml/share/classes/javax/xml/parsers/package-info.java b/jaxp/src/java.xml/share/classes/javax/xml/parsers/package-info.java new file mode 100644 index 00000000000..251b97d7595 --- /dev/null +++ b/jaxp/src/java.xml/share/classes/javax/xml/parsers/package-info.java @@ -0,0 +1,36 @@ +/* + * Copyright (c) 2015, 2017, 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. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * 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. + */ + +/** + *+ * Provides the classes for processing XML documents with a SAX (Simple API for XML) + * parser or a DOM (Document Object Model) Document builder. The JAXP Plugability + * layer allows an application programmer to specify an implementation and + * configure where to locate it. + * + * @since 1.4 + */ + +package javax.xml.parsers; diff --git a/jaxp/src/java.xml/share/classes/javax/xml/parsers/package.html b/jaxp/src/java.xml/share/classes/javax/xml/parsers/package.html deleted file mode 100644 index 52092114cd4..00000000000 --- a/jaxp/src/java.xml/share/classes/javax/xml/parsers/package.html +++ /dev/null @@ -1,51 +0,0 @@ - - - - - - - -
-- Provides classes allowing the processing of XML documents. Two types - of plugable parsers are supported: -
-+ * Defines interfaces and classes for the Streaming API for XML (StAX). + * + *
+ * StAX provides two basic functions: the cursor API allowing users to + * read and write XML efficiently, and the event iterator API promoting + * ease of use that is event based, easy to extend and pipeline. + * The event iterator API is intended to layer on top of the cursor API. + * + *
+ * The cursor API defines two interfaces: {@link XMLStreamReader} + * and {@link XMLStreamWriter}, while the event iterator API defines: + * {@link XMLEventReader} and {@link XMLEventWriter}. + * + *
+ * StAX supports plugability with {@link XMLInputFactory} and + * {@link XMLOutputFactory} that define how an implementation is + * located through a process as described in the {@link newFactory} + * method. + * + * + * @since 1.6 + */ + +package javax.xml.stream; diff --git a/jaxp/src/java.xml/share/classes/javax/xml/stream/util/package-info.java b/jaxp/src/java.xml/share/classes/javax/xml/stream/util/package-info.java new file mode 100644 index 00000000000..074f9e0c208 --- /dev/null +++ b/jaxp/src/java.xml/share/classes/javax/xml/stream/util/package-info.java @@ -0,0 +1,32 @@ +/* + * Copyright (c) 2015, 2017, 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. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * 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. + */ + +/** + * Provides utility classes for the Streaming API for XML (StAX). + * + * @since 1.6 + */ + +package javax.xml.stream.util; diff --git a/jaxp/src/java.xml/share/classes/javax/xml/transform/dom/package-info.java b/jaxp/src/java.xml/share/classes/javax/xml/transform/dom/package-info.java new file mode 100644 index 00000000000..6a121ce46c1 --- /dev/null +++ b/jaxp/src/java.xml/share/classes/javax/xml/transform/dom/package-info.java @@ -0,0 +1,61 @@ +/* + * Copyright (c) 2015, 2017, 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. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * 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. + */ + +/** + * Provides DOM specific transformation classes. + *
+ * The {@link javax.xml.transform.dom.DOMSource} class allows the + * client of the implementation of this API to specify a DOM + * {@link org.w3c.dom.Node} as the source of the input tree. The model of + * how the Transformer deals with the DOM tree in terms of mismatches with the + * XSLT data model or + * other data models is beyond the scope of this document. Any of the nodes + * derived from {@link org.w3c.dom.Node} are legal input. + *
+ * The {@link javax.xml.transform.dom.DOMResult} class allows + * a {@link org.w3c.dom.Node} to be specified to which result DOM nodes will + * be appended. If an output node is not specified, the transformer will use + * {@link javax.xml.parsers.DocumentBuilder#newDocument} to create an + * output {@link org.w3c.dom.Document} node. If a node is specified, it + * should be one of the following: {@link org.w3c.dom.Document}, + * {@link org.w3c.dom.Element}, or + * {@link org.w3c.dom.DocumentFragment}. Specification of any other node + * type is implementation dependent and undefined by this API. If the result is a + * {@link org.w3c.dom.Document}, the output of the transformation must have + * a single element root to set as the document element. + *
+ * The {@link javax.xml.transform.dom.DOMLocator} node may be passed + * to {@link javax.xml.transform.TransformerException} objects, and + * retrieved by trying to cast the result of the + * {@link javax.xml.transform.TransformerException#getLocator()} method. + * The implementation has no responsibility to use a DOMLocator instead of a + * {@link javax.xml.transform.SourceLocator} (though line numbers and the + * like do not make much sense for a DOM), so the result of getLocator must always + * be tested with an instanceof. + * + * @since 1.5 + */ + +package javax.xml.transform.dom; diff --git a/jaxp/src/java.xml/share/classes/javax/xml/transform/dom/package.html b/jaxp/src/java.xml/share/classes/javax/xml/transform/dom/package.html deleted file mode 100644 index 09cb8123d50..00000000000 --- a/jaxp/src/java.xml/share/classes/javax/xml/transform/dom/package.html +++ /dev/null @@ -1,70 +0,0 @@ - - - - - - - -
-This package implements DOM-specific transformation APIs.
-The {@link javax.xml.transform.dom.DOMSource} class allows the -client of the implementation of this API to specify a DOM -{@link org.w3c.dom.Node} as the source of the input tree. The model of -how the Transformer deals with the DOM tree in terms of mismatches with the -XSLT data model or -other data models is beyond the scope of this document. Any of the nodes -derived from {@link org.w3c.dom.Node} are legal input.
-The {@link javax.xml.transform.dom.DOMResult} class allows -a {@link org.w3c.dom.Node} to be specified to which result DOM nodes will -be appended. If an output node is not specified, the transformer will use -{@link javax.xml.parsers.DocumentBuilder#newDocument} to create an -output {@link org.w3c.dom.Document} node. If a node is specified, it -should be one of the following: {@link org.w3c.dom.Document}, -{@link org.w3c.dom.Element}, or -{@link org.w3c.dom.DocumentFragment}. Specification of any other node -type is implementation dependent and undefined by this API. If the result is a -{@link org.w3c.dom.Document}, the output of the transformation must have -a single element root to set as the document element.
-The {@link javax.xml.transform.dom.DOMLocator} node may be passed -to {@link javax.xml.transform.TransformerException} objects, and -retrieved by trying to cast the result of the -{@link javax.xml.transform.TransformerException#getLocator()} method. -The implementation has no responsibility to use a DOMLocator instead of a -{@link javax.xml.transform.SourceLocator} (though line numbers and the -like do not make much sense for a DOM), so the result of getLocator must always -be tested with an instanceof.
- - diff --git a/jaxp/src/java.xml/share/classes/javax/xml/transform/package-info.java b/jaxp/src/java.xml/share/classes/javax/xml/transform/package-info.java new file mode 100644 index 00000000000..2afa0406642 --- /dev/null +++ b/jaxp/src/java.xml/share/classes/javax/xml/transform/package-info.java @@ -0,0 +1,216 @@ +/* + * Copyright (c) 2015, 2017, 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. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * 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. + */ + +/** + * Defines the generic APIs for processing transformation instructions, + * and performing a transformation from source to result. These interfaces have no + * dependencies on SAX or the DOM standard, and try to make as few assumptions as + * possible about the details of the source and result of a transformation. It + * achieves this by defining {@link javax.xml.transform.Source} and + * {@link javax.xml.transform.Result} interfaces. + * + *+ * To provide concrete classes for the user, the API defines specializations + * of the interfaces found at the root level. These interfaces are found in + * {@link javax.xml.transform.sax}, {@link javax.xml.transform.dom}, + * {@link javax.xml.transform.stax}, and {@link javax.xml.transform.stream}. + * + * + *
+ * The API allows a concrete {@link javax.xml.transform.TransformerFactory} + * object to be created from the static function + * {@link javax.xml.transform.TransformerFactory#newInstance}. + * + * + *
+ * This API defines two interface objects called {@link javax.xml.transform.Source} + * and {@link javax.xml.transform.Result}. In order to pass Source and Result + * objects to the interfaces, concrete classes must be used. The following concrete + * representations are defined for each of these objects: + * {@link javax.xml.transform.stream.StreamSource} and + * {@link javax.xml.transform.stream.StreamResult}, + * {@link javax.xml.transform.stax.StAXSource} and + * {@link javax.xml.transform.stax.StAXResult}, and + * {@link javax.xml.transform.sax.SAXSource} and + * {@link javax.xml.transform.sax.SAXResult}, and + * {@link javax.xml.transform.dom.DOMSource} and + * {@link javax.xml.transform.dom.DOMResult}. Each of these objects defines a + * FEATURE string (which is in the form of a URL), which can be passed into + * {@link javax.xml.transform.TransformerFactory#getFeature} to see if the given + * type of Source or Result object is supported. For instance, to test if a + * DOMSource and a StreamResult is supported, you can apply the following test. + * + *
+ *
+ * TransformerFactory tfactory = TransformerFactory.newInstance();
+ * if (tfactory.getFeature(DOMSource.FEATURE) &&
+ * tfactory.getFeature(StreamResult.FEATURE)) {
+ * ...
+ * }
+ *
+ *
+ *
+ *
+ * + * Namespaces present something + * of a problem area when dealing with XML objects. Qualified Names appear in XML + * markup as prefixed names. But the prefixes themselves do not hold identity. + * Rather, it is the URIs that they contextually map to that hold the identity. + * Therefore, when passing a Qualified Name like "xyz:foo" among Java programs, + * one must provide a means to map "xyz" to a namespace. + * + *
+ * One solution has been to create a "QName" object that holds the namespace URI, + * as well as the prefix and local name, but this is not always an optimal solution, + * as when, for example, you want to use unique strings as keys in a dictionary + * object. Not having a string representation also makes it difficult to specify + * a namespaced identity outside the context of an XML document. + * + *
+ * In order to pass namespaced values to transformations, for instance when setting + * a property or a parameter on a {@link javax.xml.transform.Transformer} object, + * this specification defines that a String "qname" object parameter be passed as + * two-part string, the namespace URI enclosed in curly braces ({}), followed by + * the local name. If the qname has a null URI, then the String object only + * contains the local name. An application can safely check for a non-null URI by + * testing to see if the first character of the name is a '{' character. + * + *
+ * For example, if a URI and local name were obtained from an element defined with + * <xyz:foo xmlns:xyz="http://xyz.foo.com/yada/baz.html"/>, then the + * Qualified Name would be "{http://xyz.foo.com/yada/baz.html}foo". Note that the + * prefix is lost. + * + * + *
+ * Serialization of the result tree to a stream can be controlled with the + * {@link javax.xml.transform.Transformer#setOutputProperties} and the + * {@link javax.xml.transform.Transformer#setOutputProperty} methods. + * These properties only apply to stream results, they have no effect when + * the result is a DOM tree or SAX event stream. + * + *
+ * Strings that match the XSLT + * specification for xsl:output attributes can be referenced from the + * {@link javax.xml.transform.OutputKeys} class. Other strings can be + * specified as well. + * If the transformer does not recognize an output key, a + * {@link java.lang.IllegalArgumentException} is thrown, unless the key name + * is namespace qualified. Output key names + * that are namespace qualified are always allowed, although they may be + * ignored by some implementations. + * + *
+ * If all that is desired is the simple identity transformation of a + * source to a result, then {@link javax.xml.transform.TransformerFactory} + * provides a + * {@link javax.xml.transform.TransformerFactory#newTransformer()} method + * with no arguments. This method creates a Transformer that effectively copies + * the source to the result. This method may be used to create a DOM from SAX + * events or to create an XML or HTML stream from a DOM or SAX events. + * + *
+ * The transformation API throw three types of specialized exceptions. A + * {@link javax.xml.transform.TransformerFactoryConfigurationError} is parallel to + * the {@link javax.xml.parsers.FactoryConfigurationError}, and is thrown + * when a configuration problem with the TransformerFactory exists. This error + * will typically be thrown when the transformation factory class specified with + * the "javax.xml.transform.TransformerFactory" system property cannot be found or + * instantiated. + * + *
+ * A {@link javax.xml.transform.TransformerConfigurationException} + * may be thrown if for any reason a Transformer can not be created. A + * TransformerConfigurationException may be thrown if there is a syntax error in + * the transformation instructions, for example when + * {@link javax.xml.transform.TransformerFactory#newTransformer} is + * called. + * + *
+ * {@link javax.xml.transform.TransformerException} is a general + * exception that occurs during the course of a transformation. A transformer + * exception may wrap another exception, and if any of the + * {@link javax.xml.transform.TransformerException#printStackTrace()} + * methods are called on it, it will produce a list of stack dumps, starting from + * the most recent. The transformer exception also provides a + * {@link javax.xml.transform.SourceLocator} object which indicates where + * in the source tree or transformation instructions the error occurred. + * {@link javax.xml.transform.TransformerException#getMessageAndLocation()} + * may be called to get an error message with location info, and + * {@link javax.xml.transform.TransformerException#getLocationAsString()} + * may be called to get just the location string. + * + *
+ * Transformation warnings and errors are sent to an
+ * {@link javax.xml.transform.ErrorListener}, at which point the application may
+ * decide to report the error or warning, and may decide to throw an
+ * Exception for a non-fatal error. The ErrorListener
+ * may be set via {@link javax.xml.transform.TransformerFactory#setErrorListener}
+ * for reporting errors that have to do with syntax errors in the transformation
+ * instructions, or via {@link javax.xml.transform.Transformer#setErrorListener}
+ * to report errors that occur during the transformation. The ErrorListener
+ * on both objects will always be valid and non-null, whether set by
+ * the application or a default implementation provided by the processor.
+ * The default implementation provided by the processor will report all warnings
+ * and errors to System.err and does not throw any Exceptions.
+ * Applications are strongly encouraged to register and use
+ * ErrorListeners that insure proper behavior for warnings and
+ * errors.
+ *
+ *
+ *
+ * The API provides a way for URIs referenced from within the stylesheet
+ * instructions or within the transformation to be resolved by the calling
+ * application. This can be done by creating a class that implements the
+ * {@link javax.xml.transform.URIResolver} interface, with its one method,
+ * {@link javax.xml.transform.URIResolver#resolve}, and use this class to
+ * set the URI resolution for the transformation instructions or transformation
+ * with {@link javax.xml.transform.TransformerFactory#setURIResolver} or
+ * {@link javax.xml.transform.Transformer#setURIResolver}. The
+ * URIResolver.resolve method takes two String arguments, the URI
+ * found in the stylesheet instructions or built as part of the transformation
+ * process, and the base URI against which the first argument will be made absolute
+ * if the absolute URI is required.
+ * The returned {@link javax.xml.transform.Source} object must be usable by
+ * the transformer, as specified in its implemented features.
+ *
+ * @since 1.5
+ */
+
+package javax.xml.transform;
diff --git a/jaxp/src/java.xml/share/classes/javax/xml/transform/package.html b/jaxp/src/java.xml/share/classes/javax/xml/transform/package.html
deleted file mode 100644
index 2355a5ad1d8..00000000000
--- a/jaxp/src/java.xml/share/classes/javax/xml/transform/package.html
+++ /dev/null
@@ -1,229 +0,0 @@
-
-
-
-
-
-
This package defines the generic APIs for processing transformation -instructions, and performing a transformation from source to result. These -interfaces have no dependencies on SAX or the DOM standard, and try to make as -few assumptions as possible about the details of the source and result of a -transformation. It achieves this by defining -{@link javax.xml.transform.Source} and -{@link javax.xml.transform.Result} interfaces. -
- -To define concrete classes for the user, the API defines specializations -of the interfaces found at the root level. These interfaces are found in -{@link javax.xml.transform.sax}, {@link javax.xml.transform.dom}, -and {@link javax.xml.transform.stream}. -
- - -The API allows a concrete -{@link javax.xml.transform.TransformerFactory} object to be created from -the static function -{@link javax.xml.transform.TransformerFactory#newInstance}. -
- - -This API defines two interface objects called -{@link javax.xml.transform.Source} and -{@link javax.xml.transform.Result}. In order to pass Source and Result -objects to the interfaces, concrete classes must be used. -Three concrete representations are defined for each of these -objects: -{@link javax.xml.transform.stream.StreamSource} and -{@link javax.xml.transform.stream.StreamResult}, -{@link javax.xml.transform.sax.SAXSource} and -{@link javax.xml.transform.sax.SAXResult}, and -{@link javax.xml.transform.dom.DOMSource} and -{@link javax.xml.transform.dom.DOMResult}. Each of these objects defines -a FEATURE string (which is i the form of a URL), which can be passed into -{@link javax.xml.transform.TransformerFactory#getFeature} to see if the -given type of Source or Result object is supported. For instance, to test if a -DOMSource and a StreamResult is supported, you can apply the following -test. -
- -
-
-TransformerFactory tfactory = TransformerFactory.newInstance();
-if (tfactory.getFeature(DOMSource.FEATURE) && tfactory.getFeature(StreamResult.FEATURE)) {
-...
-}
-
-
-
-
-Namespaces -present something of a problem area when dealing with XML objects. Qualified -Names appear in XML markup as prefixed names. But the prefixes themselves do -not hold identity. Rather, it is the URIs that they contextually map to that -hold the identity. Therefore, when passing a Qualified Name like "xyz:foo" -among Java programs, one must provide a means to map "xyz" to a namespace. -
- -One solution has been to create a "QName" object that holds the -namespace URI, as well as the prefix and local name, but this is not always an -optimal solution, as when, for example, you want to use unique strings as keys -in a dictionary object. Not having a string representation also makes it -difficult to specify a namespaced identity outside the context of an XML -document. -
- -In order to pass namespaced values to transformations, -for -instance when setting a property or a parameter on a -{@link javax.xml.transform.Transformer} object, -this specification defines that a -String "qname" object parameter be passed as two-part string, the namespace URI -enclosed in curly braces ({}), followed by the local name. If the qname has a -null URI, then the String object only contains the local name. An application -can safely check for a non-null URI by testing to see if the first character of -the name is a '{' character. -
- -For example, if a URI and local name were obtained from an element -defined with <xyz:foo xmlns:xyz="http://xyz.foo.com/yada/baz.html"/>, -then the Qualified Name would be "{http://xyz.foo.com/yada/baz.html}foo". -Note that the prefix is lost. -
- - -Serialization of the result tree to a stream can be controlled with -the {@link javax.xml.transform.Transformer#setOutputProperties} and the -{@link javax.xml.transform.Transformer#setOutputProperty} methods. -These properties only apply to stream results, they have no effect when -the result is a DOM tree or SAX event stream.
- -Strings that match the XSLT -specification for xsl:output attributes can be referenced from the -{@link javax.xml.transform.OutputKeys} class. Other strings can be -specified as well. -If the transformer does not recognize an output key, a -{@link java.lang.IllegalArgumentException} is thrown, unless the -key name is namespace qualified. Output key names -that are namespace qualified are always allowed, although they may be -ignored by some implementations.
- -If all that is desired is the simple identity transformation of a -source to a result, then {@link javax.xml.transform.TransformerFactory} -provides a -{@link javax.xml.transform.TransformerFactory#newTransformer()} method -with no arguments. This method creates a Transformer that effectively copies -the source to the result. This method may be used to create a DOM from SAX -events or to create an XML or HTML stream from a DOM or SAX events.
- -The transformation API throw three types of specialized exceptions. A -{@link javax.xml.transform.TransformerFactoryConfigurationError} is parallel to -the {@link javax.xml.parsers.FactoryConfigurationError}, and is thrown -when a configuration problem with the TransformerFactory exists. This error -will typically be thrown when the transformation factory class specified with -the "javax.xml.transform.TransformerFactory" system property cannot be found or -instantiated.
- -A {@link javax.xml.transform.TransformerConfigurationException} -may be thrown if for any reason a Transformer can not be created. A -TransformerConfigurationException may be thrown if there is a syntax error in -the transformation instructions, for example when -{@link javax.xml.transform.TransformerFactory#newTransformer} is -called.
- -{@link javax.xml.transform.TransformerException} is a general -exception that occurs during the course of a transformation. A transformer -exception may wrap another exception, and if any of the -{@link javax.xml.transform.TransformerException#printStackTrace()} -methods are called on it, it will produce a list of stack dumps, starting from -the most recent. The transformer exception also provides a -{@link javax.xml.transform.SourceLocator} object which indicates where -in the source tree or transformation instructions the error occurred. -{@link javax.xml.transform.TransformerException#getMessageAndLocation()} -may be called to get an error message with location info, and -{@link javax.xml.transform.TransformerException#getLocationAsString()} -may be called to get just the location string.
- -Transformation warnings and errors are sent to an
-{@link javax.xml.transform.ErrorListener}, at which point the
-application may decide to report the error or warning, and may decide to throw
-an Exception for a non-fatal error. The ErrorListener may be set via
-{@link javax.xml.transform.TransformerFactory#setErrorListener} for
-reporting errors that have to do with syntax errors in the transformation
-instructions, or via
-{@link javax.xml.transform.Transformer#setErrorListener} to report
-errors that occur during the transformation. The ErrorListener on both objects
-will always be valid and non-null, whether set by the application or a default
-implementation provided by the processor.
-The default implementation provided by the processor will report all warnings and errors to System.err
-and does not throw any Exceptions.
-Applications are strongly encouraged to register and use
-ErrorListeners that insure proper behavior for warnings and
-errors.
-
The API provides a way for URIs referenced from within the stylesheet
-instructions or within the transformation to be resolved by the calling
-application. This can be done by creating a class that implements the
-{@link javax.xml.transform.URIResolver} interface, with its one method,
-{@link javax.xml.transform.URIResolver#resolve}, and use this class to
-set the URI resolution for the transformation instructions or transformation
-with {@link javax.xml.transform.TransformerFactory#setURIResolver} or
-{@link javax.xml.transform.Transformer#setURIResolver}. The
-URIResolver.resolve method takes two String arguments, the URI found in the
-stylesheet instructions or built as part of the transformation process, and the
-base URI
-against which the first argument will be made absolute if the
-absolute URI is required.
-The returned {@link javax.xml.transform.Source} object must be usable by
-the transformer, as specified in its implemented features.
+ * The {@link javax.xml.transform.sax.SAXSource} class allows the + * setting of an {@link org.xml.sax.XMLReader} to be used for pulling + * parse events, and an {@link org.xml.sax.InputSource} that may be used to + * specify the SAX source. + *
+ * The {@link javax.xml.transform.sax.SAXResult} class allows the + * setting of a {@link org.xml.sax.ContentHandler} to be the receiver of + * SAX2 events from the transformation. + *
+ * The {@link javax.xml.transform.sax.SAXTransformerFactory} extends + * {@link javax.xml.transform.TransformerFactory} to provide factory + * methods for creating {@link javax.xml.transform.sax.TemplatesHandler}, + * {@link javax.xml.transform.sax.TransformerHandler}, and + * {@link org.xml.sax.XMLReader} instances. + *
+ * To obtain a {@link javax.xml.transform.sax.SAXTransformerFactory}, + * the caller must cast the {@link javax.xml.transform.TransformerFactory} + * instance returned from + * {@link javax.xml.transform.TransformerFactory#newInstance}. + * + *
+ * The {@link javax.xml.transform.sax.TransformerHandler} interface + * allows a transformation to be created from SAX2 parse events, which is a "push" + * model rather than the "pull" model that normally occurs for a transformation. + * Normal parse events are received through the + * {@link org.xml.sax.ContentHandler} interface, lexical events such as + * startCDATA and endCDATA are received through the + * {@link org.xml.sax.ext.LexicalHandler} interface, and events that signal + * the start or end of disabling output escaping are received via + * {@link org.xml.sax.ContentHandler#processingInstruction}, with the + * target parameter being + * {@link javax.xml.transform.Result#PI_DISABLE_OUTPUT_ESCAPING} and + * {@link javax.xml.transform.Result#PI_ENABLE_OUTPUT_ESCAPING}. If + * parameters, output properties, or other features need to be set on the + * Transformer handler, a {@link javax.xml.transform.Transformer} reference + * will need to be obtained from + * {@link javax.xml.transform.sax.TransformerHandler#getTransformer}, and + * the methods invoked from that reference. + * + *
+ * The {@link javax.xml.transform.sax.TemplatesHandler} interface + * allows the creation of {@link javax.xml.transform.Templates} objects + * from SAX2 parse events. Once the {@link org.xml.sax.ContentHandler} + * events are complete, the Templates object may be obtained from + * {@link javax.xml.transform.sax.TemplatesHandler#getTemplates}. Note that + * {@link javax.xml.transform.sax.TemplatesHandler#setSystemId} should + * normally be called in order to establish a base system ID from which relative + * URLs may be resolved. + *
+ * The {@link javax.xml.transform.sax.SAXTransformerFactory#newXMLFilter} + * method allows the creation of a {@link org.xml.sax.XMLFilter}, which + * encapsulates the SAX2 notion of a "pull" transformation. The resulting + * {@code XMLFilters} can be chained together so that a series of transformations + * can happen with one's output becoming another's input. + * + * @since 1.5 + */ + +package javax.xml.transform.sax; diff --git a/jaxp/src/java.xml/share/classes/javax/xml/transform/sax/package.html b/jaxp/src/java.xml/share/classes/javax/xml/transform/sax/package.html deleted file mode 100644 index 97dce462bdb..00000000000 --- a/jaxp/src/java.xml/share/classes/javax/xml/transform/sax/package.html +++ /dev/null @@ -1,104 +0,0 @@ - - - - - - - -
-This package implements SAX2-specific transformation APIs. It provides - classes which allow input from {@link org.xml.sax.ContentHandler} - events, and also classes that produce org.xml.sax.ContentHandler events. It - also provides methods to set the input source as an - {@link org.xml.sax.XMLReader}, or to use a - {@link org.xml.sax.InputSource} as the source. It also allows the - creation of a {@link org.xml.sax.XMLFilter}, which enables - transformations to "pull" from other transformations, and lets the transformer - to be used polymorphically as an {@link org.xml.sax.XMLReader}.
-The {@link javax.xml.transform.sax.SAXSource} class allows the - setting of an {@link org.xml.sax.XMLReader} to be used for "pulling" - parse events, and an {@link org.xml.sax.InputSource} that may be used to - specify the SAX source.
-The {@link javax.xml.transform.sax.SAXResult} class allows the - setting of a {@link org.xml.sax.ContentHandler} to be the receiver of - SAX2 events from the transformation. -
The {@link javax.xml.transform.sax.SAXTransformerFactory} extends - {@link javax.xml.transform.TransformerFactory} to provide factory - methods for creating {@link javax.xml.transform.sax.TemplatesHandler}, - {@link javax.xml.transform.sax.TransformerHandler}, and - {@link org.xml.sax.XMLReader} instances.
-To obtain a {@link javax.xml.transform.sax.SAXTransformerFactory}, - the caller must cast the {@link javax.xml.transform.TransformerFactory} - instance returned from - {@link javax.xml.transform.TransformerFactory#newInstance}. - -
The {@link javax.xml.transform.sax.TransformerHandler} interface - allows a transformation to be created from SAX2 parse events, which is a "push" - model rather than the "pull" model that normally occurs for a transformation. - Normal parse events are received through the - {@link org.xml.sax.ContentHandler} interface, lexical events such as - startCDATA and endCDATA are received through the - {@link org.xml.sax.ext.LexicalHandler} interface, and events that signal - the start or end of disabling output escaping are received via - {@link org.xml.sax.ContentHandler#processingInstruction}, with the - target parameter being - {@link javax.xml.transform.Result#PI_DISABLE_OUTPUT_ESCAPING} and - {@link javax.xml.transform.Result#PI_ENABLE_OUTPUT_ESCAPING}. If - parameters, output properties, or other features need to be set on the - Transformer handler, a {@link javax.xml.transform.Transformer} reference - will need to be obtained from - {@link javax.xml.transform.sax.TransformerHandler#getTransformer}, and - the methods invoked from that reference. - -
The {@link javax.xml.transform.sax.TemplatesHandler} interface - allows the creation of {@link javax.xml.transform.Templates} objects - from SAX2 parse events. Once the {@link org.xml.sax.ContentHandler} - events are complete, the Templates object may be obtained from - {@link javax.xml.transform.sax.TemplatesHandler#getTemplates}. Note that - {@link javax.xml.transform.sax.TemplatesHandler#setSystemId} should - normally be called in order to establish a base system ID from which relative - URLs may be resolved. -
The - {@link javax.xml.transform.sax.SAXTransformerFactory#newXMLFilter} - method allows the creation of a {@link org.xml.sax.XMLFilter}, which - encapsulates the SAX2 notion of a "pull" transformation. The following - illustrates several transformations chained together. Each filter points to a - parent {@link org.xml.sax.XMLReader}, and the final transformation is - caused by invoking {@link org.xml.sax.XMLReader#parse} on the final - reader in the chain.
- - diff --git a/jaxp/src/java.xml/share/classes/javax/xml/transform/stax/package-info.java b/jaxp/src/java.xml/share/classes/javax/xml/transform/stax/package-info.java new file mode 100644 index 00000000000..a17343f9985 --- /dev/null +++ b/jaxp/src/java.xml/share/classes/javax/xml/transform/stax/package-info.java @@ -0,0 +1,45 @@ +/* + * Copyright (c) 2015, 2017, 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. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * 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. + */ + +/** + * Provides StAX specific transformation classes. + * + *+ * The {@link javax.xml.transform.stax.StAXSource} class encapsulates a + * {@link javax.xml.stream.XMLStreamReader} or {@link javax.xml.stream.XMLEventReader} + * and can be used as an input where a {@link javax.xml.transform.Source} + * object is accepted. + * + *
+ * The {@link javax.xml.transform.stax.StAXResult} class encapsulates a + * {@link javax.xml.stream.XMLStreamWriter} or {@link javax.xml.stream.XMLEventWriter} + * and can be used as an output where a {@link javax.xml.transform.Result} + * object is accepted. + * + * + * @since 1.6 + */ + +package javax.xml.transform.stax; diff --git a/jaxp/src/java.xml/share/classes/javax/xml/transform/stax/package.html b/jaxp/src/java.xml/share/classes/javax/xml/transform/stax/package.html deleted file mode 100644 index 0275a36f737..00000000000 --- a/jaxp/src/java.xml/share/classes/javax/xml/transform/stax/package.html +++ /dev/null @@ -1,66 +0,0 @@ - - - - - - -
-- This package implements StAX-specific transformation APIs. It provides - classes which allow input from a StAX reader, that is, - {@link javax.xml.stream.XMLStreamReader} or {@link javax.xml.stream.XMLEventReader}, - and output to a StAX writer, that is, - {@link javax.xml.stream.XMLStreamWriter} or {@link javax.xml.stream.XMLEventWriter}. -
-- The {@link javax.xml.transform.stax.StAXSource} class encapsulates a - {@link javax.xml.stream.XMLStreamReader} or {@link javax.xml.stream.XMLEventReader} - and can be used as an input where a {@link javax.xml.transform.Source} - object is accepted. -
-- The {@link javax.xml.transform.stax.StAXResult} class encapsulates a - {@link javax.xml.stream.XMLStreamWriter} or {@link javax.xml.stream.XMLEventWriter} - and can be used as an output where a {@link javax.xml.transform.Result} - object is accepted. -
- - @since 1.6 - - - diff --git a/jaxp/src/java.xml/share/classes/javax/xml/transform/stream/package-info.java b/jaxp/src/java.xml/share/classes/javax/xml/transform/stream/package-info.java new file mode 100644 index 00000000000..9534e621efb --- /dev/null +++ b/jaxp/src/java.xml/share/classes/javax/xml/transform/stream/package-info.java @@ -0,0 +1,56 @@ +/* + * Copyright (c) 2015, 2017, 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. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * 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. + */ + +/** + * Provides stream and URI specific transformation classes. + * + *+ * The {@link javax.xml.transform.stream.StreamSource} class + * provides methods for specifying {@link java.io.InputStream} input, + * {@link java.io.Reader} input, and URL input in the form of strings. Even + * if an input stream or reader is specified as the source, + * {@link javax.xml.transform.stream.StreamSource#setSystemId} should still + * be called, so that the transformer can know from where it should resolve + * relative URIs. The public identifier is always optional: if the application + * writer includes one, it will be provided as part of the + * {@link javax.xml.transform.SourceLocator} information. + *
+ * The {@link javax.xml.transform.stream.StreamResult} class + * provides methods for specifying {@link java.io.OutputStream}, + * {@link java.io.Writer}, or an output system ID, as the output of the + * transformation result. + *
+ * Normally streams should be used rather than readers or writers, for + * both the Source and Result, since readers and writers already have the encoding + * established to and from the internal Unicode format. However, there are times + * when it is useful to write to a character stream, such as when using a + * StringWriter in order to write to a String, or in the case of reading source + * XML from a StringReader. + * + * + * @since 1.5 + */ + +package javax.xml.transform.stream; diff --git a/jaxp/src/java.xml/share/classes/javax/xml/transform/stream/package.html b/jaxp/src/java.xml/share/classes/javax/xml/transform/stream/package.html deleted file mode 100644 index ea52ecb692e..00000000000 --- a/jaxp/src/java.xml/share/classes/javax/xml/transform/stream/package.html +++ /dev/null @@ -1,64 +0,0 @@ - - - - - - - -
-This package implements stream- and URI- specific transformation APIs. -
-The {@link javax.xml.transform.stream.StreamSource} class - provides methods for specifying {@link java.io.InputStream} input, - {@link java.io.Reader} input, and URL input in the form of strings. Even - if an input stream or reader is specified as the source, - {@link javax.xml.transform.stream.StreamSource#setSystemId} should still - be called, so that the transformer can know from where it should resolve - relative URIs. The public identifier is always optional: if the application - writer includes one, it will be provided as part of the - {@link javax.xml.transform.SourceLocator} information.
-The {@link javax.xml.transform.stream.StreamResult} class - provides methods for specifying {@link java.io.OutputStream}, - {@link java.io.Writer}, or an output system ID, as the output of the - transformation result.
-Normally streams should be used rather than readers or writers, for - both the Source and Result, since readers and writers already have the encoding - established to and from the internal Unicode format. However, there are times - when it is useful to write to a character stream, such as when using a - StringWriter in order to write to a String, or in the case of reading source - XML from a StringReader.
- - diff --git a/jaxp/src/java.xml/share/classes/javax/xml/validation/package-info.java b/jaxp/src/java.xml/share/classes/javax/xml/validation/package-info.java new file mode 100644 index 00000000000..b4fb61b26ae --- /dev/null +++ b/jaxp/src/java.xml/share/classes/javax/xml/validation/package-info.java @@ -0,0 +1,133 @@ +/* + * Copyright (c) 2015, 2017, 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. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * 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. + */ + +/** + *+ * Provides an API for validation of XML documents. Validation is the + * process of verifying that an XML document is an instance of a specified XML + * schema. An XML schema defines the content model (also called a + * grammar or vocabulary) that its instance documents will + * represent. + * + *
+ * There are a number of popular technologies available for creating an XML schema. + * Some of the most popular ones include: + * + *
+ * While JAXP supports validation as a feature of an XML parser, represented by + * either a {@link javax.xml.parsers.SAXParser} or {@link javax.xml.parsers.DocumentBuilder} + * instance, the {@code Validation} API is preferred. + * + *
+ * The JAXP validation API decouples the validation of an instance document from + * the parsing of an XML document. This is advantageous for several reasons, + * some of which are: + * + *
+ * Usage example. The following example + * demonstrates validating an XML document with the Validation API + * (for readability, some exception handling is not shown): + * + *
+ *
+ * // parse an XML document into a DOM tree
+ * DocumentBuilder parser = DocumentBuilderFactory.newInstance().newDocumentBuilder();
+ * Document document = parser.parse(new File("instance.xml"));
+ *
+ * // create a SchemaFactory capable of understanding WXS schemas
+ * SchemaFactory factory = SchemaFactory.newInstance(XMLConstants.W3C_XML_SCHEMA_NS_URI);
+ *
+ * // load a WXS schema, represented by a Schema instance
+ * Source schemaFile = new StreamSource(new File("mySchema.xsd"));
+ * Schema schema = factory.newSchema(schemaFile);
+ *
+ * // create a Validator instance, which can be used to validate an instance document
+ * Validator validator = schema.newValidator();
+ *
+ * // validate the DOM tree
+ * try {
+ * validator.validate(new DOMSource(document));
+ * } catch (SAXException e) {
+ * // instance document is invalid!
+ * }
+ *
+ *
+ * The JAXP parsing API has been integrated with the Validation API. Applications
+ * may create a {@link javax.xml.validation.Schema} with the validation API
+ * and associate it with a {@link javax.xml.parsers.DocumentBuilderFactory} or
+ * a {@link javax.xml.parsers.SAXParserFactory} instance by using the
+ * {@link javax.xml.parsers.DocumentBuilderFactory#setSchema(Schema)} and
+ * {@link javax.xml.parsers.SAXParserFactory#setSchema(Schema)} methods.
+ * You should not both set a schema and call setValidating(true)
+ * on a parser factory. The former technique will cause parsers to use the new
+ * validation API; the latter will cause parsers to use their own internal validation
+ * facilities. Turning on both of these options simultaneously will cause
+ * either redundant behavior or error conditions.
+ *
+ *
+ * @since 1.5
+ */
+
+package javax.xml.validation;
diff --git a/jaxp/src/java.xml/share/classes/javax/xml/validation/package.html b/jaxp/src/java.xml/share/classes/javax/xml/validation/package.html
deleted file mode 100644
index e50c8334559..00000000000
--- a/jaxp/src/java.xml/share/classes/javax/xml/validation/package.html
+++ /dev/null
@@ -1,120 +0,0 @@
-
-
-
-
-
-
- This package provides an API for validation of XML documents. Validation is the process of verifying - that an XML document is an instance of a specified XML schema. An XML schema defines the - content model (also called a grammar or vocabulary) that its instance documents - will represent. -
-- There are a number of popular technologies available for creating an XML schema. Some of the most - popular include: -
-- Previous versions of JAXP supported validation as a feature of an XML parser, represented by - either a {@link javax.xml.parsers.SAXParser} or {@link javax.xml.parsers.DocumentBuilder} instance. -
-- The JAXP validation API decouples the validation of an instance document from the parsing of an - XML document. This is advantageous for several reasons, some of which are: -
-- Usage example. The following example demonstrates validating - an XML document with the Validation API (for readability, some exception handling is not shown): -
-
-
- // parse an XML document into a DOM tree
- DocumentBuilder parser = DocumentBuilderFactory.newInstance().newDocumentBuilder();
- Document document = parser.parse(new File("instance.xml"));
-
- // create a SchemaFactory capable of understanding WXS schemas
- SchemaFactory factory = SchemaFactory.newInstance(XMLConstants.W3C_XML_SCHEMA_NS_URI);
-
- // load a WXS schema, represented by a Schema instance
- Source schemaFile = new StreamSource(new File("mySchema.xsd"));
- Schema schema = factory.newSchema(schemaFile);
-
- // create a Validator instance, which can be used to validate an instance document
- Validator validator = schema.newValidator();
-
- // validate the DOM tree
- try {
- validator.validate(new DOMSource(document));
- } catch (SAXException e) {
- // instance document is invalid!
- }
-
-
- The JAXP parsing API has been integrated with the Validation API. Applications may create a {@link javax.xml.validation.Schema} with the validation API
- and associate it with a {@link javax.xml.parsers.DocumentBuilderFactory} or a {@link javax.xml.parsers.SAXParserFactory} instance
- by using the {@link javax.xml.parsers.DocumentBuilderFactory#setSchema(Schema)} and {@link javax.xml.parsers.SAXParserFactory#setSchema(Schema)}
- methods. You should not both set a schema and call setValidating(true) on a parser factory. The former technique
- will cause parsers to use the new validation API; the latter will cause parsers to use their own internal validation
- facilities. Turning on both of these options simultaneously will cause either redundant behavior or error conditions.
-
+ * The XPath API supports + * XML Path Language (XPath) Version 1.0 + * + *
+ * The XPath language provides a simple, concise syntax for selecting + * nodes from an XML document. XPath also provides rules for converting a + * node in an XML document object model (DOM) tree to a boolean, double, + * or string value. XPath is a W3C-defined language and an official W3C + * recommendation; the W3C hosts the XML Path Language (XPath) Version + * 1.0 specification. + * + * + *
+ * XPath started in life in 1999 as a supplement to the XSLT and + * XPointer languages, but has more recently become popular as a + * stand-alone language, as a single XPath expression can be used to + * replace many lines of DOM API code. + * + * + * + *
+ * An XPath expression is composed of a location + * path and one or more optional predicates. Expressions + * may also include XPath variables. + * + * + *
+ * The following is an example of a simple XPath expression: + * + *
+ *+ * + *+ * /foo/bar + *+ *
+ * This example would select the <bar> element in
+ * an XML document such as the following:
+ *
+ *
+ *+ * + *+ * <foo> + * <bar/> + * </foo> + *+ *
The expression /foo/bar is an example of a location
+ * path. While XPath location paths resemble Unix-style file system
+ * paths, an important distinction is that XPath expressions return
+ * all nodes that match the expression. Thus, all three
+ * <bar> elements in the following document would be
+ * selected by the /foo/bar expression:
+ *
+ *
+ *+ * + *+ * <foo> + * <bar/> + * <bar/> + * <bar/> + * </foo> + *+ *
+ * A special location path operator, //, selects nodes at
+ * any depth in an XML document. The following example selects all
+ * <bar> elements regardless of their location in a
+ * document:
+ *
+ *
+ *+ * + *+ * //bar + *+ *
+ * A wildcard operator, *, causes all element nodes to be selected.
+ * The following example selects all children elements of a
+ * <foo> element:
+ *
+ *
+ *+ * + *+ * /foo/* + *+ *
+ * In addition to element nodes, XPath location paths may also address + * attribute nodes, text nodes, comment nodes, and processing instruction + * nodes. The following table gives examples of location paths for each + * of these node types: + * + *
| Location Path | + *Description | + *
|---|---|
+ * /foo/bar/@id
+ * |
+ *
+ * Selects the attribute id of the <bar> element
+ * |
+ *
/foo/bar/text()
+ * |
+ *
+ * Selects the text nodes of the <bar> element. No
+ * distinction is made between escaped and non-escaped character data.
+ * |
+ *
/foo/bar/comment()
+ * |
+ *
+ * Selects all comment nodes contained in the <bar> element.
+ * |
+ *
/foo/bar/processing-instruction()
+ * |
+ *
+ * Selects all processing-instruction nodes contained in the
+ * <bar> element.
+ * |
+ *
+ * Predicates allow for refining the nodes selected by an XPath
+ * location path. Predicates are of the form
+ * [expression]. The following example selects all
+ * <foo> elements that contain an include
+ * attribute with the value of true:
+ *
+ *
+ *+ * + *+ * //foo[@include='true'] + *+ *
+ * Predicates may be appended to each other to further refine an + * expression, such as: + * + *
+ *+ * + * + *+ * //foo[@include='true'][@mode='bar'] + *+ *
+ * While XPath expressions select nodes in the XML document, the XPath + * API allows the selected nodes to be coalesced into one of the + * following data types: + * + *
BooleanNumberString
+ * The return type is specified by a {@link javax.xml.namespace.QName} parameter
+ * in method call used to evaluate the expression, which is either a call to
+ * XPathExpression.evalute(...) or XPath.evaluate(...)
+ * methods.
+ *
+ *
+ * When a Boolean return type is requested,
+ * Boolean.TRUE is returned if one or more nodes were
+ * selected; otherwise, Boolean.FALSE is returned.
+ *
+ *
+ * The String return type is a convenience for retrieving
+ * the character data from a text node, attribute node, comment node, or
+ * processing-instruction node. When used on an element node, the value
+ * of the child text nodes is returned.
+ *
+ *
+ * The Number return type attempts to coalesce the text
+ * of a node to a double data type.
+ *
+ *
+ *
XPathExpression.evaluteExpression(...) or
+ * XPath.evaluateExpression(...) methods.
+ *
+ * The XPath data types are mapped to Class types as follows:
+ * Boolean -- Boolean.classNumber -- Number.classString -- String.classNodeset -- XPathNodes.classNode -- Node.class+ * Of the subtypes of Number, only Double, Integer and Long are supported. + * + * + *
XPathExpression.evaluteExpression(...)
+ * or XPath.evaluateExpression(...) methods will be of one of these types.
+ *
+ *
+ *
+ * XPath location paths may be relative to a particular node in the
+ * document, known as the context. A context consists of:
+ *
+ * It is an XML document tree represented as a hierarchy of nodes, a + * {@link org.w3c.dom.Node} for example, in the JDK implementation. + * + * + *
+ *+ * + *+ * <widgets> + * <widget> + * <manufacturer/> + * <dimensions/> + * </widget> + * </widgets> + *+ *
+ * The <widget> element can be selected with the following process:
+ *
+ *
+ *
+ * // parse the XML as a W3C Document
+ * DocumentBuilder builder = DocumentBuilderFactory.newInstance().newDocumentBuilder();
+ * Document document = builder.parse(new File("/widgets.xml"));
+ *
+ * //Get an XPath object and evaluate the expression
+ * XPath xpath = XPathFactory.newInstance().newXPath();
+ * String expression = "/widgets/widget";
+ * Node widgetNode = (Node) xpath.evaluate(expression, document, XPathConstants.NODE);
+ *
+ * //or using the evaluateExpression method
+ * Node widgetNode = xpath.evaluateExpression(expression, document, Node.class);
+ *
+ *
+ *
+ *
+ * With a reference to the <widget> element, a
+ * relative XPath expression can be written to select the
+ * <manufacturer> child element:
+ *
+ *
+ *+ * + *+ * XPath xpath = XPathFactory.newInstance().newXPath(); + * String expression = "manufacturer"; + * Node manufacturerNode = (Node) xpath.evaluate(expression, widgetNode, XPathConstants.NODE); + * + * //or using the evaluateExpression method + * Node manufacturerNode = xpath.evaluateExpression(expression, widgetNode, Node.class); + *+ *
+ * In the above example, the XML file is read into a DOM Document before being passed + * to the XPath API. The following code demonstrates the use of InputSource to + * leave it to the XPath implementation to process it: + * + *
+ *
+ * XPath xpath = XPathFactory.newInstance().newXPath();
+ * String expression = "/widgets/widget";
+ * InputSource inputSource = new InputSource("widgets.xml");
+ * NodeList nodes = (NodeList) xpath.evaluate(expression, inputSource, XPathConstants.NODESET);
+ *
+ * //or using the evaluateExpression method
+ * XPathNodes nodes = xpath.evaluate(expression, inputSource, XPathNodes.class);
+ *
+ *
+ *
+ * + * In the above cases, the type of the expected results are known. In case where + * the result type is unknown or any type, the {@link javax.xml.xpath.XPathEvaluationResult} + * may be used to determine the return type. The following code demonstrates the usage: + *
+ *
+ * XPathEvaluationResult<?> result = xpath.evaluateExpression(expression, document);
+ * switch (result.type()) {
+ * case NODESET:
+ * XPathNodes nodes = (XPathNodes)result.value();
+ * ...
+ * break;
+ * }
+ *
+ *
+ *
+ * + * 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: + *
+ *
+ * int count = xpath.evaluate("count(/widgets/widget)", document, Integer.class);
+ *
+ *
+ *
+ * @since 1.5
+ *
+ */
+
+package javax.xml.xpath;
diff --git a/jaxp/src/java.xml/share/classes/javax/xml/xpath/package.html b/jaxp/src/java.xml/share/classes/javax/xml/xpath/package.html
deleted file mode 100644
index 839557fde12..00000000000
--- a/jaxp/src/java.xml/share/classes/javax/xml/xpath/package.html
+++ /dev/null
@@ -1,382 +0,0 @@
-
-
-
-
-
-
-
-This package provides an object-model neutral API for the
-evaluation of XPath expressions and access to the evaluation
-environment.
-
--The XPath API supports - XML Path Language (XPath) Version 1.0 - -
The XPath language provides a simple, concise syntax for selecting -nodes from an XML document. XPath also provides rules for converting a -node in an XML document object model (DOM) tree to a boolean, double, -or string value. XPath is a W3C-defined language and an official W3C -recommendation; the W3C hosts the XML Path Language (XPath) Version -1.0 specification. -
- -XPath started in life in 1999 as a supplement to the XSLT and -XPointer languages, but has more recently become popular as a -stand-alone language, as a single XPath expression can be used to -replace many lines of DOM API code. -
- - -An XPath expression is composed of a location -path and one or more optional predicates. Expressions -may also include XPath variables. -
- -The following is an example of a simple XPath expression:
- --- --/foo/bar --
This example would select the <bar> element in
-an XML document such as the following:
-- --<foo> - <bar/> -</foo> --
The expression /foo/bar is an example of a location
-path. While XPath location paths resemble Unix-style file system
-paths, an important distinction is that XPath expressions return
-all nodes that match the expression. Thus, all three
-<bar> elements in the following document would be
-selected by the /foo/bar expression:
-- --<foo> - <bar/> - <bar/> - <bar/> -</foo> --
A special location path operator, //, selects nodes at
-any depth in an XML document. The following example selects all
-<bar> elements regardless of their location in a
-document:
-- --//bar --
A wildcard operator, *, causes all element nodes to be selected.
-The following example selects all children elements of a
-<foo> element:
-
-
-- --/foo/* --
In addition to element nodes, XPath location paths may also address -attribute nodes, text nodes, comment nodes, and processing instruction -nodes. The following table gives examples of location paths for each -of these node types:
- -| Location Path | -Description | -
|---|---|
-/foo/bar/@id
- |
-Selects the attribute id of the <bar> element
- |
-
/foo/bar/text()
- |
-Selects the text nodes of the <bar> element. No
-distinction is made between escaped and non-escaped character data.
- |
-
/foo/bar/comment()
- |
-Selects all comment nodes contained in the <bar> element.
- |
-
/foo/bar/processing-instruction()
- |
-Selects all processing-instruction nodes contained in the
-<bar> element.
- |
-
Predicates allow for refining the nodes selected by an XPath
-location path. Predicates are of the form
-[expression]. The following example selects all
-<foo> elements that contain an include
-attribute with the value of true:
-- --//foo[@include='true'] --
Predicates may be appended to each other to further refine an -expression, such as:
- --- - --//foo[@include='true'][@mode='bar'] --
While XPath expressions select nodes in the XML document, the XPath -API allows the selected nodes to be coalesced into one of the -following data types:
- -BooleanNumberStringThe return type is specified by a {@link javax.xml.namespace.QName} parameter
-in method call used to evaluate the expression, which is either a call to
-XPathExpression.evalute(...) or XPath.evaluate(...)
-methods.
-
-
When a Boolean return type is requested,
-Boolean.TRUE is returned if one or more nodes were
-selected; otherwise, Boolean.FALSE is returned.
-
-
The String return type is a convenience for retrieving
-the character data from a text node, attribute node, comment node, or
-processing-instruction node. When used on an element node, the value
-of the child text nodes is returned.
-
-
The Number return type attempts to coalesce the text
-of a node to a double data type.
-
-
-
XPathExpression.evaluteExpression(...) or
-XPath.evaluateExpression(...) methods.
-
-The XPath data types are mapped to Class types as follows:
-Boolean -- Boolean.classNumber -- Number.classString -- String.classNodeset -- XPathNodes.classNode -- Node.class-Of the subtypes of Number, only Double, Integer and Long are supported. - - -
XPathExpression.evaluteExpression(...)
-or XPath.evaluateExpression(...) methods will be of one of these types.
-
-
-XPath location paths may be relative to a particular node in the
-document, known as the context. A context consists of:
-
-It is an XML document tree represented as a hierarchy of nodes, a -{@link org.w3c.dom.Node} for example, in the JDK implementation. - - -
-- --<widgets> -<widget> -<manufacturer/> -<dimensions/> -</widget> -</widgets> --
-The <widget> element can be selected with the following process:
-
-
-
-// parse the XML as a W3C Document
-DocumentBuilder builder = DocumentBuilderFactory.newInstance().newDocumentBuilder();
-Document document = builder.parse(new File("/widgets.xml"));
-
-//Get an XPath object and evaluate the expression
-XPath xpath = XPathFactory.newInstance().newXPath();
-String expression = "/widgets/widget";
-Node widgetNode = (Node) xpath.evaluate(expression, document, XPathConstants.NODE);
-
-//or using the evaluateExpression method
-Node widgetNode = xpath.evaluateExpression(expression, document, Node.class);
-
-
-
-With a reference to the <widget> element, a
-relative XPath expression can be written to select the
-<manufacturer> child element:
-- --XPath xpath = XPathFactory.newInstance().newXPath(); -String expression = "manufacturer"; -Node manufacturerNode = (Node) xpath.evaluate(expression, widgetNode, XPathConstants.NODE); - -//or using the evaluateExpression method -Node manufacturerNode = xpath.evaluateExpression(expression, widgetNode, Node.class); --
-In the above example, the XML file is read into a DOM Document before being passed -to the XPath API. The following code demonstrates the use of InputSource to -leave it to the XPath implementation to process it: - -
-
-XPath xpath = XPathFactory.newInstance().newXPath();
-String expression = "/widgets/widget";
-InputSource inputSource = new InputSource("widgets.xml");
-NodeList nodes = (NodeList) xpath.evaluate(expression, inputSource, XPathConstants.NODESET);
-
-//or using the evaluateExpression method
-XPathNodes nodes = xpath.evaluate(expression, inputSource, XPathNodes.class);
-
-
-
--In the above cases, the type of the expected results are known. In case where -the result type is unknown or any type, the {@link javax.xml.xpath.XPathEvaluationResult} -may be used to determine the return type. The following code demonstrates the usage: -
-
-XPathEvaluationResult<?> result = xpath.evaluateExpression(expression, document);
-switch (result.type()) {
- case NODESET:
- XPathNodes nodes = (XPathNodes)result.value();
- ...
- break;
-}
-
-
-
--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: -
-
-int count = xpath.evaluate("count(/widgets/widget)", document, Integer.class);
-
-
-
-@since 1.5
-
-
-
diff --git a/jaxp/src/java.xml/share/classes/org/w3c/dom/bootstrap/package-info.java b/jaxp/src/java.xml/share/classes/org/w3c/dom/bootstrap/package-info.java
new file mode 100644
index 00000000000..e05d14562af
--- /dev/null
+++ b/jaxp/src/java.xml/share/classes/org/w3c/dom/bootstrap/package-info.java
@@ -0,0 +1,32 @@
+/*
+ * Copyright (c) 2015, 2017, 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. Oracle designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * 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.
+ */
+
+/**
+ * Provides a factory for obtaining instances of DOMImplementation.
+ *
+ * @since 1.5
+ */
+
+package org.w3c.dom.bootstrap;
diff --git a/jaxp/src/java.xml/share/classes/org/w3c/dom/events/package-info.java b/jaxp/src/java.xml/share/classes/org/w3c/dom/events/package-info.java
new file mode 100644
index 00000000000..2792c7c3d3e
--- /dev/null
+++ b/jaxp/src/java.xml/share/classes/org/w3c/dom/events/package-info.java
@@ -0,0 +1,42 @@
+/*
+ * Copyright (c) 2015, 2017, 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. Oracle designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * 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.
+ */
+
+/**
+ * + * Provides interfaces for DOM Level 2 Events. Refer to the + * + * Document Object Model (DOM) Level 2 Events Specification + * , the DOM Events module builds on + * + * DOM Level 2 Core Specification and + * + * DOM Level 2 Views Specification + * that gives to programs and scripts a generic event system. + * + * + * @since 1.5 + */ + +package org.w3c.dom.events; diff --git a/jaxp/src/java.xml/share/classes/org/w3c/dom/ls/package-info.java b/jaxp/src/java.xml/share/classes/org/w3c/dom/ls/package-info.java new file mode 100644 index 00000000000..b1369d3ccc8 --- /dev/null +++ b/jaxp/src/java.xml/share/classes/org/w3c/dom/ls/package-info.java @@ -0,0 +1,39 @@ +/* + * Copyright (c) 2015, 2017, 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. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * 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. + */ + +/** + *
+ * Provides interfaces for DOM Level 3 Load and Save. Refer to the + * + * Document Object Model (DOM) Level 3 Load and Save Specification, + * the Load and Save interface allows programs and scripts to dynamically + * load the content of an XML document into a DOM document and serialize a DOM + * document into an XML document. + * + * + * @since 1.5 + */ + +package org.w3c.dom.ls; diff --git a/jaxp/src/java.xml/share/classes/org/w3c/dom/package-info.java b/jaxp/src/java.xml/share/classes/org/w3c/dom/package-info.java new file mode 100644 index 00000000000..e092bbebe40 --- /dev/null +++ b/jaxp/src/java.xml/share/classes/org/w3c/dom/package-info.java @@ -0,0 +1,38 @@ +/* + * Copyright (c) 2015, 2017, 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. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * 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. + */ +/** + * Provides the interfaces for the Document Object Model (DOM). Supports the + * + * Document Object Model (DOM) Level 2 Core Specification, + * + * Document Object Model (DOM) Level 3 Core Specification, + * and + * Document Object Model (DOM) Level 3 Load and Save Specification. + * + * + * @since 1.4 + */ + +package org.w3c.dom; diff --git a/jaxp/src/java.xml/share/classes/org/w3c/dom/package.html b/jaxp/src/java.xml/share/classes/org/w3c/dom/package.html deleted file mode 100644 index 673366bf326..00000000000 --- a/jaxp/src/java.xml/share/classes/org/w3c/dom/package.html +++ /dev/null @@ -1,13 +0,0 @@ - -
-+ * Provides interfaces for DOM Level 2 Range. Refer to the + * + * Document Object Model (DOM) Level 2 Traversal and Range Specification, + * the Range module defines specialized interfaces for identifying + * and manipulating a range in a document. + * + * + * @since 1.5 + */ + +package org.w3c.dom.ranges; diff --git a/jaxp/src/java.xml/share/classes/org/w3c/dom/ranges/package.html b/jaxp/src/java.xml/share/classes/org/w3c/dom/ranges/package.html deleted file mode 100644 index c2a59387ee8..00000000000 --- a/jaxp/src/java.xml/share/classes/org/w3c/dom/ranges/package.html +++ /dev/null @@ -1,111 +0,0 @@ - -
-- Document Object Model Level 2 Traversal and Range is a - platform and language-neutral interfaces that allow programs - and scripts to dynamically traverse and identify a range of - content in a document. The Document Object Model Level 2 - Traversal and Range build on the Document Object Model Level 2 - Core. -
-- The DOM Level 2 Traversal and Range specification is composed - of two modules. The two modules contain specialized interfaces - dedicated to traversing the document structure and identifying - and manipulating a range in a document. -
-- The DOM bindings are published under the W3C Software Copyright Notice - and License. The software license requires "Notice of any changes or - modifications to the W3C files, including the date changes were made." - Consequently, modified versions of the DOM bindings must document that - they do not conform to the W3C standard; in the case of the IDL binding, - the pragma prefix can no longer be 'w3c.org'; in the case of the Java - binding, the package names can no longer be in the 'org.w3c' package. -
-- Note: The original version of the W3C Software Copyright Notice - and License could be found at http://www.w3.org/Consortium/Legal/copyright-software-19980720 -
-- This W3C work (including software, documents, or other related items) is - being provided by the copyright holders under the following license. By - obtaining, using and/or copying this work, you (the licensee) agree that - you have read, understood, and will comply with the following terms and - conditions: -
-- Permission to use, copy, and modify this software and its documentation, - with or without modification, for any purpose and without fee or - royalty is hereby granted, provided that you include the following on ALL - copies of the software and documentation or portions thereof, including - modifications, that you make: -
-- THIS SOFTWARE AND DOCUMENTATION IS PROVIDED "AS IS," AND COPYRIGHT - HOLDERS MAKE NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, - INCLUDING BUT NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY OR FITNESS - FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF THE SOFTWARE OR - DOCUMENTATION WILL NOT INFRINGE ANY THIRD PARTY PATENTS, COPYRIGHTS, - TRADEMARKS OR OTHER RIGHTS. -
-- COPYRIGHT HOLDERS WILL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL OR - CONSEQUENTIAL DAMAGES ARISING OUT OF ANY USE OF THE SOFTWARE OR - DOCUMENTATION. -
-- The name and trademarks of copyright holders may NOT be used in - advertising or publicity pertaining to the software without specific, - written prior permission. Title to copyright in this software and any - associated documentation will at all times remain with copyright - holders. -
- - diff --git a/jaxp/src/java.xml/share/classes/org/w3c/dom/traversal/package-info.java b/jaxp/src/java.xml/share/classes/org/w3c/dom/traversal/package-info.java new file mode 100644 index 00000000000..c532be864e7 --- /dev/null +++ b/jaxp/src/java.xml/share/classes/org/w3c/dom/traversal/package-info.java @@ -0,0 +1,36 @@ +/* + * Copyright (c) 2015, 2017, 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. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * 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. + */ +/** + *+ * Provides interfaces for DOM Level 2 Traversal. Refer to the + * + * Document Object Model (DOM) Level 2 Traversal and Range Specification, + * the Traversal module contains specialized interfaces dedicated to + * traversing the document structure. + * + * @since 1.5 + */ + +package org.w3c.dom.traversal; diff --git a/jaxp/src/java.xml/share/classes/org/w3c/dom/views/package-info.java b/jaxp/src/java.xml/share/classes/org/w3c/dom/views/package-info.java new file mode 100644 index 00000000000..a2b59efb1c4 --- /dev/null +++ b/jaxp/src/java.xml/share/classes/org/w3c/dom/views/package-info.java @@ -0,0 +1,37 @@ +/* + * Copyright (c) 2015, 2017, 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. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * 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. + */ + +/** + * Provides interfaces for DOM Level 2 Views. Refer to the + * + * Document Object Model (DOM) Level 2 Views Specification, + * the Views module allows programs and scripts to dynamically access and update + * the content of a representation of a document. + * + * + * @since 1.8 + */ + +package org.w3c.dom.views; diff --git a/jaxp/src/java.xml/share/classes/org/xml/sax/ext/package-info.java b/jaxp/src/java.xml/share/classes/org/xml/sax/ext/package-info.java new file mode 100644 index 00000000000..a583af72e2d --- /dev/null +++ b/jaxp/src/java.xml/share/classes/org/xml/sax/ext/package-info.java @@ -0,0 +1,72 @@ +/* + * Copyright (c) 2015, 2017, 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. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * 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. + */ + +/** + * Provides interfaces to SAX2 facilities that + * conformant SAX drivers won't necessarily support. + * + *
+ * See http://www.saxproject.org + * for more information about SAX. + * + *
+ * This package is independent of the SAX2 core, though the functionality + * exposed generally needs to be implemented within a parser core. + * That independence has several consequences: + * + *
org.xml.sax.helpers.DefaultHandler or
+ * org.xml.sax.helpers.XMLFilterImpl classes.
+ * You can subclass these if you need such behavior, or
+ * use the helper classes found here.This package, SAX2-ext, is a standardized extension to SAX2. It is + * designed both to allow SAX parsers to pass certain types of information + * to applications, and to serve as a simple model for other SAX2 parser + * extension packages. Not all such extension packages should need to + * be recognized directly by parsers, however. + * As an example, most validation systems can be cleanly layered on top + * of parsers supporting the standardized SAX2 interfaces. + * + * @since 1.4 + */ + +package org.xml.sax.ext; diff --git a/jaxp/src/java.xml/share/classes/org/xml/sax/ext/package.html b/jaxp/src/java.xml/share/classes/org/xml/sax/ext/package.html deleted file mode 100644 index 74d63a5fba3..00000000000 --- a/jaxp/src/java.xml/share/classes/org/xml/sax/ext/package.html +++ /dev/null @@ -1,46 +0,0 @@ -
- - - --This package contains interfaces to SAX2 facilities that -conformant SAX drivers won't necessarily support. - -
See http://www.saxproject.org -for more information about SAX.
- -This package is independent of the SAX2 core, though the functionality -exposed generally needs to be implemented within a parser core. -That independence has several consequences:
- -org.xml.sax.helpers.DefaultHandler or
-org.xml.sax.helpers.XMLFilterImpl classes.
-You can subclass these if you need such behavior, or
-use the helper classes found here.This package, SAX2-ext, is a standardized extension to SAX2. It is -designed both to allow SAX parsers to pass certain types of information -to applications, and to serve as a simple model for other SAX2 parser -extension packages. Not all such extension packages should need to -be recognized directly by parsers, however. -As an example, most validation systems can be cleanly layered on top -of parsers supporting the standardized SAX2 interfaces.
- - diff --git a/jaxp/src/java.xml/share/classes/org/xml/sax/helpers/package-info.java b/jaxp/src/java.xml/share/classes/org/xml/sax/helpers/package-info.java new file mode 100644 index 00000000000..6c1cbff3865 --- /dev/null +++ b/jaxp/src/java.xml/share/classes/org/xml/sax/helpers/package-info.java @@ -0,0 +1,38 @@ +/* + * Copyright (c) 2015, 2017, 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. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * 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. + */ + +/** + * + * Provides helper classes, including + * support for bootstrapping SAX-based applications. + * + *+ * See http://www.saxproject.org + * for more information about SAX. + * + * @since 1.4 + */ + +package org.xml.sax.helpers; diff --git a/jaxp/src/java.xml/share/classes/org/xml/sax/helpers/package.html b/jaxp/src/java.xml/share/classes/org/xml/sax/helpers/package.html deleted file mode 100644 index 001f0e277aa..00000000000 --- a/jaxp/src/java.xml/share/classes/org/xml/sax/helpers/package.html +++ /dev/null @@ -1,11 +0,0 @@ -
- - - -This package contains "helper" classes, including -support for bootstrapping SAX-based applications. - -
See http://www.saxproject.org -for more information about SAX.
- - diff --git a/jaxp/src/java.xml/share/classes/org/xml/sax/package-info.java b/jaxp/src/java.xml/share/classes/org/xml/sax/package-info.java new file mode 100644 index 00000000000..419f3e7ab50 --- /dev/null +++ b/jaxp/src/java.xml/share/classes/org/xml/sax/package-info.java @@ -0,0 +1,327 @@ +/* + * Copyright (c) 2015, 2017, 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. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * 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. + */ + +/** + * Provides the core SAX APIs. + * Some SAX1 APIs are deprecated to encourage integration of + * namespace-awareness into designs of new applications + * and into maintenance of existing infrastructure. + * + *+ * See http://www.saxproject.org + * for more information about SAX. + * + * + *
+ * One of the essential characteristics of SAX2 is that it added
+ * feature flags which can be used to examine and perhaps modify
+ * parser modes, in particular modes such as validation.
+ * Since features are identified by (absolute) URIs, anyone
+ * can define such features.
+ * Currently defined standard feature URIs have the prefix
+ * http://xml.org/sax/features/ before an identifier such as
+ * validation. Turn features on or off using
+ * setFeature. Those standard identifiers are:
+ *
+ *
+ *
| Feature ID | + *Access | + *Default | + *Description | + *
|---|---|---|---|
| external-general-entities | + *read/write | + *unspecified | + *Reports whether this parser processes external + * general entities; always true if validating. + * | + *
| external-parameter-entities | + *read/write | + *unspecified | + *Reports whether this parser processes external + * parameter entities; always true if validating. + * | + *
| is-standalone | + *(parsing) read-only, (not parsing) none | + *not applicable | + *May be examined only during a parse, after the + * startDocument() callback has been completed; read-only. + * The value is true if the document specified standalone="yes" in + * its XML declaration, and otherwise is false. + * | + *
| lexical-handler/parameter-entities | + *read/write | + *unspecified | + *A value of "true" indicates that the LexicalHandler will report + * the beginning and end of parameter entities. + * | + *
| namespaces | + *read/write | + *true | + *A value of "true" indicates namespace URIs and unprefixed local names + * for element and attribute names will be available. + * | + *
| namespace-prefixes | + *read/write | + *false | + *A value of "true" indicates that XML qualified names (with prefixes) and + * attributes (including xmlns* attributes) will be available. + * | + *
| resolve-dtd-uris | + *read/write | + *true | + * A value of "true" indicates that system IDs in declarations will
+ * be absolutized (relative to their base URIs) before reporting.
+ * (That is the default behavior for all SAX2 XML parsers.)
+ * A value of "false" indicates those IDs will not be absolutized;
+ * parsers will provide the base URI from
+ * Locator.getSystemId().
+ * This applies to system IDs passed in
|
+ *
| string-interning | + *read/write | + *unspecified | + *Has a value of "true" if all XML names (for elements, prefixes, + * attributes, entities, notations, and local names), + * as well as Namespace URIs, will have been interned + * using java.lang.String.intern. This supports fast + * testing of equality/inequality against string constants, + * rather than forcing slower calls to String.equals(). + * | + *
| unicode-normalization-checking | + *read/write | + *false | + *Controls whether the parser reports Unicode normalization + * errors as described in section 2.13 and Appendix B of the + * XML 1.1 Recommendation. If true, Unicode normalization + * errors are reported using the ErrorHandler.error() callback. + * Such errors are not fatal in themselves (though, obviously, + * other Unicode-related encoding errors may be). + * | + *
| use-attributes2 | + *read-only | + *not applicable | + *Returns "true" if the Attributes objects passed by + * this parser in ContentHandler.startElement() + * implement the org.xml.sax.ext.Attributes2 interface. + * That interface exposes additional DTD-related information, + * such as whether the attribute was specified in the + * source text rather than defaulted. + * | + *
| use-locator2 | + *read-only | + *not applicable | + *Returns "true" if the Locator objects passed by + * this parser in ContentHandler.setDocumentLocator() + * implement the org.xml.sax.ext.Locator2 interface. + * That interface exposes additional entity information, + * such as the character encoding and XML version used. + * | + *
| use-entity-resolver2 | + *read/write | + *true | + *Returns "true" if, when setEntityResolver is given + * an object implementing the org.xml.sax.ext.EntityResolver2 interface, + * those new methods will be used. + * Returns "false" to indicate that those methods will not be used. + * | + *
| validation | + *read/write | + *unspecified | + *Controls whether the parser is reporting all validity + * errors; if true, all external entities will be read. + * | + *
| xmlns-uris | + *read/write | + *false | + *Controls whether, when the namespace-prefixes feature + * is set, the parser treats namespace declaration attributes as + * being in the http://www.w3.org/2000/xmlns/ namespace. + * By default, SAX2 conforms to the original "Namespaces in XML" + * Recommendation, which explicitly states that such attributes are + * not in any namespace. + * Setting this optional flag to "true" makes the SAX2 events conform to + * a later backwards-incompatible revision of that recommendation, + * placing those attributes in a namespace. + * | + *
| xml-1.1 | + *read-only | + *not applicable | + *Returns "true" if the parser supports both XML 1.1 and XML 1.0. + * Returns "false" if the parser supports only XML 1.0. + * | + *
+ * Support for the default values of the + * namespaces and namespace-prefixes + * properties is required. + * Support for any other feature flags is entirely optional. + * + * + *
+ * For default values not specified by SAX2, + * each XMLReader implementation specifies its default, + * or may choose not to expose the feature flag. + * Unless otherwise specified here, + * implementations may support changing current values + * of these standard feature flags, but not while parsing. + * + * + *
+ * For parser interface characteristics that are described
+ * as objects, a separate namespace is defined. The
+ * objects in this namespace are again identified by URI, and
+ * the standard property URIs have the prefix
+ * http://xml.org/sax/properties/ before an identifier such as
+ * lexical-handler or
+ * dom-node. Manage those properties using
+ * setProperty(). Those identifiers are:
+ *
+ *
| Property ID | + *Description | + *
|---|---|
| declaration-handler | + *Used to see most DTD declarations except those treated + * as lexical ("document element name is ...") or which are + * mandatory for all SAX parsers (DTDHandler). + * The Object must implement org.xml.sax.ext.DeclHandler. + * | + *
| document-xml-version | + *May be examined only during a parse, after the startDocument() + * callback has been completed; read-only. This property is a + * literal string describing the actual XML version of the document, + * such as "1.0" or "1.1". + * | + *
| dom-node | + *For "DOM Walker" style parsers, which ignore their + * parser.parse() parameters, this is used to + * specify the DOM (sub)tree being walked by the parser. + * The Object must implement the + * org.w3c.dom.Node interface. + * | + *
| lexical-handler | + *Used to see some syntax events that are essential in some + * applications: comments, CDATA delimiters, selected general + * entity inclusions, and the start and end of the DTD + * (and declaration of document element name). + * The Object must implement org.xml.sax.ext.LexicalHandler. + * | + *
| xml-string | + *Readable only during a parser callback, this exposes a TBS + * chunk of characters responsible for the current event. + * | + *
+ * All of these standard properties are optional. + * XMLReader implementations are not required to support them. + * + * + * @since 1.4 + */ + +package org.xml.sax; diff --git a/jaxp/src/java.xml/share/classes/org/xml/sax/package.html b/jaxp/src/java.xml/share/classes/org/xml/sax/package.html deleted file mode 100644 index 2c16b87f34c..00000000000 --- a/jaxp/src/java.xml/share/classes/org/xml/sax/package.html +++ /dev/null @@ -1,305 +0,0 @@ -
- - - -This package provides the core SAX APIs. -Some SAX1 APIs are deprecated to encourage integration of -namespace-awareness into designs of new applications -and into maintenance of existing infrastructure.
- -See http://www.saxproject.org -for more information about SAX.
- - - One of the essential characteristics of SAX2 is that it added
-feature flags which can be used to examine and perhaps modify
-parser modes, in particular modes such as validation.
-Since features are identified by (absolute) URIs, anyone
-can define such features.
-Currently defined standard feature URIs have the prefix
-http://xml.org/sax/features/ before an identifier such as
-validation. Turn features on or off using
-setFeature. Those standard identifiers are:
| Feature ID | -Access | -Default | -Description | -
|---|---|---|---|
| external-general-entities | -read/write | -unspecified | -Reports whether this parser processes external - general entities; always true if validating. - | -
| external-parameter-entities | -read/write | -unspecified | -Reports whether this parser processes external - parameter entities; always true if validating. - | -
| is-standalone | -(parsing) read-only, (not parsing) none | -not applicable | -May be examined only during a parse, after the - startDocument() callback has been completed; read-only. - The value is true if the document specified standalone="yes" in - its XML declaration, and otherwise is false. - | -
| lexical-handler/parameter-entities | -read/write | -unspecified | -A value of "true" indicates that the LexicalHandler will report - the beginning and end of parameter entities. - | -
| namespaces | -read/write | -true | -A value of "true" indicates namespace URIs and unprefixed local names - for element and attribute names will be available. - | -
| namespace-prefixes | -read/write | -false | -A value of "true" indicates that XML qualified names (with prefixes) and - attributes (including xmlns* attributes) will be available. - | -
| resolve-dtd-uris | -read/write | -true | - A value of "true" indicates that system IDs in declarations will
- be absolutized (relative to their base URIs) before reporting.
- (That is the default behavior for all SAX2 XML parsers.)
- A value of "false" indicates those IDs will not be absolutized;
- parsers will provide the base URI from
- Locator.getSystemId().
- This applies to system IDs passed in
|
-
| string-interning | -read/write | -unspecified | -Has a value of "true" if all XML names (for elements, prefixes, - attributes, entities, notations, and local names), - as well as Namespace URIs, will have been interned - using java.lang.String.intern. This supports fast - testing of equality/inequality against string constants, - rather than forcing slower calls to String.equals(). - | -
| unicode-normalization-checking | -read/write | -false | -Controls whether the parser reports Unicode normalization - errors as described in section 2.13 and Appendix B of the - XML 1.1 Recommendation. If true, Unicode normalization - errors are reported using the ErrorHandler.error() callback. - Such errors are not fatal in themselves (though, obviously, - other Unicode-related encoding errors may be). - | -
| use-attributes2 | -read-only | -not applicable | -Returns "true" if the Attributes objects passed by - this parser in ContentHandler.startElement() - implement the org.xml.sax.ext.Attributes2 interface. - That interface exposes additional DTD-related information, - such as whether the attribute was specified in the - source text rather than defaulted. - | -
| use-locator2 | -read-only | -not applicable | -Returns "true" if the Locator objects passed by - this parser in ContentHandler.setDocumentLocator() - implement the org.xml.sax.ext.Locator2 interface. - That interface exposes additional entity information, - such as the character encoding and XML version used. - | -
| use-entity-resolver2 | -read/write | -true | -Returns "true" if, when setEntityResolver is given - an object implementing the org.xml.sax.ext.EntityResolver2 interface, - those new methods will be used. - Returns "false" to indicate that those methods will not be used. - | -
| validation | -read/write | -unspecified | -Controls whether the parser is reporting all validity - errors; if true, all external entities will be read. - | -
| xmlns-uris | -read/write | -false | -Controls whether, when the namespace-prefixes feature - is set, the parser treats namespace declaration attributes as - being in the http://www.w3.org/2000/xmlns/ namespace. - By default, SAX2 conforms to the original "Namespaces in XML" - Recommendation, which explicitly states that such attributes are - not in any namespace. - Setting this optional flag to "true" makes the SAX2 events conform to - a later backwards-incompatible revision of that recommendation, - placing those attributes in a namespace. - | -
| xml-1.1 | -read-only | -not applicable | -Returns "true" if the parser supports both XML 1.1 and XML 1.0. - Returns "false" if the parser supports only XML 1.0. - | -
Support for the default values of the -namespaces and namespace-prefixes -properties is required. -Support for any other feature flags is entirely optional. -
- -For default values not specified by SAX2, -each XMLReader implementation specifies its default, -or may choose not to expose the feature flag. -Unless otherwise specified here, -implementations may support changing current values -of these standard feature flags, but not while parsing. -
- - For parser interface characteristics that are described
-as objects, a separate namespace is defined. The
-objects in this namespace are again identified by URI, and
-the standard property URIs have the prefix
-http://xml.org/sax/properties/ before an identifier such as
-lexical-handler or
-dom-node. Manage those properties using
-setProperty(). Those identifiers are:
| Property ID | -Description | -
|---|---|
| declaration-handler | -Used to see most DTD declarations except those treated - as lexical ("document element name is ...") or which are - mandatory for all SAX parsers (DTDHandler). - The Object must implement org.xml.sax.ext.DeclHandler. - | -
| document-xml-version | -May be examined only during a parse, after the startDocument() - callback has been completed; read-only. This property is a - literal string describing the actual XML version of the document, - such as "1.0" or "1.1". - | -
| dom-node | -For "DOM Walker" style parsers, which ignore their - parser.parse() parameters, this is used to - specify the DOM (sub)tree being walked by the parser. - The Object must implement the - org.w3c.dom.Node interface. - | -
| lexical-handler | -Used to see some syntax events that are essential in some - applications: comments, CDATA delimiters, selected general - entity inclusions, and the start and end of the DTD - (and declaration of document element name). - The Object must implement org.xml.sax.ext.LexicalHandler. - | -
| xml-string | -Readable only during a parser callback, this exposes a TBS - chunk of characters responsible for the current event. | -
All of these standard properties are optional; -XMLReader implementations need not support them. -
- -