Mercurial > hg > openjdk > jdk9 > jaxp
changeset 1133:a208fa9beeee
8180349: Review JAXP Java SE 9 API javadocs
Reviewed-by: rriggs, lancea
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/src/java.xml/share/classes/javax/xml/catalog/package-info.java Wed May 24 14:10:04 2017 -0700 @@ -0,0 +1,71 @@ +/* + * 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 implementing + * <a href="https://www.oasis-open.org/committees/download.php/14809/xml-catalogs.html"> + * XML Catalogs OASIS Standard V1.1, 7 October 2005</a>. + * + * <p> + * 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. + * <p> + * The XML Catalog API defines the following interfaces: + * <ul> + * <li>{@link Catalog} -- The {@link Catalog} interface represents an entity + * catalog as defined by the Catalog standard. A {@link Catalog} object + * is immutable. Once created, it can be used to find matches in a + * {@code system}, {@code public} or {@code uri} entry. + * A custom resolver implementation may find it useful for locating local + * resources through a catalog. + * </li> + * <li>{@link CatalogFeatures} -- The {@link CatalogFeatures} class holds all + * of the features and properties the Catalog API supports, including + * {@code javax.xml.catalog.files}, {@code javax.xml.catalog.defer}, + * {@code javax.xml.catalog.prefer}, and {@code javax.xml.catalog.resolve}. + * </li> + * <li>{@link CatalogManager} -- The {@link CatalogManager} class manages the + * creation of XML catalogs and catalog resolvers. + * </li> + * <li>{@link CatalogResolver} -- The {@link CatalogResolver} class is a + * {@code Catalog} resolver that implements {@link org.xml.sax.EntityResolver}, + * {@link javax.xml.stream.XMLResolver}, {@link org.w3c.dom.ls.LSResourceResolver}, + * and {@link javax.xml.transform.URIResolver}, and resolves external + * references using catalogs. + * </li> + * </ul> + * <p> + * 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;
--- a/src/java.xml/share/classes/javax/xml/catalog/package.html Tue May 23 23:27:20 2017 -0700 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,44 +0,0 @@ -<!DOCTYPE HTML> -<html> -<head> -<!-- -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. ---> -</head> -<body> - - Provides the classes for implementing - <a href="https://www.oasis-open.org/committees/download.php/14809/xml-catalogs.html"> - XML Catalogs OASIS Standard V1.1, 7 October 2005</a>. - - <p> - 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</code> to be thrown. - </p> - -@since 9 - -</body> -</html>
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/src/java.xml/share/classes/javax/xml/datatype/package-info.java Wed May 24 14:10:04 2017 -0700 @@ -0,0 +1,172 @@ +/* + * 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. + */ + +/** + * + * <p> + * Defines XML/Java Type Mappings. + * + * <p> + * This API provides XML/Java type mappings. + * + * <p> + * The following XML standards apply: + * + * <ul> + * <li><a href="http://www.w3.org/TR/xmlschema-2/#dateTime"> + * W3C XML Schema 1.0 Part 2, Section 3.2.7-14</a> + * </li> + * <li><a href="http://www.w3.org/TR/xpath-datamodel#dt-dayTimeDuration"> + * XQuery 1.0 and XPath 2.0 Data Model, xdt:dayTimeDuration</a> + * </li> + * <li><a href="http://www.w3.org/TR/xpath-datamodel#dt-yearMonthDuration"> + * XQuery 1.0 and XPath 2.0 Data Model, xdt:yearMonthDuration</a> + * </li> + * </ul> + * + * <hr> + * + * <table class="striped"> + * <caption> W3C XML Schema/Java Type Mappings</caption> + * <thead> + * <tr> + * <th>W3C XML Schema Data Type</th> + * <th>Java Data Type</th> + * </tr> + * </thead> + * + * <tbody> + * <tr> + * <td>xs:date</td> + * <td>{@link javax.xml.datatype.XMLGregorianCalendar}</td> + * </tr> + * <tr> + * <td>xs:dateTime</td> + * <td>{@link javax.xml.datatype.XMLGregorianCalendar}</td> + * </tr> + * <tr> + * <td>xs:duration</td> + * <td>{@link javax.xml.datatype.Duration}</td> + * </tr> + * <tr> + * <td>xs:gDay</td> + * <td>{@link javax.xml.datatype.XMLGregorianCalendar}</td> + * </tr> + * <tr> + * <td>xs:gMonth </td> + * <td>{@link javax.xml.datatype.XMLGregorianCalendar}</td> + * </tr> + * <tr> + * <td>xs:gMonthDay</td> + * <td>{@link javax.xml.datatype.XMLGregorianCalendar}</td> + * </tr> + * <tr> + * <td>xs:gYear</td> + * <td>{@link javax.xml.datatype.XMLGregorianCalendar}</td> + * </tr> + * <tr> + * <td>xs:gYearMonth</td> + * <td>{@link javax.xml.datatype.XMLGregorianCalendar}</td> + * </tr> + * <tr> + * <td>xs:time</td> + * <td>{@link javax.xml.datatype.XMLGregorianCalendar}</td> + * </tr> + * + * </tbody> + * </table> + * + * <hr> + * + * + * <table class="striped"> + * <caption>XQuery and XPath/Java Type Mappings</caption> + * <thead> + * <tr> + * <th>XQuery 1.0 and XPath 2.0 Data Model</th> + * <th>Java Data Type</th> + * </tr> + * </thead> + * + * <tbody> + * <tr> + * <td>xdt:dayTimeDuration</td> + * <td>{@link javax.xml.datatype.Duration}</td> + * </tr> + * <tr> + * <td>xdt:yearMonthDuration</td> + * <td>{@link javax.xml.datatype.Duration}</td> + * </tr> + * </tbody> + * </table> + * + * <hr> + * + * <p> + * W3C XML Schema data types that have a "<em>natural</em>" 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: + * + * <ul> + * <li>xs:anySimpleType</li> + * <li>xs:base64Binary</li> + * <li>xs:boolean</li> + * <li>xs:byte</li> + * <li>xs:decimal</li> + * <li>xs:double</li> + * <li>xs:float</li> + * <li>xs:hexBinary</li> + * <li>xs:int</li> + * <li>xs:integer</li> + * <li>xs:long</li> + * <li>xs:QName</li> + * <li>xs:short</li> + * <li>xs:string</li> + * <li>xs:unsignedByte</li> + * <li>xs:unsignedInt</li> + * <li>xs:unsignedShort</li> + * </ul> + * + * <hr> + * + * <ul> + * <li>Author <a href="mailto:Jeff.Suttor@Sun.com">Jeff Suttor</a></li> + * <li>See <a href="http://www.w3.org/TR/xmlschema-2/#dateTime"> + * W3C XML Schema 1.0 Part 2, Section 3.2.7-14</a> + * </li> + * <li>See <a href="http://www.w3.org/TR/xpath-datamodel#dt-dayTimeDuration"> + * XQuery 1.0 and XPath 2.0 Data Model, xdt:dayTimeDuration</a> + * </li> + * <li>See <a href="http://www.w3.org/TR/xpath-datamodel#dt-yearMonthDuration"> + * XQuery 1.0 and XPath 2.0 Data Model, xdt:yearMonthDuration</a> + * </li> + * <li>Since 1.5</li> + * </ul> + * + * <hr> + * @since 1.5 + */ + +package javax.xml.datatype;
--- a/src/java.xml/share/classes/javax/xml/datatype/package.html Tue May 23 23:27:20 2017 -0700 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,170 +0,0 @@ -<!doctype html> -<!-- -Copyright (c) 2004, 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. ---> - -<html> - - <head> - <title>javax.xml.xpath</title> - - <meta name="@author" content="mailto:Jeff.Suttor@Sun.com" /> - <meta name="@see" content='<a href="http://www.w3.org/TR/xmlschema-2/#dateTime">W3C XML Schema 1.0 Part 2, Section 3.2.7-14</a>' /> - <meta name="@see" content='<a href="http://www.w3.org/TR/xpath-datamodel#dt-dayTimeDuration">XQuery 1.0 and XPath 2.0 Data Model, xdt:dayTimeDuration</a>' /> - <meta name="@see" content='<a href="http://www.w3.org/TR/xpath-datamodel#dt-yearMonthDuration">XQuery 1.0 and XPath 2.0 Data Model, xdt:yearMonthDuration</a>' /> - <meta name="@since" content="1.5" /> - </head> - - <body> - - <p>XML/Java Type Mappings.</p> - - <p><code>javax.xml.datatype</code>API provides XML/Java type mappings.</p> - - <p>The following XML standards apply:</p> - <ul> - <li><a href="http://www.w3.org/TR/xmlschema-2/#dateTime">W3C XML Schema 1.0 Part 2, Section 3.2.7-14</a></li> - <li><a href="http://www.w3.org/TR/xpath-datamodel#dt-dayTimeDuration">XQuery 1.0 and XPath 2.0 Data Model, xdt:dayTimeDuration</a></li> - <li><a href="http://www.w3.org/TR/xpath-datamodel#dt-yearMonthDuration">XQuery 1.0 and XPath 2.0 Data Model, xdt:yearMonthDuration</a></li> - </ul> - - <hr> - - <table class="striped"> - <caption> W3C XML Schema/Java Type Mappings</caption> - <thead> - <tr> - <th>W3C XML Schema Data Type</th> - <th>Java Data Type</th> - </tr> - </thead> - - <tbody> - <tr> - <td>xs:date</td> - <td>{@link javax.xml.datatype.XMLGregorianCalendar}</td> - </tr> - <tr> - <td>xs:dateTime</td> - <td>{@link javax.xml.datatype.XMLGregorianCalendar}</td> - </tr> - <tr> - <td>xs:duration</td> - <td>{@link javax.xml.datatype.Duration}</td> - </tr> - <tr> - <td>xs:gDay</td> - <td>{@link javax.xml.datatype.XMLGregorianCalendar}</td> - </tr> - <tr> - <td>xs:gMonth </td> - <td>{@link javax.xml.datatype.XMLGregorianCalendar}</td> - </tr> - <tr> - <td>xs:gMonthDay</td> - <td>{@link javax.xml.datatype.XMLGregorianCalendar}</td> - </tr> - <tr> - <td>xs:gYear</td> - <td>{@link javax.xml.datatype.XMLGregorianCalendar}</td> - </tr> - <tr> - <td>xs:gYearMonth</td> - <td>{@link javax.xml.datatype.XMLGregorianCalendar}</td> - </tr> - <tr> - <td>xs:time</td> - <td>{@link javax.xml.datatype.XMLGregorianCalendar}</td> - </tr> - - </tbody> - </table> - - <hr> - - - <table class="striped"> - <caption>XQuery and XPath/Java Type Mappings</caption> - <thead> - <tr> - <th>XQuery 1.0 and XPath 2.0 Data Model</th> - <th>Java Data Type</th> - </tr> - </thead> - - <tbody> - <tr> - <td>xdt:dayTimeDuration</td> - <td>{@link javax.xml.datatype.Duration}</td> - </tr> - <tr> - <td>xdt:yearMonthDuration</td> - <td>{@link javax.xml.datatype.Duration}</td> - </tr> - </tbody> - </table> - - <hr> - - <p> - W3C XML Schema data types that have a "<em>natural</em>" 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: - </p> - <ul> - <li>xs:anySimpleType</li> - <li>xs:base64Binary</li> - <li>xs:boolean</li> - <li>xs:byte</li> - <li>xs:decimal</li> - <li>xs:double</li> - <li>xs:float</li> - <li>xs:hexBinary</li> - <li>xs:int</li> - <li>xs:integer</li> - <li>xs:long</li> - <li>xs:QName</li> - <li>xs:short</li> - <li>xs:string</li> - <li>xs:unsignedByte</li> - <li>xs:unsignedInt</li> - <li>xs:unsignedShort</li> - </ul> - - <hr> - - - <ul> - <li>Author <a href="mailto:Jeff.Suttor@Sun.com">Jeff Suttor</a></li> - <li>See <a href="http://www.w3.org/TR/xmlschema-2/#dateTime">W3C XML Schema 1.0 Part 2, Section 3.2.7-14</a></li> - <li>See <a href="http://www.w3.org/TR/xpath-datamodel#dt-dayTimeDuration">XQuery 1.0 and XPath 2.0 Data Model, xdt:dayTimeDuration</a></li> - <li>See <a href="http://www.w3.org/TR/xpath-datamodel#dt-yearMonthDuration">XQuery 1.0 and XPath 2.0 Data Model, xdt:yearMonthDuration</a></li> - <li>Since 1.5</li> - </ul> - - <hr> - - - </body> -</html>
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/src/java.xml/share/classes/javax/xml/namespace/package-info.java Wed May 24 14:10:04 2017 -0700 @@ -0,0 +1,49 @@ +/* + * 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. + */ + +/** + * + * <p> + * Defines XML Namespace processing. + * + * <p> + * The following XML standards apply: + * + * <ul> + * <li><a href="http://www.w3.org/TR/xmlschema-2/#QName"> + * XML Schema Part2: Datatypes specification</a> + * </li> + * <li><a href="http://www.w3.org/TR/REC-xml-names/#ns-qualnames"> + * Namespaces in XML</a> + * </li> + * <li><a href="http://www.w3.org/XML/xml-names-19990114-errata"> + * Namespaces in XML Errata</a> + * </li> + * </ul> + * + * @since 1.5 + */ + +package javax.xml.namespace;
--- a/src/java.xml/share/classes/javax/xml/namespace/package.html Tue May 23 23:27:20 2017 -0700 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,54 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!-- -Copyright (c) 2003, 2005, 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. ---> - -<!DOCTYPE html - PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" - "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> - -<html xmlns="http://www.w3.org/1999/xhtml"> - -<head> - <title>javax.xml.namespace</title> - - <meta name="CVS" - content="$Id: package.html,v 1.2 2005/06/10 03:50:28 jeffsuttor Exp $" /> - <meta name="AUTHOR" - content="Jeff.Suttor@Sun.com" /> -</head> - -<body> - -<p>XML Namespace processing.</p> - -<p>The following XML standards apply:</p> -<ul> - <li><a href="http://www.w3.org/TR/xmlschema-2/#QName">XML Schema Part2: Datatypes specification</a></li> - <li><a href="http://www.w3.org/TR/REC-xml-names/#ns-qualnames">Namespaces in XML</a></li> - <li><a href="http://www.w3.org/XML/xml-names-19990114-errata">Namespaces in XML Errata</a></li> -</ul> - -</body> -</html>
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/src/java.xml/share/classes/javax/xml/package-info.java Wed May 24 14:10:04 2017 -0700 @@ -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;
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/src/java.xml/share/classes/javax/xml/parsers/package-info.java Wed May 24 14:10:04 2017 -0700 @@ -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. + */ + +/** + * <p> + * 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;
--- a/src/java.xml/share/classes/javax/xml/parsers/package.html Tue May 23 23:27:20 2017 -0700 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,51 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!-- -Copyright (c) 2000, 2005, 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. ---> - -<!DOCTYPE html - PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" - "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> - -<html xmlns="http://www.w3.org/1999/xhtml"> - -<head> - <title>javax.xml.parsers</title> - - <meta name="CVS" - content="$Id: package.html,v 1.2 2005/06/10 03:50:29 jeffsuttor Exp $" /> - <meta name="AUTHOR" - content="Jeff.Suttor@Sun.com" /> -</head> -<body> - <p> - Provides classes allowing the processing of XML documents. Two types - of plugable parsers are supported: - </p> - <ul> - <li>SAX (Simple API for XML)</li> - <li>DOM (Document Object Model)</li> - </ul> -</body> -</html>
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/src/java.xml/share/classes/javax/xml/stream/events/package-info.java Wed May 24 14:10:04 2017 -0700 @@ -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. + */ + +/** + * Defines event interfaces for the Streaming API for XML (StAX). + * + * @since 1.6 + */ + +package javax.xml.stream.events;
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/src/java.xml/share/classes/javax/xml/stream/package-info.java Wed May 24 14:10:04 2017 -0700 @@ -0,0 +1,51 @@ +/* + * 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. + */ + +/** + * <p> + * Defines interfaces and classes for the Streaming API for XML (StAX). + * + * <p> + * 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. + * + * <p> + * The cursor API defines two interfaces: {@link XMLStreamReader} + * and {@link XMLStreamWriter}, while the event iterator API defines: + * {@link XMLEventReader} and {@link XMLEventWriter}. + * + * <p> + * 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;
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/src/java.xml/share/classes/javax/xml/stream/util/package-info.java Wed May 24 14:10:04 2017 -0700 @@ -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;
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/src/java.xml/share/classes/javax/xml/transform/dom/package-info.java Wed May 24 14:10:04 2017 -0700 @@ -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. + * <p> + * 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 + * <A href="http://www.w3.org/TR/xslt#data-model">XSLT data model</A> 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. + * <p> + * 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. + * <p> + * 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;
--- a/src/java.xml/share/classes/javax/xml/transform/dom/package.html Tue May 23 23:27:20 2017 -0700 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,70 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!-- -Copyright (c) 2000, 2005, 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. ---> - -<!DOCTYPE html - PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" - "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> - -<html xmlns="http://www.w3.org/1999/xhtml"> - -<head> - <title>javax.xml.transform.dom</title> - - <meta name="CVS" - content="$Id: package.html,v 1.2 2005/06/10 03:50:40 jeffsuttor Exp $" /> - <meta name="AUTHOR" - content="Jeff.Suttor@Sun.com" /> -</head> -<body> -<p>This package implements DOM-specific transformation APIs.</p> -<p>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 -<A href="http://www.w3.org/TR/xslt#data-model">XSLT data model</A> 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.</p> -<p>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.</p> -<p>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. </p> -</body> -</html>
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/src/java.xml/share/classes/javax/xml/transform/package-info.java Wed May 24 14:10:04 2017 -0700 @@ -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. + * + * <p> + * 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}. + * + * + * <h3>Creating Objects</h3> + * + * <p> + * The API allows a concrete {@link javax.xml.transform.TransformerFactory} + * object to be created from the static function + * {@link javax.xml.transform.TransformerFactory#newInstance}. + * + * + * <h3>Specification of Inputs and Outputs</h3> + * + * <p> + * 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. + * + * <pre> + * <code> + * TransformerFactory tfactory = TransformerFactory.newInstance(); + * if (tfactory.getFeature(DOMSource.FEATURE) && + * tfactory.getFeature(StreamResult.FEATURE)) { + * ... + * } + * </code> + * </pre> + * + * + * <h3> + * <a id="qname-delimiter">Qualified Name Representation</a> + * </h3> + * + * <p> + * <a href="http://www.w3.org/TR/REC-xml-names">Namespaces</a> 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. + * + * <p> + * 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. + * + * <p> + * 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. + * + * <p> + * 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. + * + * + * <h3>Result Tree Serialization</h3> + * + * <p> + * 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. + * + * <p> + * Strings that match the <a href="http://www.w3.org/TR/xslt#output">XSLT + * specification for xsl:output attributes</a> 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 <a href="#qname-delimiter">namespace qualified</a>. Output key names + * that are namespace qualified are always allowed, although they may be + * ignored by some implementations. + * + * <p> + * 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. + * + * <h3>Exceptions and Error Reporting</h3> + * + * <p> + * 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. + * + * <p> + * 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. + * + * <p> + * {@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. + * + * <p> + * 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 + * <code>Exception</code> for a non-fatal error. The <code>ErrorListener</code> + * 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 <code>ErrorListener</code> + * on both objects will always be valid and non-<code>null</code>, 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 <code>System.err</code> and does not throw any <code>Exception</code>s. + * Applications are <em>strongly</em> encouraged to register and use + * <code>ErrorListener</code>s that insure proper behavior for warnings and + * errors. + * + * + * <h3>Resolution of URIs within a transformation</h3> + * + * <p> + * 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 + * <code>URIResolver.resolve</code> 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;
--- a/src/java.xml/share/classes/javax/xml/transform/package.html Tue May 23 23:27:20 2017 -0700 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,229 +0,0 @@ -<!doctype html> -<!-- -Copyright (c) 2000, 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. ---> - -<html> - -<head> - <title>javax.xml.transform</title> - - <meta name="CVS" - content="$Id: package.html,v 1.2 2005/06/10 03:50:39 jeffsuttor Exp $" /> - <meta name="AUTHOR" - content="Jeff.Suttor@Sun.com" /> -</head> - -<body> -<p>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. -</p> - -<p>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}. -</p> - - -<h3>Creating Objects</h3> - -<p>The API allows a concrete -{@link javax.xml.transform.TransformerFactory} object to be created from -the static function -{@link javax.xml.transform.TransformerFactory#newInstance}. -</p> - - -<h3>Specification of Inputs and Outputs</h3> - -<p>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. -</p> - -<pre> -<code> -TransformerFactory tfactory = TransformerFactory.newInstance(); -if (tfactory.getFeature(DOMSource.FEATURE) && tfactory.getFeature(StreamResult.FEATURE)) { -... -} -</code> -</pre> - - -<h3> -<a id="qname-delimiter">Qualified Name Representation</a> -</h3> - -<p><a href="http://www.w3.org/TR/REC-xml-names">Namespaces</a> -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. -</p> - -<p>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. -</p> - -<p>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. -</p> - -<p>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. -</p> - - -<h3>Result Tree Serialization</h3> - -<p>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.</p> - -<p>Strings that match the <a href="http://www.w3.org/TR/xslt#output">XSLT -specification for xsl:output attributes</a> 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 <a href="#qname-delimiter">namespace qualified</a>. Output key names -that are namespace qualified are always allowed, although they may be -ignored by some implementations.</p> - -<p>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. </p> - -<h3>Exceptions and Error Reporting</h3> - -<p>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.</p> - -<p>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.</p> - -<p>{@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.</p> - -<p>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 <code>Exception</code> for a non-fatal error. The <code>ErrorListener</code> 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 <code>ErrorListener</code> on both objects -will always be valid and non-<code>null</code>, 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 <code>System.err</code> -and does not throw any <code>Exception</code>s. -Applications are <em>strongly</em> encouraged to register and use -<code>ErrorListener</code>s that insure proper behavior for warnings and -errors. -</p> - - -<h3>Resolution of URIs within a transformation</h3> - -<p>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 -<code>URIResolver.resolve</code> 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.</p> - - -</body> -</html>
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/src/java.xml/share/classes/javax/xml/transform/sax/package-info.java Wed May 24 14:10:04 2017 -0700 @@ -0,0 +1,88 @@ +/* + * 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 SAX specific transformation classes. + * + * <p> + * 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. + * <p> + * 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. + * <p> + * 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. + * <p> + * 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}. + * + * <p> + * 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. + * + * <p> + * 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. + * <p> + * 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;
--- a/src/java.xml/share/classes/javax/xml/transform/sax/package.html Tue May 23 23:27:20 2017 -0700 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,104 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!-- -Copyright (c) 2000, 2005, 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. ---> - -<!DOCTYPE html - PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" - "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> - -<html xmlns="http://www.w3.org/1999/xhtml"> - -<head> - <title>javax.xml.transform.sax</title> - - <meta name="CVS" - content="$Id: package.html,v 1.2 2005/06/10 03:50:41 jeffsuttor Exp $" /> - <meta name="AUTHOR" - content="Jeff.Suttor@Sun.com" /> -</head> - -<body> -<p>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}.</p> -<p>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.</p> -<p>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. -<p>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.</p> -<p>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}. - -<p>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. - -<p>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. -<p>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.</p> -</body> -</html>
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/src/java.xml/share/classes/javax/xml/transform/stax/package-info.java Wed May 24 14:10:04 2017 -0700 @@ -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. + * + * <p> + * 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. + * + * <p> + * 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;
--- a/src/java.xml/share/classes/javax/xml/transform/stax/package.html Tue May 23 23:27:20 2017 -0700 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,66 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!-- -Copyright (c) 2005, 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. ---> - -<!DOCTYPE html - PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" - "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> - -<html xmlns="http://www.w3.org/1999/xhtml"> - <head> - <title>javax.xml.transform.stax</title> - - <meta name="CVS" - content="$Id: package.html,v 1.2 2005/11/03 19:34:28 jeffsuttor Exp $" /> - <meta name="AUTHOR" - content="Jeff.Suttor@Sun.com" /> - <meta name="AUTHOR" - content="Neeraj.Bajaj@Sun.com" /> - </head> - <body> - <p> - 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}. - </p> - <p> - 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. - </p> - <p> - 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. - </p> - - @since 1.6 - </body> -</html> -
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/src/java.xml/share/classes/javax/xml/transform/stream/package-info.java Wed May 24 14:10:04 2017 -0700 @@ -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. + * + * <p> + * 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. + * <p> + * 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. + * <p> + * 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;
--- a/src/java.xml/share/classes/javax/xml/transform/stream/package.html Tue May 23 23:27:20 2017 -0700 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,64 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!-- -Copyright (c) 2000, 2005, 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. ---> - -<!DOCTYPE html - PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" - "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> - -<html xmlns="http://www.w3.org/1999/xhtml"> - -<head> - <title>javax.xml.transform.stream</title> - - <meta name="CVS" - content="$Id: package.html,v 1.2 2005/06/10 03:50:42 jeffsuttor Exp $" /> - <meta name="AUTHOR" - content="Jeff.Suttor@Sun.com" /> -</head> -<body> -<p>This package implements stream- and URI- specific transformation APIs. - </p> -<p>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.</p> -<p>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.</p> -<p>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.</p> -</body> -</html>
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/src/java.xml/share/classes/javax/xml/validation/package-info.java Wed May 24 14:10:04 2017 -0700 @@ -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. + */ + +/** + * <p> + * Provides an API for validation of XML documents. <em>Validation</em> is the + * process of verifying that an XML document is an instance of a specified XML + * <em>schema</em>. An XML schema defines the content model (also called a + * <em>grammar</em> or <em>vocabulary</em>) that its instance documents will + * represent. + * + * <p> + * There are a number of popular technologies available for creating an XML schema. + * Some of the most popular ones include: + * + * <ul> + * <li><strong>Document Type Definition (DTD)</strong> + * - XML's built-in schema language. + * </li> + * <li><strong><a href="http://www.w3.org/XML/Schema">W3C XML Schema (WXS)</a></strong> - + * an object-oriented XML schema language. WXS also provides a type system + * for constraining the character data of an XML document. WXS is maintained + * by the <a href="http://www.w3.org">World Wide Web Consortium (W3C)</a> + * and is a W3C Recommendation (that is, a ratified W3C standard specification). + * </li> + * <li><strong><a href="http://www.relaxng.org">RELAX NG (RNG)</a></strong> - + * a pattern-based, user-friendly XML schema language. RNG schemas may + * also use types to constrain XML character data. RNG is maintained by + * the <a href="http://www.oasis-open.org">Organization for the Advancement + * of Structured Information Standards (OASIS)</a> and is both an OASIS + * and an <a href="http://www.iso.org">ISO (International Organization + * for Standardization)</a> standard. + * </li> + * <li><strong><a href="http://www.schematron.com/">Schematron</a></strong> - + * a rules-based XML schema language. Whereas DTD, WXS, and RNG are designed + * to express the structure of a content model, Schematron is designed to + * enforce individual rules that are difficult or impossible to express + * with other schema languages. Schematron is intended to supplement a + * schema written in structural schema language such as the aforementioned. + * Schematron is in the process of becoming an ISO standard. + * </li> + * </ul> + * <p> + * 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. + * + * <p> + * 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: + * + * <ul> + * <li><strong>Support for additional schema langauges.</strong> + * The JAXP parser implementations support only a subset of the available + * XML schema languages. The Validation API provides a standard mechanism + * through which applications may take of advantage of specialization + * validation libraries which support additional schema languages. + * </li> + * <li><strong>Easy runtime coupling of an XML instance and schema.</strong> + * Specifying the location of a schema to use for validation with JAXP + * parsers can be confusing. The Validation API makes this process simple + * (see <a href="#example-1">example</a> below). + * </li> + * </ul> + * <p> + * <a id="example-1"><strong>Usage example</strong>.</a> The following example + * demonstrates validating an XML document with the Validation API + * (for readability, some exception handling is not shown): + * + * <pre> + * + * // 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! + * } + * </pre> + * <p> + * 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. + * <strong>You should not</strong> both set a schema and call <code>setValidating(true)</code> + * 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. <strong>Turning on both of these options simultaneously will cause + * either redundant behavior or error conditions.</strong> + * + * + * @since 1.5 + */ + +package javax.xml.validation;
--- a/src/java.xml/share/classes/javax/xml/validation/package.html Tue May 23 23:27:20 2017 -0700 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,120 +0,0 @@ -<!doctype html> -<!-- -Copyright (c) 2003, 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. ---> - -<html> - -<head> - <title>javax.xml.validation</title> - - <meta name="CVS" - content="$Id: package.html,v 1.2 2005/06/10 03:50:43 jeffsuttor Exp $" /> - <meta name="AUTHOR" - content="Jeff.Suttor@Sun.com" /> -</head> - <body> - <p> - This package provides an API for validation of XML documents. <em>Validation</em> is the process of verifying - that an XML document is an instance of a specified XML <em>schema</em>. An XML schema defines the - content model (also called a <em>grammar</em> or <em>vocabulary</em>) that its instance documents - will represent. - </p> - <p> - There are a number of popular technologies available for creating an XML schema. Some of the most - popular include: - </p> - <ul> - <li><strong>Document Type Definition (DTD)</strong> - XML's built-in schema language.</li> - <li><strong><a href="http://www.w3.org/XML/Schema">W3C XML Schema (WXS)</a></strong> - an object-oriented XML schema - language. WXS also provides a type system for constraining the character data of an XML document. - WXS is maintained by the <a href="http://www.w3.org">World Wide Web Consortium (W3C)</a> and is a W3C - Recommendation (that is, a ratified W3C standard specification).</li> - <li><strong><a href="http://www.relaxng.org">RELAX NG (RNG)</a></strong> - a pattern-based, - user-friendly XML schema language. RNG schemas may also use types to constrain XML character data. - RNG is maintained by the <a href="http://www.oasis-open.org">Organization for the Advancement of - Structured Information Standards (OASIS)</a> and is both an OASIS and an - <a href="http://www.iso.org">ISO (International Organization for Standardization)</a> standard.</li> - <li><strong><a href="http://www.schematron.com/">Schematron</a></strong> - a rules-based XML schema - language. Whereas DTD, WXS, and RNG are designed to express the structure of a content model, - Schematron is designed to enforce individual rules that are difficult or impossible to express - with other schema languages. Schematron is intended to supplement a schema written in - structural schema language such as the aforementioned. Schematron is in the process - of becoming an ISO standard.</li> - </ul> - <p> - 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. - </p> - <p> - 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: - </p> - <ul> - <li><strong>Support for additional schema langauges.</strong> As of JDK 1.5, the two most - popular JAXP parser implementations, Crimson and Xerces, only support a subset of the available - XML schema languages. The Validation API provides a standard mechanism through which applications - may take of advantage of specialization validation libraries which support additional schema - languages.</li> - <li><strong>Easy runtime coupling of an XML instance and schema.</strong> Specifying the location - of a schema to use for validation with JAXP parsers can be confusing. The Validation API makes this - process simple (see <a href="#example-1">example</a> below).</li> - </ul> - <p> - <a id="example-1"><strong>Usage example</strong>.</a> The following example demonstrates validating - an XML document with the Validation API (for readability, some exception handling is not shown): - </p> - <pre> - - // 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! - } -</pre> - <p> - 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. <strong>You should not</strong> both set a schema and call <code>setValidating(true)</code> 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. <strong>Turning on both of these options simultaneously will cause either redundant behavior or error conditions.</strong> - </p> - </body> -</html>
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/src/java.xml/share/classes/javax/xml/xpath/package-info.java Wed May 24 14:10:04 2017 -0700 @@ -0,0 +1,401 @@ +/* + * 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 <em>object-model neutral</em> API for the + * evaluation of XPath expressions and access to the evaluation + * environment. + * + * <p> + * The XPath API supports <a href="http://www.w3.org/TR/xpath"> + * XML Path Language (XPath) Version 1.0</a> + * + * <hr> + * + * <ul> + * <li><a href='#XPath.Overview'>1. XPath Overview</a></li> + * <li><a href='#XPath.Expressions'>2. XPath Expressions</a></li> + * <li><a href='#XPath.Datatypes'>3. XPath Data Types</a> + * <ul> + * <li><a href='#XPath.Datatypes.QName'>3.1 QName Types</a> + * <li><a href='#XPath.Datatypes.Class'>3.2 Class Types</a> + * <li><a href='#XPath.Datatypes.Enum'>3.3 Enum Types</a> + * </ul> + * </li> + * <li><a href='#XPath.Context'>4. XPath Context</a></li> + * <li><a href='#XPath.Use'>5. Using the XPath API</a></li> + * </ul> + * <p> + * <a id="XPath.Overview"></a> + * <h3>1. XPath Overview</h3> + * + * <p> + * 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. + * + * + * <p> + * 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. + * + * + * <a id="XPath.Expressions"></a> + * <h3>2. XPath Expressions</h3> + * + * <p> + * An XPath <em>expression</em> is composed of a <em>location + * path</em> and one or more optional <em>predicates</em>. Expressions + * may also include XPath variables. + * + * + * <p> + * The following is an example of a simple XPath expression: + * + * <blockquote> + * <pre> + * /foo/bar + * </pre> + * </blockquote> + * + * <p> + * This example would select the <code><bar></code> element in + * an XML document such as the following: + * + * <blockquote> + * <pre> + * <foo> + * <bar/> + * </foo> + * </pre> + * </blockquote> + * + * <p>The expression <code>/foo/bar</code> 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 + * <em>all</em> nodes that match the expression. Thus, all three + * <code><bar></code> elements in the following document would be + * selected by the <code>/foo/bar</code> expression: + * + * <blockquote> + * <pre> + * <foo> + * <bar/> + * <bar/> + * <bar/> + * </foo> + * </pre> + * </blockquote> + * + * <p> + * A special location path operator, <code>//</code>, selects nodes at + * any depth in an XML document. The following example selects all + * <code><bar></code> elements regardless of their location in a + * document: + * + * <blockquote> + * <pre> + * //bar + * </pre> + * </blockquote> + * + * <p> + * A wildcard operator, *, causes all element nodes to be selected. + * The following example selects all children elements of a + * <code><foo></code> element: + * + * <blockquote> + * <pre> + * /foo/* + * </pre> + * </blockquote> + * + * <p> + * 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: + * + * <table class="striped"> + * <caption>Examples of Location Path</caption> + * <thead> + * <tr> + * <th>Location Path</th> + * <th>Description</th> + * </tr> + * </thead> + * <tbody> + * <tr> + * <td> + * <code>/foo/bar/<strong>@id</strong></code> + * </td> + * <td> + * Selects the attribute <code>id</code> of the <code><bar></code> element + * </td> + * </tr> + * <tr> + * <td><code>/foo/bar/<strong>text()</strong></code> + * </td> + * <td> + * Selects the text nodes of the <code><bar></code> element. No + * distinction is made between escaped and non-escaped character data. + * </td> + * </tr> + * <tr> + * <td><code>/foo/bar/<strong>comment()</strong></code> + * </td> + * <td> + * Selects all comment nodes contained in the <code><bar></code> element. + * </td> + * </tr> + * <tr> + * <td><code>/foo/bar/<strong>processing-instruction()</strong></code> + * </td> + * <td> + * Selects all processing-instruction nodes contained in the + * <code><bar></code> element. + * </td> + * </tr> + * </tbody> + * </table> + * + * <p> + * Predicates allow for refining the nodes selected by an XPath + * location path. Predicates are of the form + * <code>[<em>expression</em>]</code>. The following example selects all + * <code><foo></code> elements that contain an <code>include</code> + * attribute with the value of <code>true</code>: + * + * <blockquote> + * <pre> + * //foo[@include='true'] + * </pre> + * </blockquote> + * + * <p> + * Predicates may be appended to each other to further refine an + * expression, such as: + * + * <blockquote> + * <pre> + * //foo[@include='true'][@mode='bar'] + * </pre> + * </blockquote> + * + * <a id="XPath.Datatypes"></a> + * <h3>3. XPath Data Types</h3> + * + * <p> + * 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: + * + * <ul> + * <li><code>Boolean</code></li> + * <li><code>Number</code></li> + * <li><code>String</code></li> + * </ul> + * + * <a id="XPath.Datatypes.QName"></a> + * <h3>3.1 QName types</h3> + * The XPath API defines the following {@link javax.xml.namespace.QName} types to + * represent return types of an XPath evaluation: + * <ul> + * <li>{@link javax.xml.xpath.XPathConstants#NODESET}</li> + * <li>{@link javax.xml.xpath.XPathConstants#NODE}</li> + * <li>{@link javax.xml.xpath.XPathConstants#STRING}</li> + * <li>{@link javax.xml.xpath.XPathConstants#BOOLEAN}</li> + * <li>{@link javax.xml.xpath.XPathConstants#NUMBER}</li> + * </ul> + * + * <p> + * 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 + * <code>XPathExpression.evalute(...)</code> or <code>XPath.evaluate(...)</code> + * methods. + * + * <p> + * When a <code>Boolean</code> return type is requested, + * <code>Boolean.TRUE</code> is returned if one or more nodes were + * selected; otherwise, <code>Boolean.FALSE</code> is returned. + * + * <p> + * The <code>String</code> 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. + * + * <p> + * The <code>Number</code> return type attempts to coalesce the text + * of a node to a <code>double</code> data type. + * + * <a id="XPath.Datatypes.Class"></a> + * <h3>3.2 Class types</h3> + * In addition to the QName types, the XPath API supports the use of Class types + * through the <code>XPathExpression.evaluteExpression(...)</code> or + * <code>XPath.evaluateExpression(...)</code> methods. + * + * The XPath data types are mapped to Class types as follows: + * <ul> + * <li><code>Boolean</code> -- <code>Boolean.class</code></li> + * <li><code>Number</code> -- <code>Number.class</code></li> + * <li><code>String</code> -- <code>String.class</code></li> + * <li><code>Nodeset</code> -- <code>XPathNodes.class</code></li> + * <li><code>Node</code> -- <code>Node.class</code></li> + * </ul> + * + * <p> + * Of the subtypes of Number, only Double, Integer and Long are supported. + * + * <a id="XPath.Datatypes.Enum"></a> + * <h3>3.3 Enum types</h3> + * Enum types are defined in {@link javax.xml.xpath.XPathEvaluationResult.XPathResultType} + * that provide mappings between the QName and Class types above. The result of + * evaluating an expression using the <code>XPathExpression.evaluteExpression(...)</code> + * or <code>XPath.evaluateExpression(...)</code> methods will be of one of these types. + * + * <a id="XPath.Context"></a> + * <h3>4. XPath Context</h3> + * + * <p> + * XPath location paths may be relative to a particular node in the + * document, known as the <code>context</code>. A context consists of: + * <ul> + * <li>a node (the context node)</li> + * <li>a pair of non-zero positive integers (the context position and the context size)</li> + * <li>a set of variable bindings</li> + * <li>a function library</li> + * <li>the set of namespace declarations in scope for the expression</li> + * </ul> + * + * <p> + * It is an XML document tree represented as a hierarchy of nodes, a + * {@link org.w3c.dom.Node} for example, in the JDK implementation. + * + * <a id="XPath.Use"></a> + * <h3>5. Using the XPath API</h3> + * + * Consider the following XML document: + * <blockquote> + * <pre> + * <widgets> + * <widget> + * <manufacturer/> + * <dimensions/> + * </widget> + * </widgets> + * </pre> + * </blockquote> + * + * <p> + * The <code><widget></code> element can be selected with the following process: + * + * <blockquote> + * <pre> + * // 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); + * </pre> + * </blockquote> + * + * <p> + * With a reference to the <code><widget></code> element, a + * relative XPath expression can be written to select the + * <code><manufacturer></code> child element: + * + * <blockquote> + * <pre> + * XPath xpath = XPathFactory.newInstance().newXPath(); + * String expression = <b>"manufacturer";</b> + * Node manufacturerNode = (Node) xpath.evaluate(expression, <b>widgetNode</b>, XPathConstants.NODE); + * + * //or using the evaluateExpression method + * Node manufacturerNode = xpath.evaluateExpression(expression, <b>widgetNode</b>, Node.class); + * </pre> + * </blockquote> + * + * <p> + * 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: + * + * <blockquote> + * <pre> + * 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); + * </pre> + * </blockquote> + * + * <p> + * 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: + * <blockquote> + * <pre> + * XPathEvaluationResult<?> result = xpath.evaluateExpression(expression, document); + * switch (result.type()) { + * case NODESET: + * XPathNodes nodes = (XPathNodes)result.value(); + * ... + * break; + * } + * </pre> + * </blockquote> + * + * <p> + * 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: + * <blockquote> + * <pre> + * int count = xpath.evaluate("count(/widgets/widget)", document, Integer.class); + * </pre> + * </blockquote> + * + * @since 1.5 + * + */ + +package javax.xml.xpath;
--- a/src/java.xml/share/classes/javax/xml/xpath/package.html Tue May 23 23:27:20 2017 -0700 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,382 +0,0 @@ -<!doctype html> -<html> -<head> -<!-- -Copyright (c) 2003, 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. ---> -</head> -<body> - -This package provides an <em>object-model neutral</em> API for the -evaluation of XPath expressions and access to the evaluation -environment. - -<p> -The XPath API supports <a href="http://www.w3.org/TR/xpath"> - XML Path Language (XPath) Version 1.0</a> - -<hr> - -<ul> - <li><a href='#XPath.Overview'>1. XPath Overview</a></li> - <li><a href='#XPath.Expressions'>2. XPath Expressions</a></li> - <li><a href='#XPath.Datatypes'>3. XPath Data Types</a> - <ul> - <li><a href='#XPath.Datatypes.QName'>3.1 QName Types</a> - <li><a href='#XPath.Datatypes.Class'>3.2 Class Types</a> - <li><a href='#XPath.Datatypes.Enum'>3.3 Enum Types</a> - </ul> - </li> - <li><a href='#XPath.Context'>4. XPath Context</a></li> - <li><a href='#XPath.Use'>5. Using the XPath API</a></li> -</ul> -<p> -<a id="XPath.Overview"></a> -<h3>1. XPath Overview</h3> - -<p>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. -</p> - -<p>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. -</p> - -<a id="XPath.Expressions"></a> -<h3>2. XPath Expressions</h3> - -<p>An XPath <em>expression</em> is composed of a <em>location -path</em> and one or more optional <em>predicates</em>. Expressions -may also include XPath variables. -</p> - -<p>The following is an example of a simple XPath expression:</p> - -<blockquote> -<pre> -/foo/bar -</pre> -</blockquote> - -<p>This example would select the <code><bar></code> element in -an XML document such as the following:</p> - -<blockquote> -<pre> -<foo> - <bar/> -</foo> -</pre> -</blockquote> - -<p>The expression <code>/foo/bar</code> 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 -<em>all</em> nodes that match the expression. Thus, all three -<code><bar></code> elements in the following document would be -selected by the <code>/foo/bar</code> expression:</p> - -<blockquote> -<pre> -<foo> - <bar/> - <bar/> - <bar/> -</foo> -</pre> -</blockquote> - -<p>A special location path operator, <code>//</code>, selects nodes at -any depth in an XML document. The following example selects all -<code><bar></code> elements regardless of their location in a -document:</p> - -<blockquote> -<pre> -//bar -</pre> -</blockquote> - -<p>A wildcard operator, *, causes all element nodes to be selected. -The following example selects all children elements of a -<code><foo></code> element: - -<blockquote> -<pre> -/foo/* -</pre> -</blockquote> - -<p>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:</p> - -<table class="striped"> -<caption>Examples of Location Path</caption> -<thead> -<tr> -<th>Location Path</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td> -<code>/foo/bar/<strong>@id</strong></code> -</td> -<td>Selects the attribute <code>id</code> of the <code><bar></code> element -</td> -</tr> -<tr> -<td><code>/foo/bar/<strong>text()</strong></code> -</td> -<td>Selects the text nodes of the <code><bar></code> element. No -distinction is made between escaped and non-escaped character data. -</td> -</tr> -<tr> -<td><code>/foo/bar/<strong>comment()</strong></code> -</td> -<td>Selects all comment nodes contained in the <code><bar></code> element. -</td> -</tr> -<tr> -<td><code>/foo/bar/<strong>processing-instruction()</strong></code> -</td> -<td>Selects all processing-instruction nodes contained in the -<code><bar></code> element. -</td> -</tr> -</tbody> -</table> - -<p>Predicates allow for refining the nodes selected by an XPath -location path. Predicates are of the form -<code>[<em>expression</em>]</code>. The following example selects all -<code><foo></code> elements that contain an <code>include</code> -attribute with the value of <code>true</code>:</p> - -<blockquote> -<pre> -//foo[@include='true'] -</pre> -</blockquote> - -<p>Predicates may be appended to each other to further refine an -expression, such as:</p> - -<blockquote> -<pre> -//foo[@include='true'][@mode='bar'] -</pre> -</blockquote> - -<a id="XPath.Datatypes"></a> -<h3>3. XPath Data Types</h3> - -<p>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:</p> - -<ul> -<li><code>Boolean</code></li> -<li><code>Number</code></li> -<li><code>String</code></li> -</ul> - -<a id="XPath.Datatypes.QName"></a> -<h3>3.1 QName types</h3> -The XPath API defines the following {@link javax.xml.namespace.QName} types to -represent return types of an XPath evaluation: -<ul> -<li>{@link javax.xml.xpath.XPathConstants#NODESET}</li> -<li>{@link javax.xml.xpath.XPathConstants#NODE}</li> -<li>{@link javax.xml.xpath.XPathConstants#STRING}</li> -<li>{@link javax.xml.xpath.XPathConstants#BOOLEAN}</li> -<li>{@link javax.xml.xpath.XPathConstants#NUMBER}</li> -</ul> - -<p>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 -<code>XPathExpression.evalute(...)</code> or <code>XPath.evaluate(...)</code> -methods. - -<p>When a <code>Boolean</code> return type is requested, -<code>Boolean.TRUE</code> is returned if one or more nodes were -selected; otherwise, <code>Boolean.FALSE</code> is returned. - -<p>The <code>String</code> 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. - -<p>The <code>Number</code> return type attempts to coalesce the text -of a node to a <code>double</code> data type. - -<a id="XPath.Datatypes.Class"></a> -<h3>3.2 Class types</h3> -In addition to the QName types, the XPath API supports the use of Class types -through the <code>XPathExpression.evaluteExpression(...)</code> or -<code>XPath.evaluateExpression(...)</code> methods. - -The XPath data types are mapped to Class types as follows: -<ul> -<li><code>Boolean</code> -- <code>Boolean.class</code></li> -<li><code>Number</code> -- <code>Number.class</code></li> -<li><code>String</code> -- <code>String.class</code></li> -<li><code>Nodeset</code> -- <code>XPathNodes.class</code></li> -<li><code>Node</code> -- <code>Node.class</code></li> -</ul> - -<p> -Of the subtypes of Number, only Double, Integer and Long are supported. - -<a id="XPath.Datatypes.Enum"></a> -<h3>3.3 Enum types</h3> -Enum types are defined in {@link javax.xml.xpath.XPathEvaluationResult.XPathResultType} -that provide mappings between the QName and Class types above. The result of -evaluating an expression using the <code>XPathExpression.evaluteExpression(...)</code> -or <code>XPath.evaluateExpression(...)</code> methods will be of one of these types. - -<a id="XPath.Context"></a> -<h3>4. XPath Context</h3> - -<p>XPath location paths may be relative to a particular node in the -document, known as the <code>context</code>. A context consists of: -<ul> - <li>a node (the context node)</li> - <li>a pair of non-zero positive integers (the context position and the context size)</li> - <li>a set of variable bindings</li> - <li>a function library</li> - <li>the set of namespace declarations in scope for the expression</li> -</ul> - -<p> -It is an XML document tree represented as a hierarchy of nodes, a -{@link org.w3c.dom.Node} for example, in the JDK implementation. - -<a id="XPath.Use"></a> -<h3>5. Using the XPath API</h3> - -Consider the following XML document: -<blockquote> -<pre> -<widgets> -<widget> -<manufacturer/> -<dimensions/> -</widget> -</widgets> -</pre> -</blockquote> - -<p> -The <code><widget></code> element can be selected with the following process: - -<blockquote> -<pre> -// 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); -</pre> -</blockquote> - -<p>With a reference to the <code><widget></code> element, a -relative XPath expression can be written to select the -<code><manufacturer></code> child element:</p> - -<blockquote> -<pre> -XPath xpath = XPathFactory.newInstance().newXPath(); -<strong>String expression = "manufacturer";</strong> -Node manufacturerNode = (Node) xpath.evaluate(expression, <strong>widgetNode</strong>, XPathConstants.NODE); - -//or using the evaluateExpression method -Node manufacturerNode = xpath.evaluateExpression(expression, <strong>widgetNode</strong>, Node.class); -</pre> -</blockquote> - -<p> -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: - -<blockquote> -<pre> -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); -</pre> -</blockquote> - -<p> -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: -<blockquote> -<pre> -XPathEvaluationResult<?> result = xpath.evaluateExpression(expression, document); -switch (result.type()) { - case NODESET: - XPathNodes nodes = (XPathNodes)result.value(); - ... - break; -} -</pre> -</blockquote> - -<p> -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: -<blockquote> -<pre> -int count = xpath.evaluate("count(/widgets/widget)", document, Integer.class); -</pre> -</blockquote> - -@since 1.5 - -</body> -</html>
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/src/java.xml/share/classes/org/w3c/dom/bootstrap/package-info.java Wed May 24 14:10:04 2017 -0700 @@ -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 <code>DOMImplementation</code>. + * + * @since 1.5 + */ + +package org.w3c.dom.bootstrap;
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/src/java.xml/share/classes/org/w3c/dom/events/package-info.java Wed May 24 14:10:04 2017 -0700 @@ -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. + */ + +/** + * <p> + * Provides interfaces for DOM Level 2 Events. Refer to the + * <a href='http://www.w3.org/TR/2000/REC-DOM-Level-2-Events-20001113'> + * Document Object Model (DOM) Level 2 Events Specification + * </a>, the DOM Events module builds on + * <a href="http://www.w3.org/TR/DOM-Level-2-Core/"> + * DOM Level 2 Core Specification</a> and + * <a href='http://www.w3.org/TR/2000/REC-DOM-Level-2-Views-20001113'> + * DOM Level 2 Views Specification</a> + * that gives to programs and scripts a generic event system. + * + * + * @since 1.5 + */ + +package org.w3c.dom.events;
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/src/java.xml/share/classes/org/w3c/dom/ls/package-info.java Wed May 24 14:10:04 2017 -0700 @@ -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. + */ + +/** + * <p> + * Provides interfaces for DOM Level 3 Load and Save. Refer to the + * <a href='http://www.w3.org/TR/2004/REC-DOM-Level-3-LS-20040407'> + * Document Object Model (DOM) Level 3 Load and Save Specification</a>, + * 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;
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/src/java.xml/share/classes/org/w3c/dom/package-info.java Wed May 24 14:10:04 2017 -0700 @@ -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 + * <a href="http://www.w3.org/TR/DOM-Level-2-Core/"> + * Document Object Model (DOM) Level 2 Core Specification</a>, + * <a href="http://www.w3.org/TR/DOM-Level-3-Core"> + * Document Object Model (DOM) Level 3 Core Specification</a>, + * and <a href="http://www.w3.org/TR/DOM-Level-3-LS"> + * Document Object Model (DOM) Level 3 Load and Save Specification</a>. + * + * + * @since 1.4 + */ + +package org.w3c.dom;
--- a/src/java.xml/share/classes/org/w3c/dom/package.html Tue May 23 23:27:20 2017 -0700 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,13 +0,0 @@ -<html> -<head> -<title>org.w3c.dom package</title> -</head> -<body bgcolor="white"> -Provides the interfaces for the Document Object Model (DOM). Supports the -<a href="http://www.w3.org/TR/DOM-Level-2-Core/">Document Object Model (DOM) Level 2 Core Specification</a>, -<a href="http://www.w3.org/TR/DOM-Level-3-Core">Document Object Model (DOM) Level 3 Core Specification</a>, -and <a href="http://www.w3.org/TR/DOM-Level-3-LS">Document Object Model (DOM) Level 3 Load and Save Specification</a>. - -@since 1.4 -</body> -</html>
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/src/java.xml/share/classes/org/w3c/dom/ranges/package-info.java Wed May 24 14:10:04 2017 -0700 @@ -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. + */ +/** + * <p> + * Provides interfaces for DOM Level 2 Range. Refer to the + * <a href='http://www.w3.org/TR/2000/REC-DOM-Level-2-Traversal-Range-20001113'> + * Document Object Model (DOM) Level 2 Traversal and Range Specification</a>, + * the Range module defines specialized interfaces for identifying + * and manipulating a range in a document. + * + * + * @since 1.5 + */ + +package org.w3c.dom.ranges;
--- a/src/java.xml/share/classes/org/w3c/dom/ranges/package.html Tue May 23 23:27:20 2017 -0700 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,111 +0,0 @@ -<html> -<head> - <title>W3C IPR SOFTWARE NOTICE</title> -</head> -<body> - <p> - 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. - </p> - <p> - 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. - </p> - <h1> - W3C IPR SOFTWARE NOTICE - </h1> - <h2> - Copyright © 2000 <a href="http://www.w3.org/">World Wide Web - Consortium</a>, (<a href="http://www.lcs.mit.edu/">Massachusetts - Institute of Technology</a>, <a href="http://www.inria.fr/">Institut - National de Recherche en Informatique et en Automatique</a>, <a - href="http://www.keio.ac.jp/">Keio University</a>). All Rights - Reserved. - </h2> - <p> - 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. - </p> - <p> - <b>Note:</b> The original version of the W3C Software Copyright Notice - and License could be found at <a - href='http://www.w3.org/Consortium/Legal/copyright-software-19980720'>http://www.w3.org/Consortium/Legal/copyright-software-19980720</a> - </p> - <h2> - Copyright © 1994-2000 <a href="http://www.w3.org/">World Wide Web - Consortium</a>, (<a href="http://www.lcs.mit.edu/">Massachusetts - Institute of Technology</a>, <a href="http://www.inria.fr/">Institut - National de Recherche en Informatique et en Automatique</a>, <a - href="http://www.keio.ac.jp/">Keio University</a>). All Rights - Reserved. http://www.w3.org/Consortium/Legal/ - </h2> - <p> - 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: - </p> - <p> - 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: - </p> - <ol> - <li> - The full text of this NOTICE in a location viewable to users of the - redistributed or derivative work. - </li> - <li> - Any pre-existing intellectual property disclaimers, notices, or terms - and conditions. If none exist, a short notice of the following form - (hypertext is preferred, text is permitted) should be used within the - body of any redistributed or derivative code: "Copyright © - [$date-of-software] <a href="http://www.w3.org/">World Wide Web - Consortium</a>, (<a href="http://www.lcs.mit.edu/">Massachusetts - Institute of Technology</a>, <a href="http://www.inria.fr/">Institut - National de Recherche en Informatique et en Automatique</a>, <a - href="http://www.keio.ac.jp/">Keio University</a>). All Rights - Reserved. http://www.w3.org/Consortium/Legal/" - </li> - <li> - Notice of any changes or modifications to the W3C files, including the - date changes were made. (We recommend you provide URIs to the location - from which the code is derived.) - </li> - </ol> - <p> - 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. - </p> - <p> - COPYRIGHT HOLDERS WILL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL OR - CONSEQUENTIAL DAMAGES ARISING OUT OF ANY USE OF THE SOFTWARE OR - DOCUMENTATION. - </p> - <p> - 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. - </p> - </body> -</html>
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/src/java.xml/share/classes/org/w3c/dom/traversal/package-info.java Wed May 24 14:10:04 2017 -0700 @@ -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. + */ +/** + * <p> + * Provides interfaces for DOM Level 2 Traversal. Refer to the + * <a href='http://www.w3.org/TR/2000/REC-DOM-Level-2-Traversal-Range-20001113'> + * Document Object Model (DOM) Level 2 Traversal and Range Specification</a>, + * the Traversal module contains specialized interfaces dedicated to + * traversing the document structure. + * + * @since 1.5 + */ + +package org.w3c.dom.traversal;
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/src/java.xml/share/classes/org/w3c/dom/views/package-info.java Wed May 24 14:10:04 2017 -0700 @@ -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 + * <a href='http://www.w3.org/TR/2000/REC-DOM-Level-2-Views-20001113'> + * Document Object Model (DOM) Level 2 Views Specification</a>, + * 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;
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/src/java.xml/share/classes/org/xml/sax/ext/package-info.java Wed May 24 14:10:04 2017 -0700 @@ -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. + * + * <p> + * See <a target='_top' href='http://www.saxproject.org'>http://www.saxproject.org</a> + * for more information about SAX. + * + * <p> + * 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: + * + * <ul> + * + * <li>SAX2 drivers are <em>not</em> required to recognize these handlers. + * </li> + * + * <li>You cannot assume that the class files will be present in every SAX2 + * installation.</li> + * + * <li>This package may be updated independently of SAX2 (i.e. new + * handlers and classes may be added without updating SAX2 itself).</li> + * + * <li>The new handlers are not implemented by the SAX2 + * <code>org.xml.sax.helpers.DefaultHandler</code> or + * <code>org.xml.sax.helpers.XMLFilterImpl</code> classes. + * You can subclass these if you need such behavior, or + * use the helper classes found here.</li> + * + * <li>The handlers need to be registered differently than core SAX2 + * handlers.</li> + * + * </ul> + * + * <p>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;
--- a/src/java.xml/share/classes/org/xml/sax/ext/package.html Tue May 23 23:27:20 2017 -0700 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,46 +0,0 @@ -<HTML><HEAD> -<!-- $Id: package.html,v 1.3 2007/10/02 19:32:24 ndw Exp $ --> -</HEAD><BODY> - -<p> -This package contains interfaces to SAX2 facilities that -conformant SAX drivers won't necessarily support. - -<p>See <a target='_top' href='http://www.saxproject.org'>http://www.saxproject.org</a> -for more information about SAX.</p> - -<p> 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:</p> - -<ul> - -<li>SAX2 drivers are <em>not</em> required to recognize these handlers. -</li> - -<li>You cannot assume that the class files will be present in every SAX2 -installation.</li> - -<li>This package may be updated independently of SAX2 (i.e. new -handlers and classes may be added without updating SAX2 itself).</li> - -<li>The new handlers are not implemented by the SAX2 -<code>org.xml.sax.helpers.DefaultHandler</code> or -<code>org.xml.sax.helpers.XMLFilterImpl</code> classes. -You can subclass these if you need such behavior, or -use the helper classes found here.</li> - -<li>The handlers need to be registered differently than core SAX2 -handlers.</li> - -</ul> - -<p>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. </p> - -</BODY></HTML>
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/src/java.xml/share/classes/org/xml/sax/helpers/package-info.java Wed May 24 14:10:04 2017 -0700 @@ -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. + * + * <p> + * See <a target='_top' href='http://www.saxproject.org'>http://www.saxproject.org</a> + * for more information about SAX. + * + * @since 1.4 + */ + +package org.xml.sax.helpers;
--- a/src/java.xml/share/classes/org/xml/sax/helpers/package.html Tue May 23 23:27:20 2017 -0700 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,11 +0,0 @@ -<HTML><HEAD> -<!-- $Id: package.html,v 1.3 2007/10/02 19:32:24 ndw Exp $ --> -</HEAD><BODY> - -<p>This package contains "helper" classes, including -support for bootstrapping SAX-based applications. - -<p>See <a target='_top' href='http://www.saxproject.org'>http://www.saxproject.org</a> -for more information about SAX.</p> - -</BODY></HTML>
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/src/java.xml/share/classes/org/xml/sax/package-info.java Wed May 24 14:10:04 2017 -0700 @@ -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. + * + * <p> + * See <a target='_top' href='http://www.saxproject.org'>http://www.saxproject.org</a> + * for more information about SAX. + * + * + * <h2> SAX2 Standard Feature Flags </h2> + * + * <p> + * 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 + * <code>http://xml.org/sax/features/</code> before an identifier such as + * <code>validation</code>. Turn features on or off using + * <em>setFeature</em>. Those standard identifiers are: + * + * + * <table border="1" cellpadding="3" cellspacing="0" width="100%"> + * <tr align="center" bgcolor="#ccccff"> + * <th>Feature ID</th> + * <th>Access</th> + * <th>Default</th> + * <th>Description</th> + * </tr> + * + * <tr> + * <td>external-general-entities</td> + * <td><em>read/write</em></td> + * <td><em>unspecified</em></td> + * <td> Reports whether this parser processes external + * general entities; always true if validating. + * </td> + * </tr> + * + * <tr> + * <td>external-parameter-entities</td> + * <td><em>read/write</em></td> + * <td><em>unspecified</em></td> + * <td> Reports whether this parser processes external + * parameter entities; always true if validating. + * </td> + * </tr> + * + * <tr> + * <td>is-standalone</td> + * <td>(parsing) <em>read-only</em>, (not parsing) <em>none</em></td> + * <td>not applicable</td> + * <td> May be examined only during a parse, after the + * <em>startDocument()</em> callback has been completed; read-only. + * The value is true if the document specified standalone="yes" in + * its XML declaration, and otherwise is false. + * </td> + * </tr> + * + * <tr> + * <td>lexical-handler/parameter-entities</td> + * <td><em>read/write</em></td> + * <td><em>unspecified</em></td> + * <td> A value of "true" indicates that the LexicalHandler will report + * the beginning and end of parameter entities. + * </td> + * </tr> + * + * <tr> + * <td>namespaces</td> + * <td><em>read/write</em></td> + * <td>true</td> + * <td> A value of "true" indicates namespace URIs and unprefixed local names + * for element and attribute names will be available. + * </td> + * </tr> + * + * <tr> + * <td>namespace-prefixes</td> + * <td><em>read/write</em></td> + * <td>false</td> + * <td> A value of "true" indicates that XML qualified names (with prefixes) and + * attributes (including <em>xmlns*</em> attributes) will be available. + * </td> + * </tr> + * + * <tr> + * <td>resolve-dtd-uris</td> + * <td><em>read/write</em></td> + * <td><em>true</em></td> + * <td> 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 + * <em>Locator.getSystemId()</em>. + * This applies to system IDs passed in <ul> + * <li><em>DTDHandler.notationDecl()</em>, + * <li><em>DTDHandler.unparsedEntityDecl()</em>, and + * <li><em>DeclHandler.externalEntityDecl()</em>. + * </ul> + * It does not apply to <em>EntityResolver.resolveEntity()</em>, + * which is not used to report declarations, or to + * <em>LexicalHandler.startDTD()</em>, which already provides + * the non-absolutized URI. + * </td> + * </tr> + * + * <tr> + * <td>string-interning</td> + * <td><em>read/write</em></td> + * <td><em>unspecified</em></td> + * <td> 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 <em>java.lang.String.intern</em>. This supports fast + * testing of equality/inequality against string constants, + * rather than forcing slower calls to <em>String.equals()</em>. + * </td> + * </tr> + * + * <tr> + * <td>unicode-normalization-checking</td> + * <td><em>read/write</em></td> + * <td><em>false</em></td> + * <td> 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). + * </td> + * </tr> + * + * <tr> + * <td>use-attributes2</td> + * <td><em>read-only</em></td> + * <td>not applicable</td> + * <td> Returns "true" if the <em>Attributes</em> objects passed by + * this parser in <em>ContentHandler.startElement()</em> + * implement the <a href="ext/Attributes2.html" + * ><em>org.xml.sax.ext.Attributes2</em></a> interface. + * That interface exposes additional DTD-related information, + * such as whether the attribute was specified in the + * source text rather than defaulted. + * </td> + * </tr> + * + * <tr> + * <td>use-locator2</td> + * <td><em>read-only</em></td> + * <td>not applicable</td> + * <td> Returns "true" if the <em>Locator</em> objects passed by + * this parser in <em>ContentHandler.setDocumentLocator()</em> + * implement the <a href="ext/Locator2.html" + * ><em>org.xml.sax.ext.Locator2</em></a> interface. + * That interface exposes additional entity information, + * such as the character encoding and XML version used. + * </td> + * </tr> + * + * <tr> + * <td>use-entity-resolver2</td> + * <td><em>read/write</em></td> + * <td><em>true</em></td> + * <td> Returns "true" if, when <em>setEntityResolver</em> is given + * an object implementing the <a href="ext/EntityResolver2.html" + * ><em>org.xml.sax.ext.EntityResolver2</em></a> interface, + * those new methods will be used. + * Returns "false" to indicate that those methods will not be used. + * </td> + * </tr> + * + * <tr> + * <td>validation</td> + * <td><em>read/write</em></td> + * <td><em>unspecified</em></td> + * <td> Controls whether the parser is reporting all validity + * errors; if true, all external entities will be read. + * </td> + * </tr> + * + * <tr> + * <td>xmlns-uris</td> + * <td><em>read/write</em></td> + * <td><em>false</em></td> + * <td> Controls whether, when the <em>namespace-prefixes</em> feature + * is set, the parser treats namespace declaration attributes as + * being in the <em>http://www.w3.org/2000/xmlns/</em> 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. + * </td> + * </tr> + * + * <tr> + * <td>xml-1.1</td> + * <td><em>read-only</em></td> + * <td>not applicable</td> + * <td> Returns "true" if the parser supports both XML 1.1 and XML 1.0. + * Returns "false" if the parser supports only XML 1.0. + * </td> + * </tr> + * </table> + * + * <p> + * Support for the default values of the + * <em>namespaces</em> and <em>namespace-prefixes</em> + * properties is required. + * Support for any other feature flags is entirely optional. + * + * + * <p> + * 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. + * + * + * <h2> SAX2 Standard Handler and Property IDs </h2> + * + * <p> + * 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 + * <code>http://xml.org/sax/properties/</code> before an identifier such as + * <code>lexical-handler</code> or + * <code>dom-node</code>. Manage those properties using + * <em>setProperty()</em>. Those identifiers are: + * + * <table border="1" cellpadding="3" cellspacing="0" width="100%"> + * <tr align="center" bgcolor="#ccccff"> + * <th>Property ID</th> + * <th>Description</th> + * </tr> + * + * <tr> + * <td>declaration-handler</td> + * <td> Used to see most DTD declarations except those treated + * as lexical ("document element name is ...") or which are + * mandatory for all SAX parsers (<em>DTDHandler</em>). + * The Object must implement <a href="ext/DeclHandler.html" + * ><em>org.xml.sax.ext.DeclHandler</em></a>. + * </td> + * </tr> + * + * <tr> + * <td>document-xml-version</td> + * <td> 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". + * </td> + * </tr> + * + * <tr> + * <td>dom-node</td> + * <td> For "DOM Walker" style parsers, which ignore their + * <em>parser.parse()</em> parameters, this is used to + * specify the DOM (sub)tree being walked by the parser. + * The Object must implement the + * <em>org.w3c.dom.Node</em> interface. + * </td> + * </tr> + * + * <tr> + * <td>lexical-handler</td> + * <td> 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 <a href="ext/LexicalHandler.html" + * ><em>org.xml.sax.ext.LexicalHandler</em></a>. + * </td> + * </tr> + * + * <tr> + * <td>xml-string</td> + * <td> Readable only during a parser callback, this exposes a <b>TBS</b> + * chunk of characters responsible for the current event. + * </td> + * </tr> + * </table> + * + * <p> + * All of these standard properties are optional. + * XMLReader implementations are not required to support them. + * + * + * @since 1.4 + */ + +package org.xml.sax;
--- a/src/java.xml/share/classes/org/xml/sax/package.html Tue May 23 23:27:20 2017 -0700 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,305 +0,0 @@ -<html><head> -<!-- $Id: package.html,v 1.3 2007/10/02 19:32:24 ndw Exp $ --> -</head><body> - -<p> 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. </p> - -<p>See <a target='_top' href='http://www.saxproject.org'>http://www.saxproject.org</a> -for more information about SAX.</p> - - -<h2> SAX2 Standard Feature Flags </h2> - -<p> 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 -<code>http://xml.org/sax/features/</code> before an identifier such as -<code>validation</code>. Turn features on or off using -<em>setFeature</em>. Those standard identifiers are: </p> - - -<table class="striped"> - <caption>SAX2 Standard Features </caption> - <thead> - <tr> - <th>Feature ID</th> - <th>Access</th> - <th>Default</th> - <th>Description</th> - </tr> - </thead> - - <tbody> - <tr> - <td>external-general-entities</td> - <td><em>read/write</em></td> - <td><em>unspecified</em></td> - <td> Reports whether this parser processes external - general entities; always true if validating. - </td> - </tr> - - <tr> - <td>external-parameter-entities</td> - <td><em>read/write</em></td> - <td><em>unspecified</em></td> - <td> Reports whether this parser processes external - parameter entities; always true if validating. - </td> - </tr> - - <tr> - <td>is-standalone</td> - <td>(parsing) <em>read-only</em>, (not parsing) <em>none</em></td> - <td>not applicable</td> - <td> May be examined only during a parse, after the - <em>startDocument()</em> callback has been completed; read-only. - The value is true if the document specified standalone="yes" in - its XML declaration, and otherwise is false. - </td> - </tr> - - <tr> - <td>lexical-handler/parameter-entities</td> - <td><em>read/write</em></td> - <td><em>unspecified</em></td> - <td> A value of "true" indicates that the LexicalHandler will report - the beginning and end of parameter entities. - </td> - </tr> - - <tr> - <td>namespaces</td> - <td><em>read/write</em></td> - <td>true</td> - <td> A value of "true" indicates namespace URIs and unprefixed local names - for element and attribute names will be available. - </td> - </tr> - - <tr> - <td>namespace-prefixes</td> - <td><em>read/write</em></td> - <td>false</td> - <td> A value of "true" indicates that XML qualified names (with prefixes) and - attributes (including <em>xmlns*</em> attributes) will be available. - </td> - </tr> - - <tr> - <td>resolve-dtd-uris</td> - <td><em>read/write</em></td> - <td><em>true</em></td> - <td> 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 - <em>Locator.getSystemId()</em>. - This applies to system IDs passed in <ul> - <li><em>DTDHandler.notationDecl()</em>, - <li><em>DTDHandler.unparsedEntityDecl()</em>, and - <li><em>DeclHandler.externalEntityDecl()</em>. - </ul> - It does not apply to <em>EntityResolver.resolveEntity()</em>, - which is not used to report declarations, or to - <em>LexicalHandler.startDTD()</em>, which already provides - the non-absolutized URI. - </td> - </tr> - - <tr> - <td>string-interning</td> - <td><em>read/write</em></td> - <td><em>unspecified</em></td> - <td> 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 <em>java.lang.String.intern</em>. This supports fast - testing of equality/inequality against string constants, - rather than forcing slower calls to <em>String.equals()</em>. - </td> - </tr> - - <tr> - <td>unicode-normalization-checking</td> - <td><em>read/write</em></td> - <td><em>false</em></td> - <td> 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). - </td> - </tr> - - <tr> - <td>use-attributes2</td> - <td><em>read-only</em></td> - <td>not applicable</td> - <td> Returns "true" if the <em>Attributes</em> objects passed by - this parser in <em>ContentHandler.startElement()</em> - implement the <a href="ext/Attributes2.html" - ><em>org.xml.sax.ext.Attributes2</em></a> interface. - That interface exposes additional DTD-related information, - such as whether the attribute was specified in the - source text rather than defaulted. - </td> - </tr> - - <tr> - <td>use-locator2</td> - <td><em>read-only</em></td> - <td>not applicable</td> - <td> Returns "true" if the <em>Locator</em> objects passed by - this parser in <em>ContentHandler.setDocumentLocator()</em> - implement the <a href="ext/Locator2.html" - ><em>org.xml.sax.ext.Locator2</em></a> interface. - That interface exposes additional entity information, - such as the character encoding and XML version used. - </td> - </tr> - - <tr> - <td>use-entity-resolver2</td> - <td><em>read/write</em></td> - <td><em>true</em></td> - <td> Returns "true" if, when <em>setEntityResolver</em> is given - an object implementing the <a href="ext/EntityResolver2.html" - ><em>org.xml.sax.ext.EntityResolver2</em></a> interface, - those new methods will be used. - Returns "false" to indicate that those methods will not be used. - </td> - </tr> - - <tr> - <td>validation</td> - <td><em>read/write</em></td> - <td><em>unspecified</em></td> - <td> Controls whether the parser is reporting all validity - errors; if true, all external entities will be read. - </td> - </tr> - - <tr> - <td>xmlns-uris</td> - <td><em>read/write</em></td> - <td><em>false</em></td> - <td> Controls whether, when the <em>namespace-prefixes</em> feature - is set, the parser treats namespace declaration attributes as - being in the <em>http://www.w3.org/2000/xmlns/</em> 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. - </td> - </tr> - - <tr> - <td>xml-1.1</td> - <td><em>read-only</em></td> - <td>not applicable</td> - <td> Returns "true" if the parser supports both XML 1.1 and XML 1.0. - Returns "false" if the parser supports only XML 1.0. - </td> - </tr> - </tbody> -</table> - -<p> Support for the default values of the -<em>namespaces</em> and <em>namespace-prefixes</em> -properties is required. -Support for any other feature flags is entirely optional. -</p> - -<p> 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. -</p> - -<h2> SAX2 Standard Handler and Property IDs </h2> - -<p> 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 -<code>http://xml.org/sax/properties/</code> before an identifier such as -<code>lexical-handler</code> or -<code>dom-node</code>. Manage those properties using -<em>setProperty()</em>. Those identifiers are: </p> - -<table class="striped"> -<caption>SAX2 Standard Properties </caption> -<thead> - <tr> - <th>Property ID</th> - <th>Description</th> - </tr> -</thead> -<tbody> - - <tr> - <td>declaration-handler</td> - <td> Used to see most DTD declarations except those treated - as lexical ("document element name is ...") or which are - mandatory for all SAX parsers (<em>DTDHandler</em>). - The Object must implement <a href="ext/DeclHandler.html" - ><em>org.xml.sax.ext.DeclHandler</em></a>. - </td> - </tr> - - <tr> - <td>document-xml-version</td> - <td> 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". - </td> - </tr> - - <tr> - <td>dom-node</td> - <td> For "DOM Walker" style parsers, which ignore their - <em>parser.parse()</em> parameters, this is used to - specify the DOM (sub)tree being walked by the parser. - The Object must implement the - <em>org.w3c.dom.Node</em> interface. - </td> - </tr> - - <tr> - <td>lexical-handler</td> - <td> 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 <a href="ext/LexicalHandler.html" - ><em>org.xml.sax.ext.LexicalHandler</em></a>. - </td> - </tr> - - <tr> - <td>xml-string</td> - <td> Readable only during a parser callback, this exposes a <b>TBS</b> - chunk of characters responsible for the current event. </td> - </tr> -</tbody> -</table> - -<p> All of these standard properties are optional; -XMLReader implementations need not support them. -</p> - -</body></html>