javax.xml.parsers.DocumentBuilderFactory 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: DocumentBuilderFactory.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; /** * Defines a factory API that enables applications to obtain a * parser that produces DOM object trees from 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 DocumentBuilderFactory { /** The default property name according to the JAXP spec */ private static final String DEFAULT_PROPERTY_NAME = "javax.xml.parsers.DocumentBuilderFactory"; private boolean validating = false; private boolean namespaceAware = false; private boolean whitespace = false; private boolean expandEntityRef = true; private boolean ignoreComments = false; private boolean coalescing = false; private boolean canonicalState = false; /** *
false. * * @param state of canonicalization */ /* public void setCanonicalization(boolean state) { canonicalState = state; } */ /** *Protected constructor to prevent instantiation. * Use {@link #newInstance()}.
*/ protected DocumentBuilderFactory () { } /** * Obtain a new instance of a *DocumentBuilderFactory
. This static method creates * a new factory instance. * This method uses the following ordered lookup procedure to determine * theDocumentBuilderFactory
implementation class to * load: **
* * Once an application has obtained a reference to a *- * Use the
*javax.xml.parsers.DocumentBuilderFactory
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.DocumentBuilderFactory
* in jars available to the runtime. *- * Platform default
*DocumentBuilderFactory
instance. *DocumentBuilderFactory
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 New instance of aDocumentBuilderFactory
* * @throws FactoryConfigurationError if the implementation is not * available or cannot be instantiated. */ public static DocumentBuilderFactory newInstance() { try { return (DocumentBuilderFactory) FactoryFinder.find( /* The default property name according to the JAXP spec */ "javax.xml.parsers.DocumentBuilderFactory", /* The fallback implementation class name */ /* Modification to call Shani XML parser document * builder factory - Quentin Anciaux - 26/04/2007 */ "org.allcolor.xml.parser.CDocumentBuilderFactory"); } catch (FactoryFinder.ConfigurationError e) { throw new FactoryConfigurationError(e.getException(), e.getMessage()); } } /** *Obtain a new instance of a
* *DocumentBuilderFactory
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
* * *DocumentBuilderFactory
* 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.DocumentBuilderFactory
. * * @param classLoaderClassLoader
used to load the factory class. Ifnull
* currentThread
's context classLoader is used to load the factory class. * * @return New instance of aDocumentBuilderFactory
* * @throws FactoryConfigurationError iffactoryClassName
isnull
, or * the factory class cannot be loaded, instantiated. * * @see #newInstance() * * @since 1.6 */ public static DocumentBuilderFactory newInstance(String factoryClassName, ClassLoader classLoader){ try { //do not fallback if given classloader can't find the class, throw exception return (DocumentBuilderFactory) FactoryFinder.newInstance(factoryClassName, classLoader, false); } catch (FactoryFinder.ConfigurationError e) { throw new FactoryConfigurationError(e.getException(), e.getMessage()); } } /** * Creates a new instance of a {@link javax.xml.parsers.DocumentBuilder} * using the currently configured parameters. * * @return A new instance of a DocumentBuilder. * * @throws ParserConfigurationException if a DocumentBuilder * cannot be created which satisfies the configuration requested. */ public abstract DocumentBuilder newDocumentBuilder() throws ParserConfigurationException; /** * 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 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 will validate documents * as they are parsed; false otherwise. */ public void setValidating(boolean validating) { this.validating = validating; } /** * Specifies that the parsers created by this factory must eliminate * whitespace in element content (sometimes known loosely as * 'ignorable whitespace') when parsing XML documents (see XML Rec * 2.10). Note that only whitespace which is directly contained within * element content that has an element only content model (see XML * Rec 3.2.1) will be eliminated. Due to reliance on the content model * this setting requires the parser to be in validating mode. By default * the value of this is set tofalse
, then use the {@link #setSchema(Schema)} * method to associate a schema to a parser. *false
. * * @param whitespace true if the parser created must eliminate whitespace * in the element content when parsing XML documents; * false otherwise. */ public void setIgnoringElementContentWhitespace(boolean whitespace) { this.whitespace = whitespace; } /** * Specifies that the parser produced by this code will * expand entity reference nodes. By default the value of this is set to *true
* * @param expandEntityRef true if the parser produced will expand entity * reference nodes; false otherwise. */ public void setExpandEntityReferences(boolean expandEntityRef) { this.expandEntityRef = expandEntityRef; } /** *Specifies that the parser produced by this code will * ignore comments. By default the value of this is set to
* * @param ignoreCommentsfalse *
.boolean
value to ignore comments during processing */ public void setIgnoringComments(boolean ignoreComments) { this.ignoreComments = ignoreComments; } /** * Specifies that the parser produced by this code will * convert CDATA nodes to Text nodes and append it to the * adjacent (if any) text node. By default the value of this is set to *false
* * @param coalescing true if the parser produced will convert CDATA nodes * to Text nodes and append it to the adjacent (if any) * text node; false otherwise. */ public void setCoalescing(boolean coalescing) { this.coalescing = coalescing; } /** * 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; } /** * Indicates whether or not the factory is configured to produce * parsers which ignore ignorable whitespace in element content. * * @return true if the factory is configured to produce parsers * which ignore ignorable whitespace in element content; * false otherwise. */ public boolean isIgnoringElementContentWhitespace() { return whitespace; } /** * Indicates whether or not the factory is configured to produce * parsers which expand entity reference nodes. * * @return true if the factory is configured to produce parsers * which expand entity reference nodes; false otherwise. */ public boolean isExpandEntityReferences() { return expandEntityRef; } /** * Indicates whether or not the factory is configured to produce * parsers which ignores comments. * * @return true if the factory is configured to produce parsers * which ignores comments; false otherwise. */ public boolean isIgnoringComments() { return ignoreComments; } /** * Indicates whether or not the factory is configured to produce * parsers which converts CDATA nodes to Text nodes and appends it to * the adjacent (if any) Text node. * * @return true if the factory is configured to produce parsers * which converts CDATA nodes to Text nodes and appends it to * the adjacent (if any) Text node; false otherwise. */ public boolean isCoalescing() { return coalescing; } /** * Allows the user to set specific attributes on the underlying * implementation. * * @param name The name of the attribute. * @param value The value of the attribute. * * @throws IllegalArgumentException thrown if the underlying * implementation doesn't recognize the attribute. */ public abstract void setAttribute(String name, Object value) throws IllegalArgumentException; /** * Allows the user to retrieve specific attributes on the underlying * implementation. * * @param name The name of the attribute. * * @return value The value of the attribute. * * @throws IllegalArgumentException thrown if the underlying * implementation doesn't recognize the attribute. */ public abstract Object getAttribute(String name) throws IllegalArgumentException; /** *Set a feature for this
* *DocumentBuilderFactory
andDocumentBuilder
s created by this factory.* Feature names are fully qualified {@link java.net.URI}s. * Implementations may define their own features. * A {@link ParserConfigurationException} is thrown if this
* *DocumentBuilderFactory
or the *DocumentBuilder
s it creates cannot support the feature. * It is possible for aDocumentBuilderFactory
to expose a feature value but be unable to change its state. ** All implementations are required to support the {@link javax.xml.XMLConstants#FEATURE_SECURE_PROCESSING} feature. * When the feature is:
**
* * @param name Feature name. * @param value Is feature state- *
*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 DocumentBuilder#setErrorHandler(org.xml.sax.ErrorHandler errorHandler)}. *- *
*false
: the implementation will processing XML according to the XML specifications without * regard to possible implementation limits. *true
orfalse
. * * @throws ParserConfigurationException if thisDocumentBuilderFactory
or theDocumentBuilder
s * it creates cannot support this feature. * @throws NullPointerException If thename
parameter is null. */ public abstract void setFeature(String name, boolean value) throws ParserConfigurationException; /** *Get the state of the named feature.
* ** Feature names are fully qualified {@link java.net.URI}s. * Implementations may define their own features. * An {@link ParserConfigurationException} is thrown if this
* * @param name Feature name. * * @return State of the named feature. * * @throws ParserConfigurationException if thisDocumentBuilderFactory
or the *DocumentBuilder
s it creates cannot support the feature. * It is possible for anDocumentBuilderFactory
to expose a feature value but be unable to change its state. *DocumentBuilderFactory
* or theDocumentBuilder
s it creates cannot support this feature. */ public abstract boolean getFeature(String name) throws ParserConfigurationException; /**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. * * @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 DocumentBuilderFactory} * is created. * * @throws UnsupportedOperationException When implementation does not * override this method. * * @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 errors are found by the validator, the parser is responsible * to report them to the user-specified {@link org.xml.sax.ErrorHandler} * (or if the error handler is not set, ignore them or throw them), just * like any other errors 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 outcome of a parse (for example by * adding default values that were missing in documents), and a parser * is responsible to make sure that the application will receive * modified DOM trees. * *
* 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 {@link Schema} object. * Such configuration will cause a {@link ParserConfigurationException} * exception when the {@link #newDocumentBuilder()} is invoked.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 ornull
* 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() + "\"" ); } }