The package.html files for javax.xml.validation and javax.xml.xpath were
somehow missed in xml-commons-external-1.3.01. Adding these in from the jsr-206-src.zip under contrib/jaxp13. git-svn-id: https://svn.apache.org/repos/asf/xml/commons/trunk@226258 13f79535-47bb-0310-9956-ffa450edef68
This commit is contained in:
mrglavas
parent
b8b0610cd5
commit
96cbd4ae74
89
java/external/src/javax/xml/validation/package.html
vendored
Normal file
89
java/external/src/javax/xml/validation/package.html
vendored
Normal file
@ -0,0 +1,89 @@
|
|||||||
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
|
||||||
|
<!-- $Id$ -->
|
||||||
|
<html>
|
||||||
|
<body bgcolor="white">
|
||||||
|
<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:
|
||||||
|
<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>
|
||||||
|
<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:
|
||||||
|
<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>
|
||||||
|
<p>
|
||||||
|
<a name="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>
|
||||||
|
<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>
|
||||||
|
<p>
|
||||||
|
|
||||||
|
</body>
|
||||||
|
</html>
|
||||||
259
java/external/src/javax/xml/xpath/package.html
vendored
Normal file
259
java/external/src/javax/xml/xpath/package.html
vendored
Normal file
@ -0,0 +1,259 @@
|
|||||||
|
<?xml version="1.0" encoding="UTF-8"?>
|
||||||
|
<!-- $Id$ -->
|
||||||
|
|
||||||
|
<!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.xpath</title>
|
||||||
|
<meta name="@author" content="mailto:Ben@galbraiths.org" />
|
||||||
|
<meta name="@author" content="mailto:Norman.Walsh@Sun.com" />
|
||||||
|
<meta name="@author" content="mailto:Jeff.Suttor@Sun.com" />
|
||||||
|
<meta name="@version" content="$Revision$, $Date$" />
|
||||||
|
<meta name="@see" content="http://www.w3.org/TR/xpath" />
|
||||||
|
<meta name="@since" content="1.5" />
|
||||||
|
</head>
|
||||||
|
|
||||||
|
<body>
|
||||||
|
|
||||||
|
<p>This package provides an <em>object-model neutral</em> API for the
|
||||||
|
evaluation of XPath expressions and access to the evaluation
|
||||||
|
environment.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<p>The following XML standards apply:</p>
|
||||||
|
|
||||||
|
<ul>
|
||||||
|
<li><a href="http://www.w3.org/TR/xpath">XML Path Language (XPath) Version 1.0</a></li>
|
||||||
|
</ul>
|
||||||
|
|
||||||
|
<hr />
|
||||||
|
|
||||||
|
<h2>XPath Overview</h2>
|
||||||
|
|
||||||
|
<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>
|
||||||
|
|
||||||
|
<h3>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>
|
||||||
|
|
||||||
|
<pre>
|
||||||
|
/foo/bar
|
||||||
|
</pre>
|
||||||
|
|
||||||
|
<p>This example would select the <code><bar></code> element in
|
||||||
|
an XML document such as the following:</p>
|
||||||
|
|
||||||
|
<pre>
|
||||||
|
<foo>
|
||||||
|
<bar/>
|
||||||
|
</foo>
|
||||||
|
</pre>
|
||||||
|
|
||||||
|
<p>The expression <code>/foo/bar</code> is an example of a location
|
||||||
|
path. While XPath location paths resemble Unix-style file system
|
||||||
|
paths, an important distinction is that XPath expressions return
|
||||||
|
<em>all</em> nodes that match the expression. Thus, all three
|
||||||
|
<code><bar></code> elements in the following document would be
|
||||||
|
selected by the <code>/foo/bar</code> expression:</p>
|
||||||
|
|
||||||
|
<pre>
|
||||||
|
<foo>
|
||||||
|
<bar/>
|
||||||
|
<bar/>
|
||||||
|
<bar/>
|
||||||
|
</foo>
|
||||||
|
</pre>
|
||||||
|
|
||||||
|
<p>A special location path operator, <code>//</code>, selects nodes at
|
||||||
|
any depth in an XML document. The following example selects all
|
||||||
|
<code><bar></code> elements regardless of their location in a
|
||||||
|
document:</p>
|
||||||
|
|
||||||
|
<pre>
|
||||||
|
//bar
|
||||||
|
</pre>
|
||||||
|
|
||||||
|
<p>A wildcard operator, *, causes all element nodes to be selected.
|
||||||
|
The following example selects all children elements of a
|
||||||
|
<code><foo></code> element:</p>
|
||||||
|
|
||||||
|
<pre>
|
||||||
|
/foo/*
|
||||||
|
</pre>
|
||||||
|
|
||||||
|
<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 border="1">
|
||||||
|
<tr>
|
||||||
|
<td>Location Path</td>
|
||||||
|
<td>Description</td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td>
|
||||||
|
<code>/foo/bar/<strong>@id</strong></code>
|
||||||
|
</td>
|
||||||
|
<td>Selects the attribute <code>id</code> of the <code><bar></code> element
|
||||||
|
</td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td><code>/foo/bar/<strong>text()</strong></code>
|
||||||
|
</td>
|
||||||
|
<td>Selects the text nodes of the <code><bar></code> element. No
|
||||||
|
distinction is made between escaped and non-escaped character data.
|
||||||
|
</td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td><code>/foo/bar/<strong>comment()</strong></code>
|
||||||
|
</td>
|
||||||
|
<td>Selects all comment nodes contained in the <code><bar></code> element.
|
||||||
|
</td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td><code>/foo/bar/<strong>processing-instruction()</strong></code>
|
||||||
|
</td>
|
||||||
|
<td>Selects all processing-instruction nodes contained in the
|
||||||
|
<code><bar></code> element.
|
||||||
|
</td>
|
||||||
|
</tr>
|
||||||
|
</table>
|
||||||
|
|
||||||
|
<p>Predicates allow for refining the nodes selected by an XPath
|
||||||
|
location path. Predicates are of the form
|
||||||
|
<code>[<em>expression</em>]</code>. The following example selects all
|
||||||
|
<code><foo></code> elements that contain an <code>include</code>
|
||||||
|
attribute with the value of <code>true</code>:</p>
|
||||||
|
|
||||||
|
<pre>
|
||||||
|
//foo[@include='true']
|
||||||
|
</pre>
|
||||||
|
|
||||||
|
<p>Predicates may be appended to each other to further refine an
|
||||||
|
expression, such as:</p>
|
||||||
|
|
||||||
|
<pre>
|
||||||
|
//foo[@include='true'][@mode='bar']
|
||||||
|
</pre>
|
||||||
|
|
||||||
|
<h3>Using the XPath API</h3>
|
||||||
|
|
||||||
|
<p>
|
||||||
|
The following example demonstrates using the XPath API to select one
|
||||||
|
or more nodes from an XML document:</p>
|
||||||
|
|
||||||
|
<pre>
|
||||||
|
XPath xpath = XPathFactory.newInstance().newXPath();
|
||||||
|
String expression = "/widgets/widget";
|
||||||
|
InputSource inputSource = new InputSource("widgets.xml");
|
||||||
|
NodeSet nodes = (NodeSet) xpath.evaluate(expression, inputSource, XPathConstants.NODESET);
|
||||||
|
</pre>
|
||||||
|
|
||||||
|
<h3>XPath Expressions and 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 other data types:</p>
|
||||||
|
|
||||||
|
<ul>
|
||||||
|
<li><code>Boolean</code></li>
|
||||||
|
<li><code>Number</code></li>
|
||||||
|
<li><code>String</code></li>
|
||||||
|
</ul>
|
||||||
|
|
||||||
|
<p>The desired 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 to one of the
|
||||||
|
<code>XPath.evaluate(...)</code> convenience methods. The allowed
|
||||||
|
QName values are specified as constants in the {@link
|
||||||
|
javax.xml.xpath.XPathConstants} class; they are:</p>
|
||||||
|
|
||||||
|
<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>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>
|
||||||
|
|
||||||
|
<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>
|
||||||
|
|
||||||
|
<p>The <code>Number</code> return type attempts to coalesce the text
|
||||||
|
of a node to a <code>double</code> data type.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<h3>XPath Context</h3>
|
||||||
|
|
||||||
|
<p>XPath location paths may be relative to a particular node in the
|
||||||
|
document, known as the <code>context</code>. Consider the following
|
||||||
|
XML document:</p>
|
||||||
|
|
||||||
|
<pre>
|
||||||
|
<widgets>
|
||||||
|
<widget>
|
||||||
|
<manufacturer/>
|
||||||
|
<dimensions/>
|
||||||
|
</widget>
|
||||||
|
</widgets>
|
||||||
|
</pre>
|
||||||
|
|
||||||
|
<p>The <code><widget></code> element can be selected with the
|
||||||
|
following XPath API code:</p>
|
||||||
|
|
||||||
|
<pre>
|
||||||
|
// parse the XML as a W3C Document
|
||||||
|
DocumentBuilder builder = DocumentBuilderFactory.newInstance().newDocumentBuilder();
|
||||||
|
Document document = builder.parse(new File("/widgets.xml"));
|
||||||
|
|
||||||
|
XPath xpath = XPathFactory.newInstance().newXPath();
|
||||||
|
String expression = "/widgets/widget";
|
||||||
|
Node widgetNode = (Node) xpath.evaluate(expression, document, XPathConstants.NODE);
|
||||||
|
</pre>
|
||||||
|
|
||||||
|
<p>With a reference to the <code><widget></code> element, a
|
||||||
|
relative XPath expression can now written to select the
|
||||||
|
<code><manufacturer></code> child element:</p>
|
||||||
|
|
||||||
|
<pre>
|
||||||
|
XPath xpath = XPathFactory.newInstance().newXPath();
|
||||||
|
<strong>String expression = "manufacturer";</strong>
|
||||||
|
Node manufacturerNode = (Node) xpath.evaluate(expression, <strong>widgetNode</strong>, XPathConstants.NODE);
|
||||||
|
</pre>
|
||||||
|
|
||||||
|
<ul>
|
||||||
|
<li>Author <a href="mailto:Ben@galbraiths.org">Ben Galbraith</a></li>
|
||||||
|
<li>Author <a href="mailto:Norman.Walsh@Sun.com">Norman Walsh</a></li>
|
||||||
|
<li>Author <a href="mailto:Jeff.Suttor@Sun.com">Jeff Suttor</a></li>
|
||||||
|
<li>See <a href="http://www.w3.org/TR/xpath">XML Path Language (XPath) Version 1.0</a></li>
|
||||||
|
<li>Since 1.5</li>
|
||||||
|
</ul>
|
||||||
|
</body>
|
||||||
|
</html>
|
||||||
Loading…
x
Reference in New Issue
Block a user