javax.xml.parsers.SAXParserFactory Maven / Gradle / Ivy
/*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
// $Id: SAXParserFactory.java 446598 2006-09-15 12:55:40Z jeremias $
package javax.xml.parsers;
import javax.xml.validation.Schema;
import org.xml.sax.SAXException;
import org.xml.sax.SAXNotRecognizedException;
import org.xml.sax.SAXNotSupportedException;
/**
* Defines a factory API that enables applications to configure and
* obtain a SAX based parser to parse XML documents.
*
* @author Jeff Suttor
* @version $Revision: 446598 $, $Date: 2006-09-15 08:55:40 -0400 (Fri, 15 Sep 2006) $
*/
public abstract class SAXParserFactory {
/**
* Should Parsers be validating?
*/
private boolean validating = false;
/**
* Should Parsers be namespace aware?
*/
private boolean namespaceAware = false;
/**
* Protected constructor to force use of {@link #newInstance()}.
*/
protected SAXParserFactory () {
}
/**
* Obtain a new instance of a SAXParserFactory. This
* static method creates a new factory instance
* This method uses the following ordered lookup procedure to determine
* the SAXParserFactory implementation class to
* load:
*
* -
* Use the
javax.xml.parsers.SAXParserFactory system
* property.
*
* -
* Use the properties file "lib/jaxp.properties" in the JRE directory.
* This configuration file is in standard
java.util.Properties
* format and contains the fully qualified name of the
* implementation class with the key being the system property defined
* above.
*
* The jaxp.properties file is read only once by the JAXP implementation
* and it's values are then cached for future use. If the file does not exist
* when the first attempt is made to read from it, no further attempts are
* made to check for its existence. It is not possible to change the value
* of any property in jaxp.properties after it has been read for the first time.
*
* -
* Use the Services API (as detailed in the JAR specification), if
* available, to determine the classname. The Services API will look
* for a classname in the file
*
META-INF/services/javax.xml.parsers.SAXParserFactory
* in jars available to the runtime.
*
* -
* Platform default
SAXParserFactory instance.
*
*
*
* Once an application has obtained a reference to a
* SAXParserFactory it can use the factory to
* configure and obtain parser instances.
*
*
*
* Tip for Trouble-shooting
* Setting the jaxp.debug system property will cause
* this method to print a lot of debug messages
* to System.err about what it is doing and where it is looking at.
*
* If you have problems loading {@link DocumentBuilder}s, try:
*
* java -Djaxp.debug=1 YourProgram ....
*
*
*
* @return A new instance of a SAXParserFactory.
*
* @exception FactoryConfigurationError if the implementation is
* not available or cannot be instantiated.
*/
public static SAXParserFactory newInstance() {
try {
return (SAXParserFactory) FactoryFinder.find(
/* The default property name according to the JAXP spec */
"javax.xml.parsers.SAXParserFactory",
/* The fallback implementation class name */
"org.apache.xerces.jaxp.SAXParserFactoryImpl");
} catch (FactoryFinder.ConfigurationError e) {
throw new FactoryConfigurationError(e.getException(),
e.getMessage());
}
}
/**
* Creates a new instance of a SAXParser using the currently
* configured factory parameters.
*
* @return A new instance of a SAXParser.
*
* @exception ParserConfigurationException if a parser cannot
* be created which satisfies the requested configuration.
* @exception SAXException for SAX errors.
*/
public abstract SAXParser newSAXParser()
throws ParserConfigurationException, SAXException;
/**
* Specifies that the parser produced by this code will
* provide support for XML namespaces. By default the value of this is set
* to false.
*
* @param awareness true if the parser produced by this code will
* provide support for XML namespaces; false otherwise.
*/
public void setNamespaceAware(boolean awareness) {
this.namespaceAware = awareness;
}
/**
* Specifies that the parser produced by this code will
* validate documents as they are parsed. By default the value of this is
* set to false.
*
*
* Note that "the validation" here means
* a validating
* parser as defined in the XML recommendation.
* In other words, it essentially just controls the DTD validation.
* (except the legacy two properties defined in JAXP 1.2.
* See here for more details.)
*
*
*
* To use modern schema languages such as W3C XML Schema or
* RELAX NG instead of DTD, you can configure your parser to be
* a non-validating parser by leaving the {@link #setValidating(boolean)}
* method false, then use the {@link #setSchema(Schema)}
* method to associate a schema to a parser.
*
*
* @param validating true if the parser produced by this code will
* validate documents as they are parsed; false otherwise.
*/
public void setValidating(boolean validating) {
this.validating = validating;
}
/**
* Indicates whether or not the factory is configured to produce
* parsers which are namespace aware.
*
* @return true if the factory is configured to produce
* parsers which are namespace aware; false otherwise.
*/
public boolean isNamespaceAware() {
return namespaceAware;
}
/**
* Indicates whether or not the factory is configured to produce
* parsers which validate the XML content during parse.
*
* @return true if the factory is configured to produce parsers which validate
* the XML content during parse; false otherwise.
*/
public boolean isValidating() {
return validating;
}
/**
*
* Sets the particular feature in the underlying implementation of
* org.xml.sax.XMLReader.
* A list of the core features and properties can be found at
* http://www.saxproject.org/
*
* All implementations are required to support the {@link javax.xml.XMLConstants#FEATURE_SECURE_PROCESSING} feature.
* When the feature is
*
* -
*
true: the implementation will limit XML processing to conform to implementation limits.
* Examples include enity 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 org.xml.sax.ErrorHandler#fatalError(SAXParseException exception)}.
* See {@link SAXParser} parse methods for handler specification.
*
* -
* When the feature is
false, the implementation will processing XML according to the XML specifications without
* regard to possible implementation limits.
*
*
*
* @param name The name of the feature to be set.
* @param value The value of the feature to be set.
*
* @exception ParserConfigurationException if a parser cannot
* be created which satisfies the requested configuration.
* @exception SAXNotRecognizedException When the underlying XMLReader does
* not recognize the property name.
* @exception SAXNotSupportedException When the underlying XMLReader
* recognizes the property name but doesn't support the
* property.
* @throws NullPointerException If the name parameter is null.
*
* @see org.xml.sax.XMLReader#setFeature
*/
public abstract void setFeature(String name, boolean value)
throws ParserConfigurationException, SAXNotRecognizedException,
SAXNotSupportedException;
/**
*
* Returns the particular property requested for in the underlying
* implementation of org.xml.sax.XMLReader.
*
* @param name The name of the property to be retrieved.
*
* @return Value of the requested property.
*
* @exception ParserConfigurationException if a parser cannot be created which satisfies the requested configuration.
* @exception SAXNotRecognizedException When the underlying XMLReader does not recognize the property name.
* @exception SAXNotSupportedException When the underlying XMLReader recognizes the property name but doesn't support the property.
*
* @see org.xml.sax.XMLReader#getProperty
*/
public abstract boolean getFeature(String name)
throws ParserConfigurationException, SAXNotRecognizedException,
SAXNotSupportedException;
/**
* Gets the {@link Schema} object specified through
* the {@link #setSchema(Schema schema)} method.
*
*
* @throws UnsupportedOperationException
* For backward compatibility, when implementations for
* earlier versions of JAXP is used, this exception will be
* thrown.
*
* @return
* the {@link Schema} object that was last set through
* the {@link #setSchema(Schema)} method, or null
* if the method was not invoked since a {@link SAXParserFactory}
* is created.
*
* @since 1.5
*/
public Schema getSchema() {
throw new UnsupportedOperationException(
"This parser does not support specification \""
+ this.getClass().getPackage().getSpecificationTitle()
+ "\" version \""
+ this.getClass().getPackage().getSpecificationVersion()
+ "\""
);
}
/**
* Set the {@link Schema} to be used by parsers created
* from this factory.
*
* When a {@link Schema} is non-null, a parser will use a validator
* created from it to validate documents before it passes information
* down to the application.
*
* When warnings/errors/fatal errors are found by the validator, the parser must
* handle them as if those errors were found by the parser itself.
* In other words, if the user-specified {@link org.xml.sax.ErrorHandler}
* is set, it must receive those errors, and if not, they must be
* treated according to the implementation specific
* default error handling rules.
*
*
A validator may modify the SAX event stream (for example by
* adding default values that were missing in documents), and a parser
* is responsible to make sure that the application will receive
* those modified event stream.
*
* Initialy, null is set as the {@link Schema}.
*
* This processing will take effect even if
* the {@link #isValidating()} method returns false.
*
*
It is an error to use
* the http://java.sun.com/xml/jaxp/properties/schemaSource
* property and/or the http://java.sun.com/xml/jaxp/properties/schemaLanguage
* property in conjunction with a non-null {@link Schema} object.
* Such configuration will cause a {@link SAXException}
* exception when those properties are set on a {@link SAXParser}.
*
* Note for implmentors
*
* A parser must be able to work with any {@link Schema}
* implementation. However, parsers and schemas are allowed
* to use implementation-specific custom mechanisms
* as long as they yield the result described in the specification.
*
*
* @param schema Schema to use, null to remove a schema.
*
* @throws UnsupportedOperationException
* For backward compatibility, when implementations for
* earlier versions of JAXP is used, this exception will be
* thrown.
*
* @since 1.5
*/
public void setSchema(Schema schema) {
throw new UnsupportedOperationException(
"This parser does not support specification \""
+ this.getClass().getPackage().getSpecificationTitle()
+ "\" version \""
+ this.getClass().getPackage().getSpecificationVersion()
+ "\""
);
}
/**
* Set state of XInclude processing.
*
* If XInclude markup is found in the document instance, should it be
* processed as specified in
* XML Inclusions (XInclude) Version 1.0.
*
* XInclude processing defaults to false.
*
* @param state Set XInclude processing to true or
* false
*
* @throws UnsupportedOperationException
* For backward compatibility, when implementations for
* earlier versions of JAXP is used, this exception will be
* thrown.
*
* @since 1.5
*/
public void setXIncludeAware(final boolean state) {
throw new UnsupportedOperationException(
"This parser does not support specification \""
+ this.getClass().getPackage().getSpecificationTitle()
+ "\" version \""
+ this.getClass().getPackage().getSpecificationVersion()
+ "\""
);
}
/**
* Get state of XInclude processing.
*
* @return current state of XInclude processing
*
* @throws UnsupportedOperationException
* For backward compatibility, when implementations for
* earlier versions of JAXP is used, this exception will be
* thrown.
*
* @since 1.5
*/
public boolean isXIncludeAware() {
throw new UnsupportedOperationException(
"This parser does not support specification \""
+ this.getClass().getPackage().getSpecificationTitle()
+ "\" version \""
+ this.getClass().getPackage().getSpecificationVersion()
+ "\""
);
}
}