javax.xml.parsers.SAXParserFactory Maven / Gradle / Ivy
/* * The contents of this file are subject to the terms * of the Common Development and Distribution License * (the "License"). You may not use this file except * in compliance with the License. * * You can obtain a copy of the license at * https://jaxp.dev.java.net/CDDLv1.0.html. * See the License for the specific language governing * permissions and limitations under the License. * * When distributing Covered Code, include this CDDL * HEADER in each file and include the License file at * https://jaxp.dev.java.net/CDDLv1.0.html * If applicable add the following below this CDDL HEADER * with the fields enclosed by brackets "[]" replaced with * your own identifying information: Portions Copyright * [year] [name of copyright owner] */ /* * $Id: SAXParserFactory.java,v 1.6 2006/05/19 01:08:43 jeffsuttor Exp $ * %W% %E% * * Copyright 2005 Sun Microsystems, Inc. All Rights Reserved. */ 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 * @author Neeraj Bajaj * * @version $Revision: 1.7 $, $Date: 2007/26/04 20:34:00 $ * Modified 26/04/2007 - Quentin Anciaux * */ public abstract class SAXParserFactory { /** The default property name according to the JAXP spec */ private static final String DEFAULT_PROPERTY_NAME = "javax.xml.parsers.SAXParserFactory"; /** *
false. * * @param state of canonicalization */ /* public void setCanonicalization(boolean state) { canonicalState = state; } */ /** *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 aSAXParserFactory
. This * static method creates a new factory instance * This method uses the following ordered lookup procedure to determine * theSAXParserFactory
implementation class to * load: **
* * Once an application has obtained a reference to a *- * 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. *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 * toSystem.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. * * @throws 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 */ /* Modification to call Shani XML parser SAX * parser factory - Quentin Anciaux - 26/04/2007 */ "org.allcolor.xml.parser.CSaxParserFactory"); } catch (FactoryFinder.ConfigurationError e) { throw new FactoryConfigurationError(e.getException(), e.getMessage()); } } /** *Obtain a new instance of a
* *SAXParserFactory
from class name. * 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.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 * toSystem.err
about what it is doing and where it is looking at.If you have problems, try:
** java -Djaxp.debug=1 YourProgram .... ** * @param factoryClassName fully qualified factory class name that provides implementation ofjavax.xml.parsers.SAXParserFactory
. * * @param classLoaderClassLoader
used to load the factory class. Ifnull
* currentThread
's context classLoader is used to load the factory class. * * @return New instance of aSAXParserFactory
* * @throws FactoryConfigurationError iffactoryClassName
isnull
, or * the factory class cannot be loaded, instantiated. * * @see #newInstance() * * @since 1.6 */ public static SAXParserFactory newInstance(String factoryClassName, ClassLoader classLoader){ try { //do not fallback if given classloader can't find the class, throw exception return (SAXParserFactory) FactoryFinder.newInstance(factoryClassName, classLoader, false); } 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. * * @throws ParserConfigurationException if a parser cannot * be created which satisfies the requested configuration. * @throws 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 * tofalse
. * * @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 tofalse
. * ** 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.) *
* ** 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
* * @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; } /** * *false
, then use the {@link #setSchema(Schema)} * method to associate a schema to a parser. *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
**
* * @param name The name of the feature to be set. * @param value The value of the feature to be set. * * @throws ParserConfigurationException if a parser cannot * be created which satisfies the requested configuration. * @throws SAXNotRecognizedException When the underlying XMLReader does * not recognize the property name. * @throws SAXNotSupportedException When the underlying XMLReader * recognizes the property name but doesn't support the * property. * @throws NullPointerException If the- *
*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. *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. * * @throws ParserConfigurationException if a parser cannot be created which satisfies the requested configuration. * @throws SAXNotRecognizedException When the underlying XMLReader does not recognize the property name. * @throws 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; /*Get current state of canonicalization.
* * @return current state canonicalization control */ /* public boolean getCanonicalization() { return canonicalState; } */ /** * Gets the {@link Schema} object specified through * the {@link #setSchema(Schema schema)} method. * * * @throws UnsupportedOperationException When implementation does not * override this method * * @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 canonicalization control to
true
or *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 thehttp://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 schemaSchema
to use,null
to remove a schema. * * @throws UnsupportedOperationException When implementation does not * override this method * * @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
* * @param state Set XInclude processing tofalse
.true
or *false
* * @throws UnsupportedOperationException When implementation does not * override this method * * @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 When implementation does not * override this method * * @since 1.5 */ public boolean isXIncludeAware() { throw new UnsupportedOperationException( "This parser does not support specification \"" + this.getClass().getPackage().getSpecificationTitle() + "\" version \"" + this.getClass().getPackage().getSpecificationVersion() + "\"" ); } }