You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commons-cvs@xml.apache.org by mr...@apache.org on 2005/07/22 20:20:18 UTC
cvs commit: xml-commons/java/external/src/javax/xml/validation package.html
mrglavas 2005/07/22 11:20:18
Added: java/external/src/javax/xml/xpath package.html
java/external/src/javax/xml/validation package.html
Log:
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.
Revision Changes Path
1.1 xml-commons/java/external/src/javax/xml/xpath/package.html
Index: package.html
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!-- $Id: package.html,v 1.1 2005/07/22 18:20:17 mrglavas Exp $ -->
<!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: 1.1 $, $Date: 2005/07/22 18:20:17 $" />
<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>
1.1 xml-commons/java/external/src/javax/xml/validation/package.html
Index: package.html
===================================================================
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<!-- $Id: package.html,v 1.1 2005/07/22 18:20:18 mrglavas Exp $ -->
<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>