< prev index next >
src/java.xml/share/classes/javax/xml/validation/SchemaFactory.java
Print this page
@@ -35,11 +35,11 @@
import org.xml.sax.SAXNotRecognizedException;
import org.xml.sax.SAXNotSupportedException;
import org.xml.sax.SAXParseException;
/**
- * Factory that creates {@link Schema} objects. Entry-point to
+ * Factory that creates {@link Schema} objects. Entry-point to
* the validation API.
*
* <p>
* {@link SchemaFactory} is a schema compiler. It reads external
* representations of schemas and prepares them for validation.
@@ -47,16 +47,16 @@
* <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.
+ * as {@code synchronized} 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,
+ * {@code newSchema} methods is being invoked, applications
+ * may not attempt to recursively invoke the {@code newSchema} 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.
@@ -90,15 +90,15 @@
* <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>{@link javax.xml.XMLConstants#W3C_XML_SCHEMA_NS_URI} ("{@code http://www.w3.org/2001/XMLSchema}")</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>{@link javax.xml.XMLConstants#RELAXNG_NS_URI} ("{@code http://relaxng.org/ns/structure/1.0}")</td>
* <td><a href="http://www.relaxng.org/">RELAX NG 1.0</a></td>
* </tr>
* </tbody>
* </table>
*
@@ -110,28 +110,28 @@
public abstract class SchemaFactory {
private static SecuritySupport ss = new SecuritySupport();
/**
- * <p>Constructor for derived classes.</p>
+ * Constructor for derived classes.
*
- * <p>The constructor does nothing.</p>
+ * <p>The constructor does nothing.
*
* <p>Derived classes must create {@link SchemaFactory} objects that have
- * <code>null</code> {@link ErrorHandler} and
- * <code>null</code> {@link LSResourceResolver}.</p>
+ * {@code null} {@link ErrorHandler} and
+ * {@code null} {@link LSResourceResolver}.
*/
protected SchemaFactory() {
}
/**
- * <p>Lookup an implementation of the <code>SchemaFactory</code> that supports the specified
- * schema language and return it.</p>
+ * Lookup an implementation of the {@code SchemaFactory} that supports the specified
+ * schema language and return it.
*
- * <p>To find a <code>SchemaFactory</code> object for a given schema language,
+ * <p>To find a {@code SchemaFactory} 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>
+ * where "the class loader" refers to the context class loader:
* <ol>
* <li>
* <p>
* If the system property
* {@code "javax.xml.validation.SchemaFactory:<i>schemaLanguage</i>"}
@@ -176,13 +176,13 @@
* In case of {@link java.util.ServiceConfigurationError} a
* {@link SchemaFactoryConfigurationError} will be thrown.
* </li>
* <li>
* <p>
- * Platform default <code>SchemaFactory</code> is located
+ * Platform default {@code SchemaFactory} is located
* in a implementation specific way. There must be a platform default
- * <code>SchemaFactory</code> for W3C XML Schema.
+ * {@code SchemaFactory} for W3C XML Schema.
* </li>
* </ol>
*
* <p>If everything fails, {@link IllegalArgumentException} will be thrown.
*
@@ -199,16 +199,16 @@
* 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>
+ * @return New instance of a {@code SchemaFactory}
*
* @throws IllegalArgumentException
* If no implementation of the schema language is available.
* @throws NullPointerException
- * If the <code>schemaLanguage</code> parameter is null.
+ * If the {@code schemaLanguage} parameter is null.
* @throws SchemaFactoryConfigurationError
* If a configuration error is encountered.
*
* @see #newInstance(String schemaLanguage, String factoryClassName, ClassLoader classLoader)
*/
@@ -231,46 +231,46 @@
}
return f;
}
/**
- * <p>Obtain a new instance of a <code>SchemaFactory</code> from class name. <code>SchemaFactory</code>
+ * Obtain a new instance of a {@code SchemaFactory} from class name. {@code SchemaFactory}
* 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>
+ * should be loaded.
*
* <h2>Tip for Trouble-shooting</h2>
- * <p>Setting the <code>jaxp.debug</code> system property will cause
+ * <p>Setting the {@code jaxp.debug} 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>
+ * to {@code System.err} about what it is doing and where it is looking at.
*
- * <p> If you have problems try:</p>
+ * <p> If you have problems try:
* <pre>
* java -Djaxp.debug=1 YourProgram ....
* </pre>
*
* @param schemaLanguage Specifies the schema language which the returned
- * <code>SchemaFactory</code> will understand. See
+ * {@code SchemaFactory} 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 factoryClassName fully qualified factory class name that provides implementation of {@code javax.xml.validation.SchemaFactory}.
*
- * @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.
+ * @param classLoader {@code ClassLoader} used to load the factory class. If {@code null}
+ * current {@code Thread}'s context classLoader is used to load the factory class.
*
- * @return New instance of a <code>SchemaFactory</code>
+ * @return New instance of a {@code SchemaFactory}
*
* @throws IllegalArgumentException
- * if <code>factoryClassName</code> is <code>null</code>, or
+ * if {@code factoryClassName} is {@code null}, or
* the factory class cannot be loaded, instantiated or doesn't
- * support the schema language specified in <code>schemLanguage</code>
+ * support the schema language specified in {@code schemLanguage}
* parameter.
*
* @throws NullPointerException
- * If the <code>schemaLanguage</code> parameter is null.
+ * If the {@code schemaLanguage} parameter is null.
*
* @see #newInstance(String schemaLanguage)
*
* @since 1.6
*/
@@ -297,20 +297,20 @@
}
}
/**
- * <p>Is specified schema supported by this <code>SchemaFactory</code>?</p>
+ * Is specified schema supported by this {@code SchemaFactory}?
*
- * @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.
+ * @param schemaLanguage Specifies the schema language which the returned {@code SchemaFactory} will understand.
+ * {@code schemaLanguage} 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>.
+ * @return {@code true} if {@code SchemaFactory} supports {@code schemaLanguage}, else {@code false}.
*
- * @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.
+ * @throws NullPointerException If {@code schemaLanguage} is {@code null}.
+ * @throws IllegalArgumentException If {@code schemaLanguage.length() == 0}
+ * or {@code schemaLanguage} 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.
@@ -318,22 +318,22 @@
* <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>
+ * using names built on their own URIs.
*
* @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>.
+ * @throws NullPointerException If {@code name} is {@code null}.
*
* @see #setFeature(String, boolean)
*/
public boolean getFeature(String name)
throws SAXNotRecognizedException, SAXNotSupportedException {
@@ -343,42 +343,42 @@
}
throw new SAXNotRecognizedException(name);
}
/**
- * <p>Set a feature for this <code>SchemaFactory</code>,
+ * Set a feature for this {@code SchemaFactory},
* {@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
+ * {@code SchemaFactory} 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.
+ * for {@code SchemaFactory} features to be inherited automatically.
* Developers should
* make sure that features, such as secure processing, are explicitly
- * set in both places.</p>
+ * set in both places.
*
* <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>
+ * to be unable to change the current value.
*
* <p>All implementations are required to support the {@link javax.xml.XMLConstants#FEATURE_SECURE_PROCESSING} feature.
- * When the feature is:</p>
+ * When the feature is:
* <ul>
* <li>
- * <code>true</code>: the implementation will limit XML processing to conform to implementation limits.
+ * {@code true}: 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
+ * {@code false}: 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.
@@ -387,11 +387,11 @@
* @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>.
+ * @throws NullPointerException If {@code name} is {@code null}.
*
* @see #getFeature(String)
*/
public void setFeature(String name, boolean value)
throws SAXNotRecognizedException, SAXNotSupportedException {
@@ -405,48 +405,48 @@
/**
* 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>
+ * to be unable to change the current value.
*
* <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>
+ * or {@link #newSchema(URL)} or {@link #newSchema(Source[])} method.
*
* <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>
+ * {@link javax.xml.validation.Validator#validate(Source, Result)} method.
*
* <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>
+ * {@link javax.xml.validation.Validator#validate(Source, Result)} method.
*
* <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>
+ * or {@link #newSchema(URL)} or {@link #newSchema(Source[])} method.
* </li>
* </ul>
*
* @param name The property name, which is a non-null fully-qualified URI.
* @param object The requested value for the property.
@@ -454,11 +454,11 @@
* @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>.
+ * @throws NullPointerException If {@code name} is {@code null}.
*/
public void setProperty(String name, Object object)
throws SAXNotRecognizedException, SAXNotSupportedException {
if (name == null) {
@@ -470,28 +470,28 @@
/**
* 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>
+ * temporarily be unable to return its value.
*
* <p>{@link SchemaFactory}s are not required to recognize any specific
- * property names.</p>
+ * property names.
*
* <p>Implementors are free (and encouraged) to invent their own properties,
- * using names built on their own URIs.</p>
+ * using names built on their own URIs.
*
* @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>.
+ * @throws NullPointerException If {@code name} is {@code null}.
*
* @see #setProperty(String, Object)
*/
public Object getProperty(String name)
throws SAXNotRecognizedException, SAXNotSupportedException {
@@ -502,11 +502,11 @@
throw new SAXNotRecognizedException(name);
}
/**
* Sets the {@link ErrorHandler} to receive errors encountered
- * during the <code>newSchema</code> method invocation.
+ * during the {@code newSchema} 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
@@ -519,11 +519,11 @@
* 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 caller of the {@code newSchema} method will be thrown
* the same {@link Throwable} object.
*
* <p>
* {@link SchemaFactory} is not allowed to
* throw {@link SAXException} without first reporting it to
@@ -555,11 +555,11 @@
* 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>.
+ * This parameter can be {@code null}.
*/
public abstract void setErrorHandler(ErrorHandler errorHandler);
/**
* Gets the current {@link ErrorHandler} set to this {@link SchemaFactory}.
@@ -581,11 +581,11 @@
* <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><include></code>d or <code><import></code>ed,
+ * this includes files {@code <include>}d or {@code <import>}ed,
* and DTD referenced from schema files, etc.
*
* <p>
* Applications can call this method even during a {@link Schema}
* is being parsed.
@@ -605,11 +605,11 @@
*
* <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 caller of the {@code newSchema} 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
@@ -633,52 +633,52 @@
* @see #setErrorHandler(ErrorHandler)
*/
public abstract LSResourceResolver getResourceResolver();
/**
- * <p>Parses the specified source as a schema and returns it as a schema.</p>
+ * Parses the specified source as a schema and returns it as a schema.
*
- * <p>This is a convenience method for {@link #newSchema(Source[] schemas)}.</p>
+ * <p>This is a convenience method for {@link #newSchema(Source[] schemas)}.
*
* @param schema Source that represents a schema.
*
- * @return New <code>Schema</code> from parsing <code>schema</code>.
+ * @return New {@code Schema} from parsing {@code schema}.
*
* @throws SAXException If a SAX error occurs during parsing.
- * @throws NullPointerException if <code>schema</code> is null.
+ * @throws NullPointerException if {@code schema} 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>
+ * Parses the specified {@code File} as a schema and returns it as a {@code Schema}.
*
- * <p>This is a convenience method for {@link #newSchema(Source schema)}.</p>
+ * <p>This is a convenience method for {@link #newSchema(Source schema)}.
*
* @param schema File that represents a schema.
*
- * @return New <code>Schema</code> from parsing <code>schema</code>.
+ * @return New {@code Schema} from parsing {@code schema}.
*
* @throws SAXException If a SAX error occurs during parsing.
- * @throws NullPointerException if <code>schema</code> is null.
+ * @throws NullPointerException if {@code schema} 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>
+ * Parses the specified {@code URL} as a schema and returns it as a {@code Schema}.
*
- * <p>This is a convenience method for {@link #newSchema(Source schema)}.</p>
+ * <p>This is a convenience method for {@link #newSchema(Source schema)}.
*
- * @param schema <code>URL</code> that represents a schema.
+ * @param schema {@code URL} that represents a schema.
*
- * @return New <code>Schema</code> from parsing <code>schema</code>.
+ * @return New {@code Schema} from parsing {@code schema}.
*
* @throws SAXException If a SAX error occurs during parsing.
- * @throws NullPointerException if <code>schema</code> is null.
+ * @throws NullPointerException if {@code schema} is null.
*/
public Schema newSchema(URL schema) throws SAXException {
return newSchema(new StreamSource(schema.toExternalForm()));
}
@@ -708,22 +708,22 @@
* 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 <import> for a given namespace,
+ * to ignore all but the first {@code <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>.
+ * if {@code schemas.length!=1}.
*
*
* @param schemas
* inputs to be parsed. {@link SchemaFactory} is required
* to recognize {@link javax.xml.transform.sax.SAXSource},
@@ -746,11 +746,11 @@
* @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
+ * If the {@code schemas} 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.
@@ -763,22 +763,22 @@
* <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>
+ * property/feature to alter the semantics of this method.
*
* <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>
+ * set in both places.
*
* <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.
< prev index next >