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

8180349: Review JAXP Java SE 9 API javadocs

Browse Source 
Reviewed-by: rriggs, lancea
This commit is contained in:
Joe Wang 2017-05-24 14:10:04 -07:00
parent 6354698728
commit 77d6023200
41 changed files with 2175 additions and 1840 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

71
jaxp/src/java.xml/share/classes/javax/xml/catalog/package-info.java Normal file
View File

@ -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;

44
jaxp/src/java.xml/share/classes/javax/xml/catalog/package.html
View File

@ -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>

172
jaxp/src/java.xml/share/classes/javax/xml/datatype/package-info.java Normal file
View File

@ -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&trade; 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;

170
jaxp/src/java.xml/share/classes/javax/xml/datatype/package.html
View File

@ -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&trade; 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>

49
jaxp/src/java.xml/share/classes/javax/xml/namespace/package-info.java Normal file
View File

@ -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;

54
jaxp/src/java.xml/share/classes/javax/xml/namespace/package.html
View File

@ -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>

34
jaxp/src/java.xml/share/classes/javax/xml/package-info.java Normal file
View File

@ -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;

36
jaxp/src/java.xml/share/classes/javax/xml/parsers/package-info.java Normal file
View File

@ -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;

51
jaxp/src/java.xml/share/classes/javax/xml/parsers/package.html
View File

@ -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>

32
jaxp/src/java.xml/share/classes/javax/xml/stream/events/package-info.java Normal file
View File

@ -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;

51
jaxp/src/java.xml/share/classes/javax/xml/stream/package-info.java Normal file
View File

@ -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;

32
jaxp/src/java.xml/share/classes/javax/xml/stream/util/package-info.java Normal file
View File

@ -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;

61
jaxp/src/java.xml/share/classes/javax/xml/transform/dom/package-info.java Normal file
View File

@ -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;

70
jaxp/src/java.xml/share/classes/javax/xml/transform/dom/package.html
View File

@ -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>

216
jaxp/src/java.xml/share/classes/javax/xml/transform/package-info.java Normal file
View File

@ -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) &amp;&amp;
* 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
* &lt;xyz:foo xmlns:xyz="http://xyz.foo.com/yada/baz.html"/&gt;, 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;

229
jaxp/src/java.xml/share/classes/javax/xml/transform/package.html
View File

@ -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) &amp;&amp; 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 &lt;xyz:foo xmlns:xyz="http://xyz.foo.com/yada/baz.html"/&gt;,
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>

88
jaxp/src/java.xml/share/classes/javax/xml/transform/sax/package-info.java Normal file
View File

@ -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;

104
jaxp/src/java.xml/share/classes/javax/xml/transform/sax/package.html
View File

@ -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>

45
jaxp/src/java.xml/share/classes/javax/xml/transform/stax/package-info.java Normal file
View File

@ -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;

66
jaxp/src/java.xml/share/classes/javax/xml/transform/stax/package.html
View File

@ -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>

56
jaxp/src/java.xml/share/classes/javax/xml/transform/stream/package-info.java Normal file
View File

@ -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;

64
jaxp/src/java.xml/share/classes/javax/xml/transform/stream/package.html
View File

@ -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>

133
jaxp/src/java.xml/share/classes/javax/xml/validation/package-info.java Normal file
View File

@ -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;

120
jaxp/src/java.xml/share/classes/javax/xml/validation/package.html
View File

@ -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>

401
jaxp/src/java.xml/share/classes/javax/xml/xpath/package-info.java Normal file
View File

@ -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>&lt;bar&gt;</code> element in
* an XML document such as the following:
*
* <blockquote>
* <pre>
* &lt;foo&gt;
* &lt;bar/&gt;
* &lt;/foo&gt;
* </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>&lt;bar&gt;</code> elements in the following document would be
* selected by the <code>/foo/bar</code> expression:
*
* <blockquote>
* <pre>
* &lt;foo&gt;
* &lt;bar/&gt;
* &lt;bar/&gt;
* &lt;bar/&gt;
* &lt;/foo&gt;
* </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>&lt;bar&gt;</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>&lt;foo&gt;</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>&lt;bar&gt;</code> element
* </td>
* </tr>
* <tr>
* <td><code>/foo/bar/<strong>text()</strong></code>
* </td>
* <td>
* Selects the text nodes of the <code>&lt;bar&gt;</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>&lt;bar&gt;</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>&lt;bar&gt;</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>&lt;foo&gt;</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>
* &lt;widgets&gt;
* &lt;widget&gt;
* &lt;manufacturer/&gt;
* &lt;dimensions/&gt;
* &lt;/widget&gt;
* &lt;/widgets&gt;
* </pre>
* </blockquote>
*
* <p>
* The <code>&lt;widget&gt;</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>&lt;widget&gt;</code> element, a
* relative XPath expression can be written to select the
* <code>&lt;manufacturer&gt;</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&lt;?&gt; 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;

382
jaxp/src/java.xml/share/classes/javax/xml/xpath/package.html
View File

@ -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>&lt;bar&gt;</code> element in
an XML document such as the following:</p>
<blockquote>
<pre>
&lt;foo&gt;
&lt;bar/&gt;
&lt;/foo&gt;
</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>&lt;bar&gt;</code> elements in the following document would be
selected by the <code>/foo/bar</code> expression:</p>
<blockquote>
<pre>
&lt;foo&gt;
&lt;bar/&gt;
&lt;bar/&gt;
&lt;bar/&gt;
&lt;/foo&gt;
</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>&lt;bar&gt;</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>&lt;foo&gt;</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>&lt;bar&gt;</code> element
</td>
</tr>
<tr>
<td><code>/foo/bar/<strong>text()</strong></code>
</td>
<td>Selects the text nodes of the <code>&lt;bar&gt;</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>&lt;bar&gt;</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>&lt;bar&gt;</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>&lt;foo&gt;</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>
&lt;widgets&gt;
&lt;widget&gt;
&lt;manufacturer/&gt;
&lt;dimensions/&gt;
&lt;/widget&gt;
&lt;/widgets&gt;
</pre>
</blockquote>
<p>
The <code>&lt;widget&gt;</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>&lt;widget&gt;</code> element, a
relative XPath expression can be written to select the
<code>&lt;manufacturer&gt;</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&lt;?&gt; 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>

32
jaxp/src/java.xml/share/classes/org/w3c/dom/bootstrap/package-info.java Normal file
View File

@ -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;

42
jaxp/src/java.xml/share/classes/org/w3c/dom/events/package-info.java Normal file
View File

@ -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;

39
jaxp/src/java.xml/share/classes/org/w3c/dom/ls/package-info.java Normal file
View File

@ -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;

38
jaxp/src/java.xml/share/classes/org/w3c/dom/package-info.java Normal file
View File

@ -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;

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

@ -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>

37
jaxp/src/java.xml/share/classes/org/w3c/dom/ranges/package-info.java Normal file
View File

@ -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;

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

@ -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 &copy; 2000 <a href="http://www.w3.org/">World Wide Web
Consortium</a>, (<a href="http://www.lcs.mit.edu/">Massachusetts
Institute of Technology</a>, <a href="http://www.inria.fr/">Institut
National de Recherche en Informatique et en Automatique</a>, <a
href="http://www.keio.ac.jp/">Keio University</a>). All Rights
Reserved.
</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 &copy; 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,&nbsp; 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 &copy;
[$date-of-software] <a href="http://www.w3.org/">World Wide Web
Consortium</a>, (<a href="http://www.lcs.mit.edu/">Massachusetts
Institute of Technology</a>, <a href="http://www.inria.fr/">Institut
National de Recherche en Informatique et en Automatique</a>, <a
href="http://www.keio.ac.jp/">Keio University</a>). All Rights
Reserved. http://www.w3.org/Consortium/Legal/"
</li>
<li>
Notice of any changes or modifications to the W3C files, including the
date changes were made. (We recommend you provide URIs to the location
from which the code is derived.)
</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>

36
jaxp/src/java.xml/share/classes/org/w3c/dom/traversal/package-info.java Normal file
View File

@ -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;

37
jaxp/src/java.xml/share/classes/org/w3c/dom/views/package-info.java Normal file
View File

@ -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;

72
jaxp/src/java.xml/share/classes/org/xml/sax/ext/package-info.java Normal file
View File

@ -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;

46
jaxp/src/java.xml/share/classes/org/xml/sax/ext/package.html
View File

@ -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>

38
jaxp/src/java.xml/share/classes/org/xml/sax/helpers/package-info.java Normal file
View File

@ -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;

11
jaxp/src/java.xml/share/classes/org/xml/sax/helpers/package.html
View File

@ -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>

327
jaxp/src/java.xml/share/classes/org/xml/sax/package-info.java Normal file
View File

@ -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;

305
jaxp/src/java.xml/share/classes/org/xml/sax/package.html
View File

@ -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>