+ This package provides an API for validation of XML documents. Validation is the process of verifying + that an XML document is an instance of a specified XML schema. An XML schema defines the + content model (also called a grammar or vocabulary) that its instance documents + will represent. +
++ There are a number of popular technologies available for creating an XML schema. Some of the most + popular include: +
+ Previous versions of JAXP supported validation as a feature of an XML parser, represented by + either a {@link javax.xml.parsers.SAXParser} or {@link javax.xml.parsers.DocumentBuilder} instance. +
++ The JAXP validation API decouples the validation of an instance document from the parsing of an + XML document. This is advantageous for several reasons, some of which are: +
+ Usage example. The following example demonstrates validating + an XML document with the Validation API (for readability, some exception handling is not shown): +
+
+ // parse an XML document into a DOM tree
+ DocumentBuilder parser = DocumentBuilderFactory.newInstance().newDocumentBuilder();
+ Document document = parser.parse(new File("instance.xml"));
+
+ // create a SchemaFactory capable of understanding WXS schemas
+ SchemaFactory factory = SchemaFactory.newInstance(XMLConstants.W3C_XML_SCHEMA_NS_URI);
+
+ // load a WXS schema, represented by a Schema instance
+ Source schemaFile = new StreamSource(new File("mySchema.xsd"));
+ Schema schema = factory.newSchema(schemaFile);
+
+ // create a Validator instance, which can be used to validate an instance document
+ Validator validator = schema.newValidator();
+
+ // validate the DOM tree
+ try {
+ validator.validate(new DOMSource(document));
+ } catch (SAXException e) {
+ // instance document is invalid!
+ }
+
+
+
+ The JAXP parsing API has been integrated with the Validation API. Applications may create a {@link javax.xml.validation.Schema} with the validation API
+ and associate it with a {@link javax.xml.parsers.DocumentBuilderFactory} or a {@link javax.xml.parsers.SAXParserFactory} instance
+ by using the {@link javax.xml.parsers.DocumentBuilderFactory#setSchema(Schema)} and {@link javax.xml.parsers.SAXParserFactory#setSchema(Schema)}
+ methods. You should not both set a schema and call setValidating(true) on a parser factory. The former technique
+ will cause parsers to use the new validation API; the latter will cause parsers to use their own internal validation
+ facilities. Turning on both of these options simultaneously will cause either redundant behavior or error conditions.
+
+ + + diff --git a/java/external/src/javax/xml/xpath/package.html b/java/external/src/javax/xml/xpath/package.html new file mode 100644 index 0000000..db3b6e8 --- /dev/null +++ b/java/external/src/javax/xml/xpath/package.html @@ -0,0 +1,259 @@ + + + + + +
+This package provides an object-model neutral API for the +evaluation of XPath expressions and access to the evaluation +environment. +
+ +The following XML standards apply:
+ + + +The XPath language provides a simple, concise syntax for selecting +nodes from an XML document. XPath also provides rules for converting a +node in an XML document object model (DOM) tree to a boolean, double, +or string value. XPath is a W3C-defined language and an official W3C +recommendation; the W3C hosts the XML Path Language (XPath) Version +1.0 specification. +
+ +XPath started in life in 1999 as a supplement to the XSLT and +XPointer languages, but has more recently become popular as a +stand-alone language, as a single XPath expression can be used to +replace many lines of DOM API code. +
+ +An XPath expression is composed of a location +path and one or more optional predicates. Expressions +may also include XPath variables. +
+ +The following is an example of a simple XPath expression:
+ ++/foo/bar ++ +
This example would select the <bar> element in
+an XML document such as the following:
+<foo> +<bar/> +</foo> ++ +
The expression /foo/bar is an example of a location
+path. While XPath location paths resemble Unix-style file system
+paths, an important distinction is that XPath expressions return
+all nodes that match the expression. Thus, all three
+<bar> elements in the following document would be
+selected by the /foo/bar expression:
+<foo> +<bar/> +<bar/> +<bar/> +</foo> ++ +
A special location path operator, //, selects nodes at
+any depth in an XML document. The following example selects all
+<bar> elements regardless of their location in a
+document:
+//bar ++ +
A wildcard operator, *, causes all element nodes to be selected.
+The following example selects all children elements of a
+<foo> element:
+/foo/* ++ +
In addition to element nodes, XPath location paths may also address +attribute nodes, text nodes, comment nodes, and processing instruction +nodes. The following table gives examples of location paths for each +of these node types:
+ +| Location Path | +Description | +
+/foo/bar/@id
+ |
+Selects the attribute id of the <bar> element
+ |
+
/foo/bar/text()
+ |
+Selects the text nodes of the <bar> element. No
+distinction is made between escaped and non-escaped character data.
+ |
+
/foo/bar/comment()
+ |
+Selects all comment nodes contained in the <bar> element.
+ |
+
/foo/bar/processing-instruction()
+ |
+Selects all processing-instruction nodes contained in the
+<bar> element.
+ |
+
Predicates allow for refining the nodes selected by an XPath
+location path. Predicates are of the form
+[expression]. The following example selects all
+<foo> elements that contain an include
+attribute with the value of true:
+//foo[@include='true'] ++ +
Predicates may be appended to each other to further refine an +expression, such as:
+ ++//foo[@include='true'][@mode='bar'] ++ +
+The following example demonstrates using the XPath API to select one +or more nodes from an XML document:
+ +
+XPath xpath = XPathFactory.newInstance().newXPath();
+String expression = "/widgets/widget";
+InputSource inputSource = new InputSource("widgets.xml");
+NodeSet nodes = (NodeSet) xpath.evaluate(expression, inputSource, XPathConstants.NODESET);
+
+
+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:
+ +BooleanNumberStringThe 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
+XPathExpression.evalute(...) or to one of the
+XPath.evaluate(...) convenience methods. The allowed
+QName values are specified as constants in the {@link
+javax.xml.xpath.XPathConstants} class; they are:
When a Boolean return type is requested,
+Boolean.TRUE is returned if one or more nodes were
+selected; otherwise, Boolean.FALSE is returned.
The String return type is a convenience for retrieving
+the character data from a text node, attribute node, comment node, or
+processing-instruction node. When used on an element node, the value
+of the child text nodes is returned.
+
The Number return type attempts to coalesce the text
+of a node to a double data type.
+
XPath location paths may be relative to a particular node in the
+document, known as the context. Consider the following
+XML document:
+<widgets> +<widget> +<manufacturer/> +<dimensions/> +</widget> +</widgets> ++ +
The <widget> element can be selected with the
+following XPath API code:
+// 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);
+
+
+With a reference to the <widget> element, a
+relative XPath expression can now written to select the
+<manufacturer> child element:
+XPath xpath = XPathFactory.newInstance().newXPath(); +String expression = "manufacturer"; +Node manufacturerNode = (Node) xpath.evaluate(expression, widgetNode, XPathConstants.NODE); ++ +