archive/jdk
1
0
Fork 0
mirror of https://github.com/openjdk/jdk.git synced 2025-09-20 11:04:34 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

8054834: Modular Source Code

Browse source 
Co-authored-by: Alan Bateman <alan.bateman@oracle.com>
Co-authored-by: Alex Buckley <alex.buckley@oracle.com>
Co-authored-by: Erik Joelsson <erik.joelsson@oracle.com>
Co-authored-by: Jonathan Gibbons <jonathan.gibbons@oracle.com>
Co-authored-by: Karen Kinnear <karen.kinnear@oracle.com>
Co-authored-by: Magnus Ihse Bursie <magnus.ihse.bursie@oracle.com>
Co-authored-by: Mandy Chung <mandy.chung@oracle.com>
Co-authored-by: Mark Reinhold <mark.reinhold@oracle.com>
Co-authored-by: Paul Sandoz <paul.sandoz@oracle.com>
Reviewed-by: alanb, chegar, ihse, mduigou
This commit is contained in:
Chris Hegarty 2014-08-17 15:51:56 +01:00
parent e35087b430
commit 786f3dbbdf
2059 changed files with 0 additions and 1770 deletions
Download patch file Download diff file Expand all files Collapse all files

104
jaxp/src/java.xml/share/classes/javax/xml/validation/Schema.java Normal file
View file

@ -0,0 +1,104 @@
/*
* 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.
*/
package javax.xml.validation;
/**
* Immutable in-memory representation of grammar.
*
* <p>
* This object represents a set of constraints that can be checked/
* enforced against an XML document.
*
* <p>
* A {@link Schema} object is thread safe and applications are
* encouraged to share it across many parsers in many threads.
*
* <p>
* A {@link Schema} object is immutable in the sense that it shouldn't
* change the set of constraints once it is created. In other words,
* if an application validates the same document twice against the same
* {@link Schema}, it must always produce the same result.
*
* <p>
* A {@link Schema} object is usually created from {@link SchemaFactory}.
*
* <p>
* Two kinds of validators can be created from a {@link Schema} object.
* One is {@link Validator}, which provides highly-level validation
* operations that cover typical use cases. The other is
* {@link ValidatorHandler}, which works on top of SAX for better
* modularity.
*
* <p>
* This specification does not refine
* the {@link java.lang.Object#equals(java.lang.Object)} method.
* In other words, if you parse the same schema twice, you may
* still get <code>!schemaA.equals(schemaB)</code>.
*
* @author <a href="mailto:Kohsuke.Kawaguchi@Sun.com">Kohsuke Kawaguchi</a>
* @see <a href="http://www.w3.org/TR/xmlschema-1/">XML Schema Part 1: Structures</a>
* @see <a href="http://www.w3.org/TR/xml11/">Extensible Markup Language (XML) 1.1</a>
* @see <a href="http://www.w3.org/TR/REC-xml">Extensible Markup Language (XML) 1.0 (Second Edition)</a>
* @since 1.5
*/
public abstract class Schema {
/**
* Constructor for the derived class.
*
* <p>
* The constructor does nothing.
*/
protected Schema() {
}
/**
* Creates a new {@link Validator} for this {@link Schema}.
*
* <p>A validator enforces/checks the set of constraints this object
* represents.</p>
*
* <p>Implementors should assure that the properties set on the
* {@link SchemaFactory} that created this {@link Schema} are also
* set on the {@link Validator} constructed.</p>
*
* @return
* Always return a non-null valid object.
*/
public abstract Validator newValidator();
/**
* Creates a new {@link ValidatorHandler} for this {@link Schema}.
*
* <p>Implementors should assure that the properties set on the
* {@link SchemaFactory} that created this {@link Schema} are also
* set on the {@link ValidatorHandler} constructed.</p>
*
* @return
* Always return a non-null valid object.
*/
public abstract ValidatorHandler newValidatorHandler();
}

800
jaxp/src/java.xml/share/classes/javax/xml/validation/SchemaFactory.java Normal file
View file

@ -0,0 +1,800 @@
/*
* Copyright (c) 2003, 2013, 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.
*/
package javax.xml.validation;
import java.io.File;
import java.net.URL;
import javax.xml.transform.Source;
import javax.xml.transform.stream.StreamSource;
import org.w3c.dom.ls.LSResourceResolver;
import org.xml.sax.ErrorHandler;
import org.xml.sax.SAXException;
import org.xml.sax.SAXNotRecognizedException;
import org.xml.sax.SAXNotSupportedException;
import org.xml.sax.SAXParseException;
/**
* Factory that creates {@link Schema} objects&#x2E; Entry-point to
* the validation API.
*
* <p>
* {@link SchemaFactory} is a schema compiler. It reads external
* representations of schemas and prepares them for validation.
*
* <p>
* The {@link SchemaFactory} class is not thread-safe. In other words,
* it is the application's responsibility to ensure that at most
* one thread is using a {@link SchemaFactory} object at any
* given moment. Implementations are encouraged to mark methods
* as <code>synchronized</code> to protect themselves from broken clients.
*
* <p>
* {@link SchemaFactory} is not re-entrant. While one of the
* <code>newSchema</code> methods is being invoked, applications
* may not attempt to recursively invoke the <code>newSchema</code> method,
* even from the same thread.
*
* <h2><a name="schemaLanguage"></a>Schema Language</h2>
* <p>
* This spec uses a namespace URI to designate a schema language.
* The following table shows the values defined by this specification.
* <p>
* To be compliant with the spec, the implementation
* is only required to support W3C XML Schema 1.0. However,
* if it chooses to support other schema languages listed here,
* it must conform to the relevant behaviors described in this spec.
*
* <p>
* Schema languages not listed here are expected to
* introduce their own URIs to represent themselves.
* The {@link SchemaFactory} class is capable of locating other
* implementations for other schema languages at run-time.
*
* <p>
* Note that because the XML DTD is strongly tied to the parsing process
* and has a significant effect on the parsing process, it is impossible
* to define the DTD validation as a process independent from parsing.
* For this reason, this specification does not define the semantics for
* the XML DTD. This doesn't prohibit implementors from implementing it
* in a way they see fit, but <em>users are warned that any DTD
* validation implemented on this interface necessarily deviate from
* the XML DTD semantics as defined in the XML 1.0</em>.
*
* <table border="1" cellpadding="2">
* <thead>
* <tr>
* <th>value</th>
* <th>language</th>
* </tr>
* </thead>
* <tbody>
* <tr>
* <td>{@link javax.xml.XMLConstants#W3C_XML_SCHEMA_NS_URI} ("<code>http://www.w3.org/2001/XMLSchema</code>")</td>
* <td><a href="http://www.w3.org/TR/xmlschema-1">W3C XML Schema 1.0</a></td>
* </tr>
* <tr>
* <td>{@link javax.xml.XMLConstants#RELAXNG_NS_URI} ("<code>http://relaxng.org/ns/structure/1.0</code>")</td>
* <td><a href="http://www.relaxng.org/">RELAX NG 1.0</a></td>
* </tr>
* </tbody>
* </table>
*
* @author <a href="mailto:Kohsuke.Kawaguchi@Sun.com">Kohsuke Kawaguchi</a>
* @author <a href="mailto:Neeraj.Bajaj@sun.com">Neeraj Bajaj</a>
*
* @since 1.5
*/
public abstract class SchemaFactory {
private static SecuritySupport ss = new SecuritySupport();
/**
* <p>Constructor for derived classes.</p>
*
* <p>The constructor does nothing.</p>
*
* <p>Derived classes must create {@link SchemaFactory} objects that have
* <code>null</code> {@link ErrorHandler} and
* <code>null</code> {@link LSResourceResolver}.</p>
*/
protected SchemaFactory() {
}
/**
* <p>Lookup an implementation of the <code>SchemaFactory</code> that supports the specified
* schema language and return it.</p>
*
* <p>To find a <code>SchemaFactory</code> object for a given schema language,
* this method looks the following places in the following order
* where "the class loader" refers to the context class loader:</p>
* <ol>
* <li>
* If the system property
* <code>"javax.xml.validation.SchemaFactory:<i>schemaLanguage</i>"</code>
* is present (where <i>schemaLanguage</i> is the parameter
* to this method), then its value is read
* as a class name. The method will try to
* create a new instance of this class by using the class loader,
* and returns it if it is successfully created.
* </li>
* <li>
* <code>$java.home/lib/jaxp.properties</code> is read and
* the value associated with the key being the system property above
* is looked for. If present, the value is processed just like above.
* </li>
* <li>
* Use the service-provider loading facilities, defined by the
* {@link java.util.ServiceLoader} class, to attempt to locate and load an
* implementation of the service using the {@linkplain
* java.util.ServiceLoader#load(java.lang.Class) default loading mechanism}:
* the service-provider loading facility will use the {@linkplain
* java.lang.Thread#getContextClassLoader() current thread's context class loader}
* to attempt to load the service. If the context class
* loader is null, the {@linkplain
* ClassLoader#getSystemClassLoader() system class loader} will be used.
* <br>
* Each potential service provider is required to implement the method
* {@link #isSchemaLanguageSupported(String schemaLanguage)}.
* <br>
* The first service provider found that supports the specified schema
* language is returned.
* <br>
* In case of {@link java.util.ServiceConfigurationError} a
* {@link SchemaFactoryConfigurationError} will be thrown.
* </li>
* <li>
* Platform default <code>SchemaFactory</code> is located
* in a implementation specific way. There must be a platform default
* <code>SchemaFactory</code> for W3C XML Schema.
* </li>
* </ol>
*
* <p>If everything fails, {@link IllegalArgumentException} will be thrown.</p>
*
* <p><strong>Tip for Trouble-shooting:</strong></p>
* <p>See {@link java.util.Properties#load(java.io.InputStream)} for
* exactly how a property file is parsed. In particular, colons ':'
* need to be escaped in a property file, so make sure schema language
* URIs are properly escaped in it. For example:</p>
* <pre>
* http\://www.w3.org/2001/XMLSchema=org.acme.foo.XSSchemaFactory
* </pre>
*
* @param schemaLanguage
* Specifies the schema language which the returned
* SchemaFactory will understand. See
* <a href="#schemaLanguage">the list of available
* schema languages</a> for the possible values.
*
* @return New instance of a <code>SchemaFactory</code>
*
* @throws IllegalArgumentException
* If no implementation of the schema language is available.
* @throws NullPointerException
* If the <code>schemaLanguage</code> parameter is null.
* @throws SchemaFactoryConfigurationError
* If a configuration error is encountered.
*
* @see #newInstance(String schemaLanguage, String factoryClassName, ClassLoader classLoader)
*/
public static SchemaFactory newInstance(String schemaLanguage) {
ClassLoader cl;
cl = ss.getContextClassLoader();
if (cl == null) {
//cl = ClassLoader.getSystemClassLoader();
//use the current class loader
cl = SchemaFactory.class.getClassLoader();
}
SchemaFactory f = new SchemaFactoryFinder(cl).newFactory(schemaLanguage);
if (f == null) {
throw new IllegalArgumentException(
"No SchemaFactory"
+ " that implements the schema language specified by: " + schemaLanguage
+ " could be loaded");
}
return f;
}
/**
* <p>Obtain a new instance of a <code>SchemaFactory</code> from class name. <code>SchemaFactory</code>
* is returned if specified factory class name supports the specified schema language.
* This function is useful when there are multiple providers in the classpath.
* It gives more control to the application as it can specify which provider
* should be loaded.</p>
*
* <h2>Tip for Trouble-shooting</h2>
* <p>Setting the <code>jaxp.debug</code> system property will cause
* this method to print a lot of debug messages
* to <code>System.err</code> about what it is doing and where it is looking at.</p>
*
* <p> If you have problems try:</p>
* <pre>
* java -Djaxp.debug=1 YourProgram ....
* </pre>
*
* @param schemaLanguage Specifies the schema language which the returned
* <code>SchemaFactory</code> will understand. See
* <a href="#schemaLanguage">the list of available
* schema languages</a> for the possible values.
*
* @param factoryClassName fully qualified factory class name that provides implementation of <code>javax.xml.validation.SchemaFactory</code>.
*
* @param classLoader <code>ClassLoader</code> used to load the factory class. If <code>null</code>
* current <code>Thread</code>'s context classLoader is used to load the factory class.
*
* @return New instance of a <code>SchemaFactory</code>
*
* @throws IllegalArgumentException
* if <code>factoryClassName</code> is <code>null</code>, or
* the factory class cannot be loaded, instantiated or doesn't
* support the schema language specified in <code>schemLanguage</code>
* parameter.
*
* @throws NullPointerException
* If the <code>schemaLanguage</code> parameter is null.
*
* @see #newInstance(String schemaLanguage)
*
* @since 1.6
*/
public static SchemaFactory newInstance(String schemaLanguage, String factoryClassName, ClassLoader classLoader){
ClassLoader cl = classLoader;
if (cl == null) {
cl = ss.getContextClassLoader();
}
SchemaFactory f = new SchemaFactoryFinder(cl).createInstance(factoryClassName);
if (f == null) {
throw new IllegalArgumentException(
"Factory " + factoryClassName
+ " could not be loaded to implement the schema language specified by: " + schemaLanguage);
}
//if this factory supports the given schemalanguage return this factory else thrown exception
if(f.isSchemaLanguageSupported(schemaLanguage)){
return f;
}else{
throw new IllegalArgumentException(
"Factory " + f.getClass().getName()
+ " does not implement the schema language specified by: " + schemaLanguage);
}
}
/**
* <p>Is specified schema supported by this <code>SchemaFactory</code>?</p>
*
* @param schemaLanguage Specifies the schema language which the returned <code>SchemaFactory</code> will understand.
* <code>schemaLanguage</code> must specify a <a href="#schemaLanguage">valid</a> schema language.
*
* @return <code>true</code> if <code>SchemaFactory</code> supports <code>schemaLanguage</code>, else <code>false</code>.
*
* @throws NullPointerException If <code>schemaLanguage</code> is <code>null</code>.
* @throws IllegalArgumentException If <code>schemaLanguage.length() == 0</code>
* or <code>schemaLanguage</code> does not specify a <a href="#schemaLanguage">valid</a> schema language.
*/
public abstract boolean isSchemaLanguageSupported(String schemaLanguage);
/**
* Look up the value of a feature flag.
*
* <p>The feature name is any fully-qualified URI. It is
* possible for a {@link SchemaFactory} to recognize a feature name but
* temporarily be unable to return its value.
*
* <p>Implementors are free (and encouraged) to invent their own features,
* using names built on their own URIs.</p>
*
* @param name The feature name, which is a non-null fully-qualified URI.
*
* @return The current value of the feature (true or false).
*
* @throws SAXNotRecognizedException If the feature
* value can't be assigned or retrieved.
* @throws SAXNotSupportedException When the
* {@link SchemaFactory} recognizes the feature name but
* cannot determine its value at this time.
* @throws NullPointerException If <code>name</code> is <code>null</code>.
*
* @see #setFeature(String, boolean)
*/
public boolean getFeature(String name)
throws SAXNotRecognizedException, SAXNotSupportedException {
if (name == null) {
throw new NullPointerException("the name parameter is null");
}
throw new SAXNotRecognizedException(name);
}
/**
* <p>Set a feature for this <code>SchemaFactory</code>,
* {@link Schema}s created by this factory, and by extension,
* {@link Validator}s and {@link ValidatorHandler}s created by
* those {@link Schema}s.
* </p>
*
* <p>Implementors and developers should pay particular attention
* to how the special {@link Schema} object returned by {@link
* #newSchema()} is processed. In some cases, for example, when the
* <code>SchemaFactory</code> and the class actually loading the
* schema come from different implementations, it may not be possible
* for <code>SchemaFactory</code> features to be inherited automatically.
* Developers should
* make sure that features, such as secure processing, are explicitly
* set in both places.</p>
*
* <p>The feature name is any fully-qualified URI. It is
* possible for a {@link SchemaFactory} to expose a feature value but
* to be unable to change the current value.</p>
*
* <p>All implementations are required to support the {@link javax.xml.XMLConstants#FEATURE_SECURE_PROCESSING} feature.
* When the feature is:</p>
* <ul>
* <li>
* <code>true</code>: the implementation will limit XML processing to conform to implementation limits.
* Examples include entity expansion limits and XML Schema constructs that would consume large amounts of resources.
* If XML processing is limited for security reasons, it will be reported via a call to the registered
* {@link ErrorHandler#fatalError(SAXParseException exception)}.
* See {@link #setErrorHandler(ErrorHandler errorHandler)}.
* </li>
* <li>
* <code>false</code>: the implementation will processing XML according to the XML specifications without
* regard to possible implementation limits.
* </li>
* </ul>
*
* @param name The feature name, which is a non-null fully-qualified URI.
* @param value The requested value of the feature (true or false).
*
* @throws SAXNotRecognizedException If the feature
* value can't be assigned or retrieved.
* @throws SAXNotSupportedException When the
* {@link SchemaFactory} recognizes the feature name but
* cannot set the requested value.
* @throws NullPointerException If <code>name</code> is <code>null</code>.
*
* @see #getFeature(String)
*/
public void setFeature(String name, boolean value)
throws SAXNotRecognizedException, SAXNotSupportedException {
if (name == null) {
throw new NullPointerException("the name parameter is null");
}
throw new SAXNotRecognizedException(name);
}
/**
* Set the value of a property.
*
* <p>The property name is any fully-qualified URI. It is
* possible for a {@link SchemaFactory} to recognize a property name but
* to be unable to change the current value.</p>
*
* <p>
* All implementations that implement JAXP 1.5 or newer are required to
* support the {@link javax.xml.XMLConstants#ACCESS_EXTERNAL_DTD} and
* {@link javax.xml.XMLConstants#ACCESS_EXTERNAL_SCHEMA} properties.
* </p>
* <ul>
* <li>
* <p>Access to external DTDs in Schema files is restricted to the protocols
* specified by the {@link javax.xml.XMLConstants#ACCESS_EXTERNAL_DTD} property.
* If access is denied during the creation of new Schema due to the restriction
* of this property, {@link org.xml.sax.SAXException} will be thrown by the
* {@link #newSchema(Source)} or {@link #newSchema(File)}
* or {@link #newSchema(URL)} or or {@link #newSchema(Source[])} method.</p>
*
* <p>Access to external DTDs in xml source files is restricted to the protocols
* specified by the {@link javax.xml.XMLConstants#ACCESS_EXTERNAL_DTD} property.
* If access is denied during validation due to the restriction
* of this property, {@link org.xml.sax.SAXException} will be thrown by the
* {@link javax.xml.validation.Validator#validate(Source)} or
* {@link javax.xml.validation.Validator#validate(Source, Result)} method.</p>
*
* <p>Access to external reference set by the schemaLocation attribute is
* restricted to the protocols specified by the
* {@link javax.xml.XMLConstants#ACCESS_EXTERNAL_SCHEMA} property.
* If access is denied during validation due to the restriction of this property,
* {@link org.xml.sax.SAXException} will be thrown by the
* {@link javax.xml.validation.Validator#validate(Source)} or
* {@link javax.xml.validation.Validator#validate(Source, Result)} method.</p>
*
* <p>Access to external reference set by the Import
* and Include element is restricted to the protocols specified by the
* {@link javax.xml.XMLConstants#ACCESS_EXTERNAL_SCHEMA} property.
* If access is denied during the creation of new Schema due to the restriction
* of this property, {@link org.xml.sax.SAXException} will be thrown by the
* {@link #newSchema(Source)} or {@link #newSchema(File)}
* or {@link #newSchema(URL)} or {@link #newSchema(Source[])} method.</p>
* </li>
* </ul>
*
* @param name The property name, which is a non-null fully-qualified URI.
* @param object The requested value for the property.
*
* @throws SAXNotRecognizedException If the property
* value can't be assigned or retrieved.
* @throws SAXNotSupportedException When the
* {@link SchemaFactory} recognizes the property name but
* cannot set the requested value.
* @throws NullPointerException If <code>name</code> is <code>null</code>.
*/
public void setProperty(String name, Object object)
throws SAXNotRecognizedException, SAXNotSupportedException {
if (name == null) {
throw new NullPointerException("the name parameter is null");
}
throw new SAXNotRecognizedException(name);
}
/**
* Look up the value of a property.
*
* <p>The property name is any fully-qualified URI. It is
* possible for a {@link SchemaFactory} to recognize a property name but
* temporarily be unable to return its value.</p>
*
* <p>{@link SchemaFactory}s are not required to recognize any specific
* property names.</p>
*
* <p>Implementors are free (and encouraged) to invent their own properties,
* using names built on their own URIs.</p>
*
* @param name The property name, which is a non-null fully-qualified URI.
*
* @return The current value of the property.
*
* @throws SAXNotRecognizedException If the property
* value can't be assigned or retrieved.
* @throws SAXNotSupportedException When the
* XMLReader recognizes the property name but
* cannot determine its value at this time.
* @throws NullPointerException If <code>name</code> is <code>null</code>.
*
* @see #setProperty(String, Object)
*/
public Object getProperty(String name)
throws SAXNotRecognizedException, SAXNotSupportedException {
if (name == null) {
throw new NullPointerException("the name parameter is null");
}
throw new SAXNotRecognizedException(name);
}
/**
* Sets the {@link ErrorHandler} to receive errors encountered
* during the <code>newSchema</code> method invocation.
*
* <p>
* Error handler can be used to customize the error handling process
* during schema parsing. When an {@link ErrorHandler} is set,
* errors found during the parsing of schemas will be first sent
* to the {@link ErrorHandler}.
*
* <p>
* The error handler can abort the parsing of a schema immediately
* by throwing {@link SAXException} from the handler. Or for example
* it can print an error to the screen and try to continue the
* processing by returning normally from the {@link ErrorHandler}
*
* <p>
* If any {@link Throwable} (or instances of its derived classes)
* is thrown from an {@link ErrorHandler},
* the caller of the <code>newSchema</code> method will be thrown
* the same {@link Throwable} object.
*
* <p>
* {@link SchemaFactory} is not allowed to
* throw {@link SAXException} without first reporting it to
* {@link ErrorHandler}.
*
* <p>
* Applications can call this method even during a {@link Schema}
* is being parsed.
*
* <p>
* When the {@link ErrorHandler} is null, the implementation will
* behave as if the following {@link ErrorHandler} is set:
* <pre>
* class DraconianErrorHandler implements {@link ErrorHandler} {
* public void fatalError( {@link org.xml.sax.SAXParseException} e ) throws {@link SAXException} {
* throw e;
* }
* public void error( {@link org.xml.sax.SAXParseException} e ) throws {@link SAXException} {
* throw e;
* }
* public void warning( {@link org.xml.sax.SAXParseException} e ) throws {@link SAXException} {
* // noop
* }
* }
* </pre>
*
* <p>
* When a new {@link SchemaFactory} object is created, initially
* this field is set to null. This field will <em>NOT</em> be
* inherited to {@link Schema}s, {@link Validator}s, or
* {@link ValidatorHandler}s that are created from this {@link SchemaFactory}.
*
* @param errorHandler A new error handler to be set.
* This parameter can be <code>null</code>.
*/
public abstract void setErrorHandler(ErrorHandler errorHandler);
/**
* Gets the current {@link ErrorHandler} set to this {@link SchemaFactory}.
*
* @return
* This method returns the object that was last set through
* the {@link #setErrorHandler(ErrorHandler)} method, or null
* if that method has never been called since this {@link SchemaFactory}
* has created.
*
* @see #setErrorHandler(ErrorHandler)
*/
public abstract ErrorHandler getErrorHandler();
/**
* Sets the {@link LSResourceResolver} to customize
* resource resolution when parsing schemas.
*
* <p>
* {@link SchemaFactory} uses a {@link LSResourceResolver}
* when it needs to locate external resources while parsing schemas,
* although exactly what constitutes "locating external resources" is
* up to each schema language. For example, for W3C XML Schema,
* this includes files <code>&lt;include></code>d or <code>&lt;import></code>ed,
* and DTD referenced from schema files, etc.
*
* <p>
* Applications can call this method even during a {@link Schema}
* is being parsed.
*
* <p>
* When the {@link LSResourceResolver} is null, the implementation will
* behave as if the following {@link LSResourceResolver} is set:
* <pre>
* class DumbDOMResourceResolver implements {@link LSResourceResolver} {
* public {@link org.w3c.dom.ls.LSInput} resolveResource(
* String publicId, String systemId, String baseURI) {
*
* return null; // always return null
* }
* }
* </pre>
*
* <p>
* If a {@link LSResourceResolver} throws a {@link RuntimeException}
* (or instances of its derived classes),
* then the {@link SchemaFactory} will abort the parsing and
* the caller of the <code>newSchema</code> method will receive
* the same {@link RuntimeException}.
*
* <p>
* When a new {@link SchemaFactory} object is created, initially
* this field is set to null. This field will <em>NOT</em> be
* inherited to {@link Schema}s, {@link Validator}s, or
* {@link ValidatorHandler}s that are created from this {@link SchemaFactory}.
*
* @param resourceResolver
* A new resource resolver to be set. This parameter can be null.
*/
public abstract void setResourceResolver(LSResourceResolver resourceResolver);
/**
* Gets the current {@link LSResourceResolver} set to this {@link SchemaFactory}.
*
* @return
* This method returns the object that was last set through
* the {@link #setResourceResolver(LSResourceResolver)} method, or null
* if that method has never been called since this {@link SchemaFactory}
* has created.
*
* @see #setErrorHandler(ErrorHandler)
*/
public abstract LSResourceResolver getResourceResolver();
/**
* <p>Parses the specified source as a schema and returns it as a schema.</p>
*
* <p>This is a convenience method for {@link #newSchema(Source[] schemas)}.</p>
*
* @param schema Source that represents a schema.
*
* @return New <code>Schema</code> from parsing <code>schema</code>.
*
* @throws SAXException If a SAX error occurs during parsing.
* @throws NullPointerException if <code>schema</code> is null.
*/
public Schema newSchema(Source schema) throws SAXException {
return newSchema(new Source[]{schema});
}
/**
* <p>Parses the specified <code>File</code> as a schema and returns it as a <code>Schema</code>.</p>
*
* <p>This is a convenience method for {@link #newSchema(Source schema)}.</p>
*
* @param schema File that represents a schema.
*
* @return New <code>Schema</code> from parsing <code>schema</code>.
*
* @throws SAXException If a SAX error occurs during parsing.
* @throws NullPointerException if <code>schema</code> is null.
*/
public Schema newSchema(File schema) throws SAXException {
return newSchema(new StreamSource(schema));
}
/**
* <p>Parses the specified <code>URL</code> as a schema and returns it as a <code>Schema</code>.</p>
*
* <p>This is a convenience method for {@link #newSchema(Source schema)}.</p>
*
* @param schema <code>URL</code> that represents a schema.
*
* @return New <code>Schema</code> from parsing <code>schema</code>.
*
* @throws SAXException If a SAX error occurs during parsing.
* @throws NullPointerException if <code>schema</code> is null.
*/
public Schema newSchema(URL schema) throws SAXException {
return newSchema(new StreamSource(schema.toExternalForm()));
}
/**
* Parses the specified source(s) as a schema and returns it as a schema.
*
* <p>
* The callee will read all the {@link Source}s and combine them into a
* single schema. The exact semantics of the combination depends on the schema
* language that this {@link SchemaFactory} object is created for.
*
* <p>
* When an {@link ErrorHandler} is set, the callee will report all the errors
* found in sources to the handler. If the handler throws an exception, it will
* abort the schema compilation and the same exception will be thrown from
* this method. Also, after an error is reported to a handler, the callee is allowed
* to abort the further processing by throwing it. If an error handler is not set,
* the callee will throw the first error it finds in the sources.
*
* <h2>W3C XML Schema 1.0</h2>
* <p>
* The resulting schema contains components from the specified sources.
* The same result would be achieved if all these sources were
* imported, using appropriate values for schemaLocation and namespace,
* into a single schema document with a different targetNamespace
* and no components of its own, if the import elements were given
* in the same order as the sources. Section 4.2.3 of the XML Schema
* recommendation describes the options processors have in this
* regard. While a processor should be consistent in its treatment of
* JAXP schema sources and XML Schema imports, the behaviour between
* JAXP-compliant parsers may vary; in particular, parsers may choose
* to ignore all but the first &lt;import> for a given namespace,
* regardless of information provided in schemaLocation.
*
* <p>
* If the parsed set of schemas includes error(s) as
* specified in the section 5.1 of the XML Schema spec, then
* the error must be reported to the {@link ErrorHandler}.
*
* <h2>RELAX NG</h2>
*
* <p>For RELAX NG, this method must throw {@link UnsupportedOperationException}
* if <code>schemas.length!=1</code>.
*
*
* @param schemas
* inputs to be parsed. {@link SchemaFactory} is required
* to recognize {@link javax.xml.transform.sax.SAXSource},
* {@link StreamSource},
* {@link javax.xml.transform.stax.StAXSource},
* and {@link javax.xml.transform.dom.DOMSource}.
* Input schemas must be XML documents or
* XML elements and must not be null. For backwards compatibility,
* the results of passing anything other than
* a document or element are implementation-dependent.
* Implementations must either recognize and process the input
* or thrown an IllegalArgumentException.
*
* @return
* Always return a non-null valid {@link Schema} object.
* Note that when an error has been reported, there is no
* guarantee that the returned {@link Schema} object is
* meaningful.
*
* @throws SAXException
* If an error is found during processing the specified inputs.
* When an {@link ErrorHandler} is set, errors are reported to
* there first. See {@link #setErrorHandler(ErrorHandler)}.
* @throws NullPointerException
* If the <code>schemas</code> parameter itself is null or
* any item in the array is null.
* @throws IllegalArgumentException
* If any item in the array is not recognized by this method.
* @throws UnsupportedOperationException
* If the schema language doesn't support this operation.
*/
public abstract Schema newSchema(Source[] schemas) throws SAXException;
/**
* Creates a special {@link Schema} object.
*
* <p>The exact semantics of the returned {@link Schema} object
* depend on the schema language for which this {@link SchemaFactory}
* is created.
*
* <p>Also, implementations are allowed to use implementation-specific
* property/feature to alter the semantics of this method.</p>
*
* <p>Implementors and developers should pay particular attention
* to how the features set on this {@link SchemaFactory} are
* processed by this special {@link Schema}.
* In some cases, for example, when the
* {@link SchemaFactory} and the class actually loading the
* schema come from different implementations, it may not be possible
* for {@link SchemaFactory} features to be inherited automatically.
* Developers should
* make sure that features, such as secure processing, are explicitly
* set in both places.</p>
*
* <h2>W3C XML Schema 1.0</h2>
* <p>
* For XML Schema, this method creates a {@link Schema} object that
* performs validation by using location hints specified in documents.
*
* <p>
* The returned {@link Schema} object assumes that if documents
* refer to the same URL in the schema location hints,
* they will always resolve to the same schema document. This
* asusmption allows implementations to reuse parsed results of
* schema documents so that multiple validations against the same
* schema will run faster.
*
* <p>
* Note that the use of schema location hints introduces a
* vulnerability to denial-of-service attacks.
*
*
* <h2>RELAX NG</h2>
* <p>
* RELAX NG does not support this operation.
*
* @return
* Always return non-null valid {@link Schema} object.
*
* @throws UnsupportedOperationException
* If this operation is not supported by the callee.
* @throws SAXException
* If this operation is supported but failed for some reason.
*/
public abstract Schema newSchema() throws SAXException;
}

80
jaxp/src/java.xml/share/classes/javax/xml/validation/SchemaFactoryConfigurationError.java Normal file
View file

@ -0,0 +1,80 @@
/*
* Copyright (c) 2013, 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.
*/
package javax.xml.validation;
/**
* Thrown when a problem with configuration with the Schema Factories
* exists. This error will typically be thrown when the class of a
* schema factory specified in the system properties cannot be found
* or instantiated.
* @since 1.8
*/
public final class SchemaFactoryConfigurationError extends Error {
static final long serialVersionUID = 3531438703147750126L;
/**
* Create a new <code>SchemaFactoryConfigurationError</code> with no
* detail message.
*/
public SchemaFactoryConfigurationError() {
}
/**
* Create a new <code>SchemaFactoryConfigurationError</code> with
* the <code>String</code> specified as an error message.
*
* @param message The error message for the exception.
*/
public SchemaFactoryConfigurationError(String message) {
super(message);
}
/**
* Create a new <code>SchemaFactoryConfigurationError</code> with the
* given <code>Throwable</code> base cause.
*
* @param cause The exception or error to be encapsulated in a
* SchemaFactoryConfigurationError.
*/
public SchemaFactoryConfigurationError(Throwable cause) {
super(cause);
}
/**
* Create a new <code>SchemaFactoryConfigurationError</code> with the
* given <code>Throwable</code> base cause and detail message.
*
* @param cause The exception or error to be encapsulated in a
* SchemaFactoryConfigurationError.
* @param message The detail message.
*/
public SchemaFactoryConfigurationError(String message, Throwable cause) {
super(message, cause);
}
}

447
jaxp/src/java.xml/share/classes/javax/xml/validation/SchemaFactoryFinder.java Normal file
View file

@ -0,0 +1,447 @@
/*
* Copyright (c) 2003, 2013, 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.
*/
package javax.xml.validation;
import java.io.File;
import java.lang.reflect.Method;
import java.lang.reflect.Modifier;
import java.net.URL;
import java.security.AccessControlContext;
import java.security.AccessController;
import java.security.PrivilegedAction;
import java.util.Properties;
import java.util.ServiceConfigurationError;
import java.util.ServiceLoader;
/**
* Implementation of {@link SchemaFactory#newInstance(String)}.
*
* @author <a href="Kohsuke.Kawaguchi@Sun.com">Kohsuke Kawaguchi</a>
* @since 1.5
*/
class SchemaFactoryFinder {
/** debug support code. */
private static boolean debug = false;
/**
*<p> Take care of restrictions imposed by java security model </p>
*/
private static final SecuritySupport ss = new SecuritySupport();
private static final String DEFAULT_PACKAGE = "com.sun.org.apache.xerces.internal";
/**
* <p>Cache properties for performance.</p>
*/
private static final Properties cacheProps = new Properties();
/**
* <p>First time requires initialization overhead.</p>
*/
private static volatile boolean firstTime = true;
static {
// Use try/catch block to support applets
try {
debug = ss.getSystemProperty("jaxp.debug") != null;
} catch (Exception unused) {
debug = false;
}
}
/**
* <p>Conditional debug printing.</p>
*
* @param msg to print
*/
private static void debugPrintln(String msg) {
if (debug) {
System.err.println("JAXP: " + msg);
}
}
/**
* <p><code>ClassLoader</code> to use to find <code>SchemaFactory</code>.</p>
*/
private final ClassLoader classLoader;
/**
* <p>Constructor that specifies <code>ClassLoader</code> to use
* to find <code>SchemaFactory</code>.</p>
*
* @param loader
* to be used to load resource, {@link SchemaFactory}, and
* {@link SchemaFactoryLoader} implementations during
* the resolution process.
* If this parameter is null, the default system class loader
* will be used.
*/
public SchemaFactoryFinder(ClassLoader loader) {
this.classLoader = loader;
if( debug ) {
debugDisplayClassLoader();
}
}
private void debugDisplayClassLoader() {
try {
if( classLoader == ss.getContextClassLoader() ) {
debugPrintln("using thread context class loader ("+classLoader+") for search");
return;
}
} catch( Throwable unused ) {
// getContextClassLoader() undefined in JDK1.1
}
if( classLoader==ClassLoader.getSystemClassLoader() ) {
debugPrintln("using system class loader ("+classLoader+") for search");
return;
}
debugPrintln("using class loader ("+classLoader+") for search");
}
/**
* <p>Creates a new {@link SchemaFactory} object for the specified
* schema language.</p>
*
* @param schemaLanguage
* See {@link SchemaFactory Schema Language} table in <code>SchemaFactory</code>
* for the list of available schema languages.
*
* @return <code>null</code> if the callee fails to create one.
*
* @throws NullPointerException
* If the <code>schemaLanguage</code> parameter is null.
* @throws SchemaFactoryConfigurationError
* If a configuration error is encountered.
*/
public SchemaFactory newFactory(String schemaLanguage) {
if(schemaLanguage==null) {
throw new NullPointerException();
}
SchemaFactory f = _newFactory(schemaLanguage);
if (f != null) {
debugPrintln("factory '" + f.getClass().getName() + "' was found for " + schemaLanguage);
} else {
debugPrintln("unable to find a factory for " + schemaLanguage);
}
return f;
}
/**
* <p>Lookup a <code>SchemaFactory</code> for the given <code>schemaLanguage</code>.</p>
*
* @param schemaLanguage Schema language to lookup <code>SchemaFactory</code> for.
*
* @return <code>SchemaFactory</code> for the given <code>schemaLanguage</code>.
*/
private SchemaFactory _newFactory(String schemaLanguage) {
SchemaFactory sf;
String propertyName = SERVICE_CLASS.getName() + ":" + schemaLanguage;
// system property look up
try {
debugPrintln("Looking up system property '"+propertyName+"'" );
String r = ss.getSystemProperty(propertyName);
if(r!=null) {
debugPrintln("The value is '"+r+"'");
sf = createInstance(r, true);
if(sf!=null) return sf;
} else
debugPrintln("The property is undefined.");
} catch( Throwable t ) {
if( debug ) {
debugPrintln("failed to look up system property '"+propertyName+"'" );
t.printStackTrace();
}
}
String javah = ss.getSystemProperty( "java.home" );
String configFile = javah + File.separator +
"lib" + File.separator + "jaxp.properties";
// try to read from $java.home/lib/jaxp.properties
try {
if(firstTime){
synchronized(cacheProps){
if(firstTime){
File f=new File( configFile );
firstTime = false;
if(ss.doesFileExist(f)){
debugPrintln("Read properties file " + f);
cacheProps.load(ss.getFileInputStream(f));
}
}
}
}
final String factoryClassName = cacheProps.getProperty(propertyName);
debugPrintln("found " + factoryClassName + " in $java.home/jaxp.properties");
if (factoryClassName != null) {
sf = createInstance(factoryClassName, true);
if(sf != null){
return sf;
}
}
} catch (Exception ex) {
if (debug) {
ex.printStackTrace();
}
}
// Try with ServiceLoader
final SchemaFactory factoryImpl = findServiceProvider(schemaLanguage);
// The following assertion should always be true.
// Uncomment it, recompile, and run with -ea in case of doubts:
// assert factoryImpl == null || factoryImpl.isSchemaLanguageSupported(schemaLanguage);
if (factoryImpl != null) {
return factoryImpl;
}
// platform default
if(schemaLanguage.equals("http://www.w3.org/2001/XMLSchema")) {
debugPrintln("attempting to use the platform default XML Schema validator");
return createInstance("com.sun.org.apache.xerces.internal.jaxp.validation.XMLSchemaFactory", true);
}
debugPrintln("all things were tried, but none was found. bailing out.");
return null;
}
/** <p>Create class using appropriate ClassLoader.</p>
*
* @param className Name of class to create.
* @return Created class or <code>null</code>.
*/
private Class<?> createClass(String className) {
Class<?> clazz;
// make sure we have access to restricted packages
boolean internal = false;
if (System.getSecurityManager() != null) {
if (className != null && className.startsWith(DEFAULT_PACKAGE)) {
internal = true;
}
}
try {
if (classLoader != null && !internal) {
clazz = Class.forName(className, false, classLoader);
} else {
clazz = Class.forName(className);
}
} catch (Throwable t) {
if(debug) {
t.printStackTrace();
}
return null;
}
return clazz;
}
/**
* <p>Creates an instance of the specified and returns it.</p>
*
* @param className
* fully qualified class name to be instantiated.
*
* @return null
* if it fails. Error messages will be printed by this method.
*/
SchemaFactory createInstance( String className ) {
return createInstance( className, false );
}
SchemaFactory createInstance( String className, boolean useServicesMechanism ) {
SchemaFactory schemaFactory = null;
debugPrintln("createInstance(" + className + ")");
// get Class from className
Class<?> clazz = createClass(className);
if (clazz == null) {
debugPrintln("failed to getClass(" + className + ")");
return null;
}
debugPrintln("loaded " + className + " from " + which(clazz));
// instantiate Class as a SchemaFactory
try {
if (!SchemaFactory.class.isAssignableFrom(clazz)) {
throw new ClassCastException(clazz.getName()
+ " cannot be cast to " + SchemaFactory.class);
}
if (!useServicesMechanism) {
schemaFactory = newInstanceNoServiceLoader(clazz);
}
if (schemaFactory == null) {
schemaFactory = (SchemaFactory) clazz.newInstance();
}
} catch (ClassCastException classCastException) {
debugPrintln("could not instantiate " + clazz.getName());
if (debug) {
classCastException.printStackTrace();
}
return null;
} catch (IllegalAccessException illegalAccessException) {
debugPrintln("could not instantiate " + clazz.getName());
if (debug) {
illegalAccessException.printStackTrace();
}
return null;
} catch (InstantiationException instantiationException) {
debugPrintln("could not instantiate " + clazz.getName());
if (debug) {
instantiationException.printStackTrace();
}
return null;
}
return schemaFactory;
}
/**
* Try to construct using newXMLSchemaFactoryNoServiceLoader
* method if available.
*/
private static SchemaFactory newInstanceNoServiceLoader(
Class<?> providerClass
) {
// Retain maximum compatibility if no security manager.
if (System.getSecurityManager() == null) {
return null;
}
try {
final Method creationMethod =
providerClass.getDeclaredMethod(
"newXMLSchemaFactoryNoServiceLoader"
);
final int modifiers = creationMethod.getModifiers();
// Do not call the method if it's not public static.
if (!Modifier.isStatic(modifiers) || !Modifier.isPublic(modifiers)) {
return null;
}
// Only calls "newXMLSchemaFactoryNoServiceLoader" if it's
// declared to return an instance of SchemaFactory.
final Class<?> returnType = creationMethod.getReturnType();
if (SERVICE_CLASS.isAssignableFrom(returnType)) {
return SERVICE_CLASS.cast(creationMethod.invoke(null, (Object[])null));
} else {
// Should not happen since
// XMLSchemaFactory.newXMLSchemaFactoryNoServiceLoader is
// declared to return XMLSchemaFactory.
throw new ClassCastException(returnType
+ " cannot be cast to " + SERVICE_CLASS);
}
} catch(ClassCastException e) {
throw new SchemaFactoryConfigurationError(e.getMessage(), e);
} catch (NoSuchMethodException exc) {
return null;
} catch (Exception exc) {
return null;
}
}
// Call isSchemaLanguageSupported with initial context.
private boolean isSchemaLanguageSupportedBy(final SchemaFactory factory,
final String schemaLanguage,
AccessControlContext acc) {
return AccessController.doPrivileged(new PrivilegedAction<Boolean>() {
public Boolean run() {
return factory.isSchemaLanguageSupported(schemaLanguage);
}
}, acc);
}
/**
* Finds a service provider subclass of SchemaFactory that supports the
* given schema language using the ServiceLoader.
*
* @param schemaLanguage The schema language for which we seek a factory.
* @return A SchemaFactory supporting the specified schema language, or null
* if none is found.
* @throws SchemaFactoryConfigurationError if a configuration error is found.
*/
private SchemaFactory findServiceProvider(final String schemaLanguage) {
assert schemaLanguage != null;
// store current context.
final AccessControlContext acc = AccessController.getContext();
try {
return AccessController.doPrivileged(new PrivilegedAction<SchemaFactory>() {
public SchemaFactory run() {
final ServiceLoader<SchemaFactory> loader =
ServiceLoader.load(SERVICE_CLASS);
for (SchemaFactory factory : loader) {
// restore initial context to call
// factory.isSchemaLanguageSupported
if (isSchemaLanguageSupportedBy(factory, schemaLanguage, acc)) {
return factory;
}
}
return null; // no factory found.
}
});
} catch (ServiceConfigurationError error) {
throw new SchemaFactoryConfigurationError(
"Provider for " + SERVICE_CLASS + " cannot be created", error);
}
}
private static final Class<SchemaFactory> SERVICE_CLASS = SchemaFactory.class;
private static String which( Class<?> clazz ) {
return which( clazz.getName(), clazz.getClassLoader() );
}
/**
* <p>Search the specified classloader for the given classname.</p>
*
* @param classname the fully qualified name of the class to search for
* @param loader the classloader to search
*
* @return the source location of the resource, or null if it wasn't found
*/
private static String which(String classname, ClassLoader loader) {
String classnameAsResource = classname.replace('.', '/') + ".class";
if( loader==null ) loader = ClassLoader.getSystemClassLoader();
//URL it = loader.getResource(classnameAsResource);
URL it = ss.getResourceAsURL(loader, classnameAsResource);
if (it != null) {
return it.toString();
} else {
return null;
}
}
}

68
jaxp/src/java.xml/share/classes/javax/xml/validation/SchemaFactoryLoader.java Normal file
View file

@ -0,0 +1,68 @@
/*
* Copyright (c) 2004, 2006, 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.
*/
package javax.xml.validation;
/**
* <p>Factory that creates {@link SchemaFactory}.</p>
*
* <p><b>DO NOT USE THIS CLASS</b></p>
*
* <p>
* This class was introduced as a part of an early proposal during the
* JSR-206 standardization process. The proposal was eventually abandoned
* but this class accidentally remained in the source tree, and made its
* way into the final version.
* </p><p>
* This class does not participate in any JAXP 1.3 or JAXP 1.4 processing.
* It must not be used by users or JAXP implementations.
* </p>
*
* @author <a href="Kohsuke.Kawaguchi@Sun.com">Kohsuke Kawaguchi</a>
* @since 1.5
*/
public abstract class SchemaFactoryLoader {
/**
* A do-nothing constructor.
*/
protected SchemaFactoryLoader() {
}
/**
* Creates a new {@link SchemaFactory} object for the specified
* schema language.
*
* @param schemaLanguage
* See <a href="SchemaFactory.html#schemaLanguage">
* the list of available schema languages</a>.
*
* @throws NullPointerException
* If the <tt>schemaLanguage</tt> parameter is null.
*
* @return <code>null</code> if the callee fails to create one.
*/
public abstract SchemaFactory newFactory(String schemaLanguage);
}

163
jaxp/src/java.xml/share/classes/javax/xml/validation/SecuritySupport.java Normal file
View file

@ -0,0 +1,163 @@
/*
* Copyright (c) 2005, 2006, 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.
*/
package javax.xml.validation;
import java.io.IOException;
import java.net.URL;
import java.security.*;
import java.net.*;
import java.io.*;
import java.util.*;
/**
* This class is duplicated for each JAXP subpackage so keep it in sync.
* It is package private and therefore is not exposed as part of the JAXP
* API.
*
* Security related methods that only work on J2SE 1.2 and newer.
*/
class SecuritySupport {
ClassLoader getContextClassLoader() {
return (ClassLoader)
AccessController.doPrivileged(new PrivilegedAction() {
public Object run() {
ClassLoader cl = null;
//try {
cl = Thread.currentThread().getContextClassLoader();
//} catch (SecurityException ex) { }
if (cl == null)
cl = ClassLoader.getSystemClassLoader();
return cl;
}
});
}
String getSystemProperty(final String propName) {
return (String)
AccessController.doPrivileged(new PrivilegedAction() {
public Object run() {
return System.getProperty(propName);
}
});
}
FileInputStream getFileInputStream(final File file)
throws FileNotFoundException
{
try {
return (FileInputStream)
AccessController.doPrivileged(new PrivilegedExceptionAction() {
public Object run() throws FileNotFoundException {
return new FileInputStream(file);
}
});
} catch (PrivilegedActionException e) {
throw (FileNotFoundException)e.getException();
}
}
InputStream getURLInputStream(final URL url)
throws IOException
{
try {
return (InputStream)
AccessController.doPrivileged(new PrivilegedExceptionAction() {
public Object run() throws IOException {
return url.openStream();
}
});
} catch (PrivilegedActionException e) {
throw (IOException)e.getException();
}
}
URL getResourceAsURL(final ClassLoader cl,
final String name)
{
return (URL)
AccessController.doPrivileged(new PrivilegedAction() {
public Object run() {
URL url;
if (cl == null) {
url = Object.class.getResource(name);
} else {
url = cl.getResource(name);
}
return url;
}
});
}
Enumeration getResources(final ClassLoader cl,
final String name) throws IOException
{
try{
return (Enumeration)
AccessController.doPrivileged(new PrivilegedExceptionAction() {
public Object run() throws IOException{
Enumeration enumeration;
if (cl == null) {
enumeration = ClassLoader.getSystemResources(name);
} else {
enumeration = cl.getResources(name);
}
return enumeration;
}
});
}catch(PrivilegedActionException e){
throw (IOException)e.getException();
}
}
InputStream getResourceAsStream(final ClassLoader cl,
final String name)
{
return (InputStream)
AccessController.doPrivileged(new PrivilegedAction() {
public Object run() {
InputStream ris;
if (cl == null) {
ris = Object.class.getResourceAsStream(name);
} else {
ris = cl.getResourceAsStream(name);
}
return ris;
}
});
}
boolean doesFileExist(final File f) {
return ((Boolean)
AccessController.doPrivileged(new PrivilegedAction() {
public Object run() {
return new Boolean(f.exists());
}
})).booleanValue();
}
}

197
jaxp/src/java.xml/share/classes/javax/xml/validation/TypeInfoProvider.java Normal file
View file

@ -0,0 +1,197 @@
/*
* 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.
*/
package javax.xml.validation;
import org.w3c.dom.TypeInfo;
/**
* This class provides access to the type information determined
* by {@link ValidatorHandler}.
*
* <p>
* Some schema languages, such as W3C XML Schema, encourages a validator
* to report the "type" it assigns to each attribute/element.
* Those applications who wish to access this type information can invoke
* methods defined on this "interface" to access such type information.
*
* <p>
* Implementation of this "interface" can be obtained through the
* {@link ValidatorHandler#getTypeInfoProvider()} method.
*
* @author <a href="mailto:Kohsuke.Kawaguchi@Sun.com">Kohsuke Kawaguchi</a>
* @see org.w3c.dom.TypeInfo
* @since 1.5
*/
public abstract class TypeInfoProvider {
/**
* Constructor for the derived class.
*
* <p>
* The constructor does nothing.
*/
protected TypeInfoProvider() {
}
/**
* <p>Returns the immutable {@link TypeInfo} object for the current
* element.</p>
*
* <p>The method may only be called by the startElement event
* or the endElement event
* of the {@link org.xml.sax.ContentHandler} that the application sets to
* the {@link ValidatorHandler}.</p>
*
* <p>When W3C XML Schema validation is being performed, in the
* case where an element has a union type, the {@link TypeInfo}
* returned by a call to <code>getElementTypeInfo()</code> from the
* startElement
* event will be the union type. The <code>TypeInfo</code>
* returned by a call
* from the endElement event will be the actual member type used
* to validate the element.</p>
*
* @throws IllegalStateException
* If this method is called from other {@link org.xml.sax.ContentHandler}
* methods.
* @return
* An immutable {@link TypeInfo} object that represents the
* type of the current element.
* Note that the caller can keep references to the obtained
* {@link TypeInfo} longer than the callback scope.
*
* Otherwise, this method returns
* null if the validator is unable to
* determine the type of the current element for some reason
* (for example, if the validator is recovering from
* an earlier error.)
*
*/
public abstract TypeInfo getElementTypeInfo();
/**
* Returns the immutable {@link TypeInfo} object for the specified
* attribute of the current element.
*
* <p>
* The method may only be called by the startElement event of
* the {@link org.xml.sax.ContentHandler} that the application sets to the
* {@link ValidatorHandler}.</p>
*
* @param index
* The index of the attribute. The same index for
* the {@link org.xml.sax.Attributes} object passed to the
* <code>startElement</code> callback.
*
* @throws IndexOutOfBoundsException
* If the index is invalid.
* @throws IllegalStateException
* If this method is called from other {@link org.xml.sax.ContentHandler}
* methods.
*
* @return
* An immutable {@link TypeInfo} object that represents the
* type of the specified attribute.
* Note that the caller can keep references to the obtained
* {@link TypeInfo} longer than the callback scope.
*
* Otherwise, this method returns
* null if the validator is unable to
* determine the type.
*/
public abstract TypeInfo getAttributeTypeInfo(int index);
/**
* Returns <code>true</code> if the specified attribute is determined
* to be ID.
*
* <p>
* Exacly how an attribute is "determined to be ID" is up to the
* schema language. In case of W3C XML Schema, this means
* that the actual type of the attribute is the built-in ID type
* or its derived type.
*
* <p>
* A {@link javax.xml.parsers.DocumentBuilder} uses this information
* to properly implement {@link org.w3c.dom.Attr#isId()}.
*
* <p>
* The method may only be called by the startElement event of
* the {@link org.xml.sax.ContentHandler} that the application sets to the
* {@link ValidatorHandler}.
*
* @param index
* The index of the attribute. The same index for
* the {@link org.xml.sax.Attributes} object passed to the
* <code>startElement</code> callback.
*
* @throws IndexOutOfBoundsException
* If the index is invalid.
* @throws IllegalStateException
* If this method is called from other {@link org.xml.sax.ContentHandler}
* methods.
*
* @return true
* if the type of the specified attribute is ID.
*/
public abstract boolean isIdAttribute(int index);
/**
* Returns <code>false</code> if the attribute was added by the validator.
*
* <p>
* This method provides information necessary for
* a {@link javax.xml.parsers.DocumentBuilder} to determine what
* the DOM tree should return from the {@link org.w3c.dom.Attr#getSpecified()} method.
*
* <p>
* The method may only be called by the startElement event of
* the {@link org.xml.sax.ContentHandler} that the application sets to the
* {@link ValidatorHandler}.
*
* <p>
* A general guideline for validators is to return true if
* the attribute was originally present in the pipeline, and
* false if it was added by the validator.
*
* @param index
* The index of the attribute. The same index for
* the {@link org.xml.sax.Attributes} object passed to the
* <code>startElement</code> callback.
*
* @throws IndexOutOfBoundsException
* If the index is invalid.
* @throws IllegalStateException
* If this method is called from other {@link org.xml.sax.ContentHandler}
* methods.
*
* @return
* <code>true</code> if the attribute was present before the validator
* processes input. <code>false</code> if the attribute was added
* by the validator.
*/
public abstract boolean isSpecified(int index);
}

524
jaxp/src/java.xml/share/classes/javax/xml/validation/Validator.java Normal file
View file

@ -0,0 +1,524 @@
/*
* Copyright (c) 2003, 2013, 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.
*/
package javax.xml.validation;
import java.io.IOException;
import javax.xml.transform.Result;
import javax.xml.transform.Source;
import org.w3c.dom.ls.LSResourceResolver;
import org.xml.sax.ErrorHandler;
import org.xml.sax.SAXException;
import org.xml.sax.SAXNotRecognizedException;
import org.xml.sax.SAXNotSupportedException;
/**
* <p>A processor that checks an XML document against {@link Schema}.</p>
*
* <p>
* A validator object is not thread-safe and not reentrant.
* In other words, it is the application's responsibility to make
* sure that one {@link Validator} object is not used from
* more than one thread at any given time, and while the <code>validate</code>
* method is invoked, applications may not recursively call
* the <code>validate</code> method.
* <p>
*
*
* @author <a href="mailto:Kohsuke.Kawaguchi@Sun.com">Kohsuke Kawaguchi</a>
* @since 1.5
*/
public abstract class Validator {
/**
* Constructor for derived classes.
*
* <p>The constructor does nothing.</p>
*
* <p>Derived classes must create {@link Validator} objects that have
* <code>null</code> {@link ErrorHandler} and
* <code>null</code> {@link LSResourceResolver}.
* </p>
*/
protected Validator() {
}
/**
* <p>Reset this <code>Validator</code> to its original configuration.</p>
*
* <p><code>Validator</code> is reset to the same state as when it was created with
* {@link Schema#newValidator()}.
* <code>reset()</code> is designed to allow the reuse of existing <code>Validator</code>s
* thus saving resources associated with the creation of new <code>Validator</code>s.</p>
*
* <p>The reset <code>Validator</code> is not guaranteed to have the same {@link LSResourceResolver} or {@link ErrorHandler}
* <code>Object</code>s, e.g. {@link Object#equals(Object obj)}. It is guaranteed to have a functionally equal
* <code>LSResourceResolver</code> and <code>ErrorHandler</code>.</p>
*/
public abstract void reset();
/**
* Validates the specified input.
*
* <p>This is just a convenience method for
* {@link #validate(Source source, Result result)}
* with <code>result</code> of <code>null</code>.</p>
*
* @param source
* XML to be validated. Must be an XML document or
* XML element and must not be null. For backwards compatibility,
* the results of attempting to validate anything other than
* a document or element are implementation-dependent.
* Implementations must either recognize and process the input
* or throw an IllegalArgumentException.
*
* @throws IllegalArgumentException
* If the <code>Source</code>
* is an XML artifact that the implementation cannot
* validate (for example, a processing instruction).
*
* @throws SAXException
* If the {@link ErrorHandler} throws a {@link SAXException} or
* if a fatal error is found and the {@link ErrorHandler} returns
* normally.
*
* @throws IOException
* If the validator is processing a
* {@link javax.xml.transform.sax.SAXSource} and the
* underlying {@link org.xml.sax.XMLReader} throws an
* {@link IOException}.
*
*
* @throws NullPointerException If <code>source</code> is
* <code>null</code>.
*
* @see #validate(Source source, Result result)
*/
public void validate(Source source)
throws SAXException, IOException {
validate(source, null);
}
/**
* <p>Validates the specified input and send the augmented validation
* result to the specified output.</p>
*
* <p>This method places the following restrictions on the types of
* the {@link Source}/{@link Result} accepted.</p>
*
* <table border=1>
* <thead>
* <tr>
* <th colspan="5"><code>Source</code> / <code>Result</code> Accepted</th>
* </tr>
* <tr>
* <th></th>
* <th>{@link javax.xml.transform.stream.StreamSource}</th>
* <th>{@link javax.xml.transform.sax.SAXSource}</th>
* <th>{@link javax.xml.transform.dom.DOMSource}</th>
* <th>{@link javax.xml.transform.stax.StAXSource}</th>
* </tr>
* </thead>
* <tbody align="center">
* <tr>
* <td><code>null</code></td>
* <td>OK</td>
* <td>OK</td>
* <td>OK</td>
* <td>OK</td>
* </tr>
* <tr>
* <th>{@link javax.xml.transform.stream.StreamResult}</th>
* <td>OK</td>
* <td><code>IllegalArgumentException</code></td>
* <td><code>IllegalArgumentException</code></td>
* <td><code>IllegalArgumentException</code></td>
* </tr>
* <tr>
* <th>{@link javax.xml.transform.sax.SAXResult}</th>
* <td><code>IllegalArgumentException</code></td>
* <td>OK</td>
* <td><code>IllegalArgumentException</code></td>
* <td><code>IllegalArgumentException</code></td>
* </tr>
* <tr>
* <th>{@link javax.xml.transform.dom.DOMResult}</th>
* <td><code>IllegalArgumentException</code></td>
* <td><code>IllegalArgumentException</code></td>
* <td>OK</td>
* <td><code>IllegalArgumentException</code></td>
* </tr>
* <tr>
* <th>{@link javax.xml.transform.stax.StAXResult}</th>
* <td><code>IllegalArgumentException</code></td>
* <td><code>IllegalArgumentException</code></td>
* <td><code>IllegalArgumentException</code></td>
* <td>OK</td>
* </tr>
* </tbody>
* </table>
*
* <p>To validate one <code>Source</code> into another kind of
* <code>Result</code>, use the identity transformer (see
* {@link javax.xml.transform.TransformerFactory#newTransformer()}).</p>
*
* <p>Errors found during the validation is sent to the specified
* {@link ErrorHandler}.</p>
*
* <p>If a document is valid, or if a document contains some errors
* but none of them were fatal and the <code>ErrorHandler</code> didn't
* throw any exception, then the method returns normally.</p>
*
* @param source
* XML to be validated. Must be an XML document or
* XML element and must not be null. For backwards compatibility,
* the results of attempting to validate anything other than
* a document or element are implementation-dependent.
* Implementations must either recognize and process the input
* or throw an IllegalArgumentException.
*
* @param result
* The <code>Result</code> object that receives (possibly augmented)
* XML. This parameter can be null if the caller is not interested
* in it.
*
* Note that when a <code>DOMResult</code> is used,
* a validator might just pass the same DOM node from
* <code>DOMSource</code> to <code>DOMResult</code>
* (in which case <code>source.getNode()==result.getNode()</code>),
* it might copy the entire DOM tree, or it might alter the
* node given by the source.
*
* @throws IllegalArgumentException
* If the <code>Result</code> type doesn't match the
* <code>Source</code> type of if the <code>Source</code>
* is an XML artifact that the implementation cannot
* validate (for example, a processing instruction).
* @throws SAXException
* If the <code>ErrorHandler</code> throws a
* <code>SAXException</code> or
* if a fatal error is found and the <code>ErrorHandler</code> returns
* normally.
* @throws IOException
* If the validator is processing a
* <code>SAXSource</code> and the
* underlying {@link org.xml.sax.XMLReader} throws an
* <code>IOException</code>.
* @throws NullPointerException
* If the <code>source</code> parameter is <code>null</code>.
*
* @see #validate(Source source)
*/
public abstract void validate(Source source, Result result)
throws SAXException, IOException;
/**
* Sets the {@link ErrorHandler} to receive errors encountered
* during the <code>validate</code> method invocation.
*
* <p>
* Error handler can be used to customize the error handling process
* during a validation. When an {@link ErrorHandler} is set,
* errors found during the validation will be first sent
* to the {@link ErrorHandler}.
*
* <p>
* The error handler can abort further validation immediately
* by throwing {@link SAXException} from the handler. Or for example
* it can print an error to the screen and try to continue the
* validation by returning normally from the {@link ErrorHandler}
*
* <p>
* If any {@link Throwable} is thrown from an {@link ErrorHandler},
* the caller of the <code>validate</code> method will be thrown
* the same {@link Throwable} object.
*
* <p>
* {@link Validator} is not allowed to
* throw {@link SAXException} without first reporting it to
* {@link ErrorHandler}.
*
* <p>
* When the {@link ErrorHandler} is null, the implementation will
* behave as if the following {@link ErrorHandler} is set:
* <pre>
* class DraconianErrorHandler implements {@link ErrorHandler} {
* public void fatalError( {@link org.xml.sax.SAXParseException} e ) throws {@link SAXException} {
* throw e;
* }
* public void error( {@link org.xml.sax.SAXParseException} e ) throws {@link SAXException} {
* throw e;
* }
* public void warning( {@link org.xml.sax.SAXParseException} e ) throws {@link SAXException} {
* // noop
* }
* }
* </pre>
*
* <p>
* When a new {@link Validator} object is created, initially
* this field is set to null.
*
* @param errorHandler
* A new error handler to be set. This parameter can be null.
*/
public abstract void setErrorHandler(ErrorHandler errorHandler);
/**
* Gets the current {@link ErrorHandler} set to this {@link Validator}.
*
* @return
* This method returns the object that was last set through
* the {@link #setErrorHandler(ErrorHandler)} method, or null
* if that method has never been called since this {@link Validator}
* has created.
*
* @see #setErrorHandler(ErrorHandler)
*/
public abstract ErrorHandler getErrorHandler();
/**
* Sets the {@link LSResourceResolver} to customize
* resource resolution while in a validation episode.
*
* <p>
* {@link Validator} uses a {@link LSResourceResolver}
* when it needs to locate external resources while a validation,
* although exactly what constitutes "locating external resources" is
* up to each schema language.
*
* <p>
* When the {@link LSResourceResolver} is null, the implementation will
* behave as if the following {@link LSResourceResolver} is set:
* <pre>
* class DumbLSResourceResolver implements {@link LSResourceResolver} {
* public {@link org.w3c.dom.ls.LSInput} resolveResource(
* String publicId, String systemId, String baseURI) {
*
* return null; // always return null
* }
* }
* </pre>
*
* <p>
* If a {@link LSResourceResolver} throws a {@link RuntimeException}
* (or instances of its derived classes),
* then the {@link Validator} will abort the parsing and
* the caller of the <code>validate</code> method will receive
* the same {@link RuntimeException}.
*
* <p>
* When a new {@link Validator} object is created, initially
* this field is set to null.
*
* @param resourceResolver
* A new resource resolver to be set. This parameter can be null.
*/
public abstract void setResourceResolver(LSResourceResolver resourceResolver);
/**
* Gets the current {@link LSResourceResolver} set to this {@link Validator}.
*
* @return
* This method returns the object that was last set through
* the {@link #setResourceResolver(LSResourceResolver)} method, or null
* if that method has never been called since this {@link Validator}
* has created.
*
* @see #setErrorHandler(ErrorHandler)
*/
public abstract LSResourceResolver getResourceResolver();
/**
* Look up the value of a feature flag.
*
* <p>The feature name is any fully-qualified URI. It is
* possible for a {@link Validator} to recognize a feature name but
* temporarily be unable to return its value.
* Some feature values may be available only in specific
* contexts, such as before, during, or after a validation.
*
* <p>Implementors are free (and encouraged) to invent their own features,
* using names built on their own URIs.</p>
*
* @param name The feature name, which is a non-null fully-qualified URI.
*
* @return The current value of the feature (true or false).
*
* @throws SAXNotRecognizedException If the feature
* value can't be assigned or retrieved.
* @throws SAXNotSupportedException When the
* {@link Validator} recognizes the feature name but
* cannot determine its value at this time.
* @throws NullPointerException
* When the name parameter is null.
*
* @see #setFeature(String, boolean)
*/
public boolean getFeature(String name)
throws SAXNotRecognizedException, SAXNotSupportedException {
if (name == null) {
throw new NullPointerException("the name parameter is null");
}
throw new SAXNotRecognizedException(name);
}
/**
* Set the value of a feature flag.
*
* <p>
* Feature can be used to control the way a {@link Validator}
* parses schemas, although {@link Validator}s are not required
* to recognize any specific feature names.</p>
*
* <p>The feature name is any fully-qualified URI. It is
* possible for a {@link Validator} to expose a feature value but
* to be unable to change the current value.
* Some feature values may be immutable or mutable only
* in specific contexts, such as before, during, or after
* a validation.</p>
*
* @param name The feature name, which is a non-null fully-qualified URI.
* @param value The requested value of the feature (true or false).
*
* @throws SAXNotRecognizedException If the feature
* value can't be assigned or retrieved.
* @throws SAXNotSupportedException When the
* {@link Validator} recognizes the feature name but
* cannot set the requested value.
* @throws NullPointerException
* When the name parameter is null.
*
* @see #getFeature(String)
*/
public void setFeature(String name, boolean value)
throws SAXNotRecognizedException, SAXNotSupportedException {
if (name == null) {
throw new NullPointerException("the name parameter is null");
}
throw new SAXNotRecognizedException(name);
}
/**
* Set the value of a property.
*
* <p>The property name is any fully-qualified URI. It is
* possible for a {@link Validator} to recognize a property name but
* to be unable to change the current value.
* Some property values may be immutable or mutable only
* in specific contexts, such as before, during, or after
* a validation.</p>
*
* <p>
* All implementations that implement JAXP 1.5 or newer are required to
* support the {@link javax.xml.XMLConstants#ACCESS_EXTERNAL_DTD} and
* {@link javax.xml.XMLConstants#ACCESS_EXTERNAL_SCHEMA} properties.
* </p>
* <ul>
* <li>
* <p>Access to external DTDs in source or Schema file is restricted to
* the protocols specified by the {@link javax.xml.XMLConstants#ACCESS_EXTERNAL_DTD}
* property. If access is denied during validation due to the restriction
* of this property, {@link org.xml.sax.SAXException} will be thrown by the
* {@link #validate(Source)} method.</p>
*
* <p>Access to external reference set by the schemaLocation attribute is
* restricted to the protocols specified by the
* {@link javax.xml.XMLConstants#ACCESS_EXTERNAL_SCHEMA} property.
* If access is denied during validation due to the restriction of this property,
* {@link org.xml.sax.SAXException} will be thrown by the
* {@link #validate(Source)} method.</p>
* </li>
* </ul>
*
* @param name The property name, which is a non-null fully-qualified URI.
* @param object The requested value for the property.
*
* @throws SAXNotRecognizedException If the property
* value can't be assigned or retrieved.
* @throws SAXNotSupportedException When the
* {@link Validator} recognizes the property name but
* cannot set the requested value.
* @throws NullPointerException
* When the name parameter is null.
*/
public void setProperty(String name, Object object)
throws SAXNotRecognizedException, SAXNotSupportedException {
if (name == null) {
throw new NullPointerException("the name parameter is null");
}
throw new SAXNotRecognizedException(name);
}
/**
* Look up the value of a property.
*
* <p>The property name is any fully-qualified URI. It is
* possible for a {@link Validator} to recognize a property name but
* temporarily be unable to return its value.
* Some property values may be available only in specific
* contexts, such as before, during, or after a validation.</p>
*
* <p>{@link Validator}s are not required to recognize any specific
* property names.</p>
*
* <p>Implementors are free (and encouraged) to invent their own properties,
* using names built on their own URIs.</p>
*
* @param name The property name, which is a non-null fully-qualified URI.
*
* @return The current value of the property.
*
* @throws SAXNotRecognizedException If the property
* value can't be assigned or retrieved.
* @throws SAXNotSupportedException When the
* XMLReader recognizes the property name but
* cannot determine its value at this time.
* @throws NullPointerException
* When the name parameter is null.
*
* @see #setProperty(String, Object)
*/
public Object getProperty(String name)
throws SAXNotRecognizedException, SAXNotSupportedException {
if (name == null) {
throw new NullPointerException("the name parameter is null");
}
throw new SAXNotRecognizedException(name);
}
}

485
jaxp/src/java.xml/share/classes/javax/xml/validation/ValidatorHandler.java Normal file
View file

@ -0,0 +1,485 @@
/*
* 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.
*/
package javax.xml.validation;
import org.w3c.dom.ls.LSResourceResolver;
import org.xml.sax.ContentHandler;
import org.xml.sax.ErrorHandler;
import org.xml.sax.SAXNotRecognizedException;
import org.xml.sax.SAXNotSupportedException;
/**
* Streaming validator that works on SAX stream.
*
* <p>
* A {@link ValidatorHandler} object is not thread-safe and not reentrant.
* In other words, it is the application's responsibility to make
* sure that one {@link ValidatorHandler} object is not used from
* more than one thread at any given time.
*
* <p>
* {@link ValidatorHandler} checks if the SAX events follow
* the set of constraints described in the associated {@link Schema},
* and additionally it may modify the SAX events (for example
* by adding default values, etc.)
*
* <p>
* {@link ValidatorHandler} extends from {@link ContentHandler},
* but it refines the underlying {@link ContentHandler} in
* the following way:
* <ol>
* <li>startElement/endElement events must receive non-null String
* for <code>uri</code>, <code>localName</code>, and <code>qname</code>,
* even though SAX allows some of them to be null.
* Similarly, the user-specified {@link ContentHandler} will receive non-null
* Strings for all three parameters.
*
* <li>Applications must ensure that {@link ValidatorHandler}'s
* {@link ContentHandler#startPrefixMapping(String,String)} and
* {@link ContentHandler#endPrefixMapping(String)} are invoked
* properly. Similarly, the user-specified {@link ContentHandler}
* will receive startPrefixMapping/endPrefixMapping events.
* If the {@link ValidatorHandler} introduces additional namespace
* bindings, the user-specified {@link ContentHandler} will receive
* additional startPrefixMapping/endPrefixMapping events.
*
* <li>{@link org.xml.sax.Attributes} for the
* {@link ContentHandler#startElement(String,String,String,Attributes)} method
* may or may not include xmlns* attributes.
* </ol>
*
* <p>
* A {@link ValidatorHandler} is automatically reset every time
* the startDocument method is invoked.
*
* <h2>Recognized Properties and Features</h2>
* <p>
* This spec defines the following feature that must be recognized
* by all {@link ValidatorHandler} implementations.
*
* <h3><code>http://xml.org/sax/features/namespace-prefixes</code></h3>
* <p>
* This feature controls how a {@link ValidatorHandler} introduces
* namespace bindings that were not present in the original SAX event
* stream.
* When this feature is set to true, it must make
* sure that the user's {@link ContentHandler} will see
* the corresponding <code>xmlns*</code> attribute in
* the {@link org.xml.sax.Attributes} object of the
* {@link ContentHandler#startElement(String,String,String,Attributes)}
* callback. Otherwise, <code>xmlns*</code> attributes must not be
* added to {@link org.xml.sax.Attributes} that's passed to the
* user-specified {@link ContentHandler}.
* <p>
* (Note that regardless of this switch, namespace bindings are
* always notified to applications through
* {@link ContentHandler#startPrefixMapping(String,String)} and
* {@link ContentHandler#endPrefixMapping(String)} methods of the
* {@link ContentHandler} specified by the user.)
*
* <p>
* Note that this feature does <em>NOT</em> affect the way
* a {@link ValidatorHandler} receives SAX events. It merely
* changes the way it augments SAX events.
*
* <p>This feature is set to <code>false</code> by default.</p>
*
* @author <a href="mailto:Kohsuke.Kawaguchi@Sun.com">Kohsuke Kawaguchi</a>
* @since 1.5
*/
public abstract class ValidatorHandler implements ContentHandler {
/**
* <p>Constructor for derived classes.</p>
*
* <p>The constructor does nothing.</p>
*
* <p>Derived classes must create {@link ValidatorHandler} objects that have
* <code>null</code> {@link ErrorHandler} and
* <code>null</code> {@link LSResourceResolver}.</p>
*/
protected ValidatorHandler() {
}
/**
* Sets the {@link ContentHandler} which receives
* the augmented validation result.
*
* <p>
* When a {@link ContentHandler} is specified, a
* {@link ValidatorHandler} will work as a filter
* and basically copy the incoming events to the
* specified {@link ContentHandler}.
*
* <p>
* In doing so, a {@link ValidatorHandler} may modify
* the events, for example by adding defaulted attributes.
*
* <p>
* A {@link ValidatorHandler} may buffer events to certain
* extent, but to allow {@link ValidatorHandler} to be used
* by a parser, the following requirement has to be met.
*
* <ol>
* <li>When
* {@link ContentHandler#startElement(String, String, String, Attributes)},
* {@link ContentHandler#endElement(String, String, String)},
* {@link ContentHandler#startDocument()}, or
* {@link ContentHandler#endDocument()}
* are invoked on a {@link ValidatorHandler},
* the same method on the user-specified {@link ContentHandler}
* must be invoked for the same event before the callback
* returns.
* <li>{@link ValidatorHandler} may not introduce new elements that
* were not present in the input.
*
* <li>{@link ValidatorHandler} may not remove attributes that were
* present in the input.
* </ol>
*
* <p>
* When a callback method on the specified {@link ContentHandler}
* throws an exception, the same exception object must be thrown
* from the {@link ValidatorHandler}. The {@link ErrorHandler}
* should not be notified of such an exception.
*
* <p>
* This method can be called even during a middle of a validation.
*
* @param receiver
* A {@link ContentHandler} or a null value.
*/
public abstract void setContentHandler(ContentHandler receiver);
/**
* Gets the {@link ContentHandler} which receives the
* augmented validation result.
*
* @return
* This method returns the object that was last set through
* the {@link #getContentHandler()} method, or null
* if that method has never been called since this {@link ValidatorHandler}
* has created.
*
* @see #setContentHandler(ContentHandler)
*/
public abstract ContentHandler getContentHandler();
/**
* Sets the {@link ErrorHandler} to receive errors encountered
* during the validation.
*
* <p>
* Error handler can be used to customize the error handling process
* during a validation. When an {@link ErrorHandler} is set,
* errors found during the validation will be first sent
* to the {@link ErrorHandler}.
*
* <p>
* The error handler can abort further validation immediately
* by throwing {@link org.xml.sax.SAXException} from the handler. Or for example
* it can print an error to the screen and try to continue the
* validation by returning normally from the {@link ErrorHandler}
*
* <p>
* If any {@link Throwable} is thrown from an {@link ErrorHandler},
* the same {@link Throwable} object will be thrown toward the
* root of the call stack.
*
* <p>
* {@link ValidatorHandler} is not allowed to
* throw {@link org.xml.sax.SAXException} without first reporting it to
* {@link ErrorHandler}.
*
* <p>
* When the {@link ErrorHandler} is null, the implementation will
* behave as if the following {@link ErrorHandler} is set:
* <pre>
* class DraconianErrorHandler implements {@link ErrorHandler} {
* public void fatalError( {@link org.xml.sax.SAXParseException} e ) throws {@link org.xml.sax.SAXException} {
* throw e;
* }
* public void error( {@link org.xml.sax.SAXParseException} e ) throws {@link org.xml.sax.SAXException} {
* throw e;
* }
* public void warning( {@link org.xml.sax.SAXParseException} e ) throws {@link org.xml.sax.SAXException} {
* // noop
* }
* }
* </pre>
*
* <p>
* When a new {@link ValidatorHandler} object is created, initially
* this field is set to null.
*
* @param errorHandler
* A new error handler to be set. This parameter can be null.
*/
public abstract void setErrorHandler(ErrorHandler errorHandler);
/**
* Gets the current {@link ErrorHandler} set to this {@link ValidatorHandler}.
*
* @return
* This method returns the object that was last set through
* the {@link #setErrorHandler(ErrorHandler)} method, or null
* if that method has never been called since this {@link ValidatorHandler}
* has created.
*
* @see #setErrorHandler(ErrorHandler)
*/
public abstract ErrorHandler getErrorHandler();
/**
* Sets the {@link LSResourceResolver} to customize
* resource resolution while in a validation episode.
*
* <p>
* {@link ValidatorHandler} uses a {@link LSResourceResolver}
* when it needs to locate external resources while a validation,
* although exactly what constitutes "locating external resources" is
* up to each schema language.
*
* <p>
* When the {@link LSResourceResolver} is null, the implementation will
* behave as if the following {@link LSResourceResolver} is set:
* <pre>
* class DumbLSResourceResolver implements {@link LSResourceResolver} {
* public {@link org.w3c.dom.ls.LSInput} resolveResource(
* String publicId, String systemId, String baseURI) {
*
* return null; // always return null
* }
* }
* </pre>
*
* <p>
* If a {@link LSResourceResolver} throws a {@link RuntimeException}
* (or instances of its derived classes),
* then the {@link ValidatorHandler} will abort the parsing and
* the caller of the <code>validate</code> method will receive
* the same {@link RuntimeException}.
*
* <p>
* When a new {@link ValidatorHandler} object is created, initially
* this field is set to null.
*
* @param resourceResolver
* A new resource resolver to be set. This parameter can be null.
*/
public abstract void setResourceResolver(LSResourceResolver resourceResolver);
/**
* Gets the current {@link LSResourceResolver} set to this {@link ValidatorHandler}.
*
* @return
* This method returns the object that was last set through
* the {@link #setResourceResolver(LSResourceResolver)} method, or null
* if that method has never been called since this {@link ValidatorHandler}
* has created.
*
* @see #setErrorHandler(ErrorHandler)
*/
public abstract LSResourceResolver getResourceResolver();
/**
* Obtains the {@link TypeInfoProvider} implementation of this
* {@link ValidatorHandler}.
*
* <p>
* The obtained {@link TypeInfoProvider} can be queried during a parse
* to access the type information determined by the validator.
*
* <p>
* Some schema languages do not define the notion of type,
* for those languages, this method may not be supported.
* However, to be compliant with this specification, implementations
* for W3C XML Schema 1.0 must support this operation.
*
* @return
* null if the validator / schema language does not support
* the notion of {@link org.w3c.dom.TypeInfo}.
* Otherwise a non-null valid {@link TypeInfoProvider}.
*/
public abstract TypeInfoProvider getTypeInfoProvider();
/**
* Look up the value of a feature flag.
*
* <p>The feature name is any fully-qualified URI. It is
* possible for a {@link ValidatorHandler} to recognize a feature name but
* temporarily be unable to return its value.
* Some feature values may be available only in specific
* contexts, such as before, during, or after a validation.
*
* <p>Implementors are free (and encouraged) to invent their own features,
* using names built on their own URIs.</p>
*
* @param name The feature name, which is a non-null fully-qualified URI.
*
* @return The current value of the feature (true or false).
*
* @throws SAXNotRecognizedException If the feature
* value can't be assigned or retrieved.
* @throws SAXNotSupportedException When the
* {@link ValidatorHandler} recognizes the feature name but
* cannot determine its value at this time.
* @throws NullPointerException When <code>name</code> is <code>null</code>.
*
* @see #setFeature(String, boolean)
*/
public boolean getFeature(String name)
throws SAXNotRecognizedException, SAXNotSupportedException {
if (name == null) {
throw new NullPointerException();
}
throw new SAXNotRecognizedException(name);
}
/**
* <p>Set a feature for this <code>ValidatorHandler</code>.</p>
*
* <p>Feature can be used to control the way a
* {@link ValidatorHandler} parses schemas. The feature name is
* any fully-qualified URI. It is possible for a
* {@link SchemaFactory} to
* expose a feature value but to be unable to change the current
* value. Some feature values may be immutable or mutable only in
* specific contexts, such as before, during, or after a
* validation.</p>
*
* <p>All implementations are required to support the {@link javax.xml.XMLConstants#FEATURE_SECURE_PROCESSING} feature.
* When the feature is:</p>
* <ul>
* <li>
* <code>true</code>: the implementation will limit XML processing to conform to implementation limits.
* Examples include entity expansion limits and XML Schema constructs that would consume large amounts of resources.
* If XML processing is limited for security reasons, it will be reported via a call to the registered
* {@link ErrorHandler#fatalError(SAXParseException exception)}.
* See {@link #setErrorHandler(ErrorHandler errorHandler)}.
* </li>
* <li>
* <code>false</code>: the implementation will processing XML according to the XML specifications without
* regard to possible implementation limits.
* </li>
* </ul>
*
* @param name The feature name, which is a non-null fully-qualified URI.
* @param value The requested value of the feature (true or false).
*
* @throws SAXNotRecognizedException If the feature
* value can't be assigned or retrieved.
* @throws SAXNotSupportedException When the
* {@link ValidatorHandler} recognizes the feature name but
* cannot set the requested value.
* @throws NullPointerException When <code>name</code> is <code>null</code>.
*
* @see #getFeature(String)
*/
public void setFeature(String name, boolean value)
throws SAXNotRecognizedException, SAXNotSupportedException {
if (name == null) {
throw new NullPointerException();
}
throw new SAXNotRecognizedException(name);
}
/**
* Set the value of a property.
*
* <p>The property name is any fully-qualified URI. It is
* possible for a {@link ValidatorHandler} to recognize a property name but
* to be unable to change the current value.
* Some property values may be immutable or mutable only
* in specific contexts, such as before, during, or after
* a validation.</p>
*
* <p>{@link ValidatorHandler}s are not required to recognize setting
* any specific property names.</p>
*
* @param name The property name, which is a non-null fully-qualified URI.
* @param object The requested value for the property.
*
* @throws SAXNotRecognizedException If the property
* value can't be assigned or retrieved.
* @throws SAXNotSupportedException When the
* {@link ValidatorHandler} recognizes the property name but
* cannot set the requested value.
* @throws NullPointerException When <code>name</code> is <code>null</code>.
*/
public void setProperty(String name, Object object)
throws SAXNotRecognizedException, SAXNotSupportedException {
if (name == null) {
throw new NullPointerException();
}
throw new SAXNotRecognizedException(name);
}
/**
* Look up the value of a property.
*
* <p>The property name is any fully-qualified URI. It is
* possible for a {@link ValidatorHandler} to recognize a property name but
* temporarily be unable to return its value.
* Some property values may be available only in specific
* contexts, such as before, during, or after a validation.</p>
*
* <p>{@link ValidatorHandler}s are not required to recognize any specific
* property names.</p>
*
* <p>Implementors are free (and encouraged) to invent their own properties,
* using names built on their own URIs.</p>
*
* @param name The property name, which is a non-null fully-qualified URI.
*
* @return The current value of the property.
*
* @throws SAXNotRecognizedException If the property
* value can't be assigned or retrieved.
* @throws SAXNotSupportedException When the
* XMLReader recognizes the property name but
* cannot determine its value at this time.
* @throws NullPointerException When <code>name</code> is <code>null</code>.
*
* @see #setProperty(String, Object)
*/
public Object getProperty(String name)
throws SAXNotRecognizedException, SAXNotSupportedException {
if (name == null) {
throw new NullPointerException();
}
throw new SAXNotRecognizedException(name);
}
}

124
jaxp/src/java.xml/share/classes/javax/xml/validation/package.html Normal file
View file

@ -0,0 +1,124 @@
<?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.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 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):
</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>