12005
+ − 1 <?xml version="1.0" encoding="UTF-8"?>
+ − 2 <!--
+ − 3 Copyright (c) 2003, 2005, Oracle and/or its affiliates. All rights reserved.
+ − 4 DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ − 5
+ − 6 This code is free software; you can redistribute it and/or modify it
+ − 7 under the terms of the GNU General Public License version 2 only, as
+ − 8 published by the Free Software Foundation. Oracle designates this
+ − 9 particular file as subject to the "Classpath" exception as provided
+ − 10 by Oracle in the LICENSE file that accompanied this code.
+ − 11
+ − 12 This code is distributed in the hope that it will be useful, but WITHOUT
+ − 13 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ − 14 FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+ − 15 version 2 for more details (a copy is included in the LICENSE file that
+ − 16 accompanied this code).
+ − 17
+ − 18 You should have received a copy of the GNU General Public License version
+ − 19 2 along with this work; if not, write to the Free Software Foundation,
+ − 20 Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ − 21
+ − 22 Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ − 23 or visit www.oracle.com if you need additional information or have any
+ − 24 questions.
+ − 25 -->
+ − 26
+ − 27 <!DOCTYPE html
+ − 28 PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
+ − 29 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+ − 30
+ − 31 <html xmlns="http://www.w3.org/1999/xhtml">
+ − 32
+ − 33 <head>
+ − 34 <title>javax.xml.validation</title>
+ − 35
+ − 36 <meta name="CVS"
+ − 37 content="$Id: package.html,v 1.2 2005/06/10 03:50:43 jeffsuttor Exp $" />
+ − 38 <meta name="AUTHOR"
+ − 39 content="Jeff.Suttor@Sun.com" />
+ − 40 </head>
+ − 41 <body>
+ − 42 <p>
+ − 43 This package provides an API for validation of XML documents. <em>Validation</em> is the process of verifying
+ − 44 that an XML document is an instance of a specified XML <em>schema</em>. An XML schema defines the
+ − 45 content model (also called a <em>grammar</em> or <em>vocabulary</em>) that its instance documents
+ − 46 will represent.
+ − 47 </p>
+ − 48 <p>
+ − 49 There are a number of popular technologies available for creating an XML schema. Some of the most
+ − 50 popular include:
+ − 51 </p>
+ − 52 <ul>
+ − 53 <li><strong>Document Type Definition (DTD)</strong> - XML's built-in schema language.</li>
+ − 54 <li><strong><a href="http://www.w3.org/XML/Schema">W3C XML Schema (WXS)</a></strong> - an object-oriented XML schema
+ − 55 language. WXS also provides a type system for constraining the character data of an XML document.
+ − 56 WXS is maintained by the <a href="http://www.w3.org">World Wide Web Consortium (W3C)</a> and is a W3C
+ − 57 Recommendation (that is, a ratified W3C standard specification).</li>
+ − 58 <li><strong><a href="http://www.relaxng.org">RELAX NG (RNG)</a></strong> - a pattern-based,
+ − 59 user-friendly XML schema language. RNG schemas may also use types to constrain XML character data.
+ − 60 RNG is maintained by the <a href="http://www.oasis-open.org">Organization for the Advancement of
+ − 61 Structured Information Standards (OASIS)</a> and is both an OASIS and an
+ − 62 <a href="http://www.iso.org">ISO (International Organization for Standardization)</a> standard.</li>
+ − 63 <li><strong><a href="http://www.schematron.com/">Schematron</a></strong> - a rules-based XML schema
+ − 64 language. Whereas DTD, WXS, and RNG are designed to express the structure of a content model,
+ − 65 Schematron is designed to enforce individual rules that are difficult or impossible to express
+ − 66 with other schema languages. Schematron is intended to supplement a schema written in
+ − 67 structural schema language such as the aforementioned. Schematron is in the process
+ − 68 of becoming an ISO standard.</li>
+ − 69 </ul>
+ − 70 <p>
+ − 71 Previous versions of JAXP supported validation as a feature of an XML parser, represented by
+ − 72 either a {@link javax.xml.parsers.SAXParser} or {@link javax.xml.parsers.DocumentBuilder} instance.
+ − 73 </p>
+ − 74 <p>
+ − 75 The JAXP validation API decouples the validation of an instance document from the parsing of an
+ − 76 XML document. This is advantageous for several reasons, some of which are:
+ − 77 </p>
+ − 78 <ul>
+ − 79 <li><strong>Support for additional schema langauges.</strong> As of JDK 1.5, the two most
+ − 80 popular JAXP parser implementations, Crimson and Xerces, only support a subset of the available
+ − 81 XML schema languages. The Validation API provides a standard mechanism through which applications
+ − 82 may take of advantage of specialization validation libraries which support additional schema
+ − 83 languages.</li>
+ − 84 <li><strong>Easy runtime coupling of an XML instance and schema.</strong> Specifying the location
+ − 85 of a schema to use for validation with JAXP parsers can be confusing. The Validation API makes this
+ − 86 process simple (see <a href="#example-1">example</a> below).</li>
+ − 87 </ul>
+ − 88 <p>
+ − 89 <a name="example-1"><strong>Usage example</strong>.</a> The following example demonstrates validating
+ − 90 an XML document with the Validation API (for readability, some exception handling is not shown):
+ − 91 </p>
+ − 92 <pre>
+ − 93
+ − 94 // parse an XML document into a DOM tree
+ − 95 DocumentBuilder parser = DocumentBuilderFactory.newInstance().newDocumentBuilder();
+ − 96 Document document = parser.parse(new File("instance.xml"));
+ − 97
+ − 98 // create a SchemaFactory capable of understanding WXS schemas
+ − 99 SchemaFactory factory = SchemaFactory.newInstance(XMLConstants.W3C_XML_SCHEMA_NS_URI);
+ − 100
+ − 101 // load a WXS schema, represented by a Schema instance
+ − 102 Source schemaFile = new StreamSource(new File("mySchema.xsd"));
+ − 103 Schema schema = factory.newSchema(schemaFile);
+ − 104
+ − 105 // create a Validator instance, which can be used to validate an instance document
+ − 106 Validator validator = schema.newValidator();
+ − 107
+ − 108 // validate the DOM tree
+ − 109 try {
+ − 110 validator.validate(new DOMSource(document));
+ − 111 } catch (SAXException e) {
+ − 112 // instance document is invalid!
+ − 113 }
+ − 114 </pre>
+ − 115 <p>
+ − 116 The JAXP parsing API has been integrated with the Validation API. Applications may create a {@link javax.xml.validation.Schema} with the validation API
+ − 117 and associate it with a {@link javax.xml.parsers.DocumentBuilderFactory} or a {@link javax.xml.parsers.SAXParserFactory} instance
+ − 118 by using the {@link javax.xml.parsers.DocumentBuilderFactory#setSchema(Schema)} and {@link javax.xml.parsers.SAXParserFactory#setSchema(Schema)}
+ − 119 methods. <strong>You should not</strong> both set a schema and call <code>setValidating(true)</code> on a parser factory. The former technique
+ − 120 will cause parsers to use the new validation API; the latter will cause parsers to use their own internal validation
+ − 121 facilities. <strong>Turning on both of these options simultaneously will cause either redundant behavior or error conditions.</strong>
+ − 122 </p>
+ − 123 </body>
+ − 124 </html>