All Downloads are FREE. Search and download functionalities are using the official Maven repository.

javax.xml.parsers.DocumentBuilderFactory Maven / Gradle / Ivy

There is a newer version: 1.2.9
Show newest version
/*
 * 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: DocumentBuilderFactory.java 884950 2009-11-27 18:46:18Z mrglavas $

package javax.xml.parsers;

import javax.xml.validation.Schema;
import org.apache.harmony.xml.parsers.DocumentBuilderFactoryImpl;

/**
 * Defines a factory API that enables applications to obtain a
 * parser that produces DOM object trees from XML documents.
 *
 * @author Jeff Suttor
 * @version $Revision: 884950 $, $Date: 2009-11-27 10:46:18 -0800 (Fri, 27 Nov 2009) $
 */

public abstract class 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;

    protected DocumentBuilderFactory () {
    }

    /**
     * Returns Android's implementation of {@code DocumentBuilderFactory}.
     * Unlike other Java implementations, this method does not consult system
     * properties, property files, or the services API.
     *
     * @return a new DocumentBuilderFactory.
     */
    public static DocumentBuilderFactory newInstance() {
        // instantiate the class directly rather than using reflection
        return new DocumentBuilderFactoryImpl();
    }

    /**
     * Returns an instance of the named implementation of {@code DocumentBuilderFactory}.
     *
     * @throws FactoryConfigurationError if {@code factoryClassName} is not available or cannot be
     *     instantiated.
     * @since 1.6
     */
    public static DocumentBuilderFactory newInstance(String factoryClassName,
            ClassLoader classLoader) {
        if (factoryClassName == null) {
            throw new FactoryConfigurationError("factoryClassName == null");
        }
        if (classLoader == null) {
            classLoader = Thread.currentThread().getContextClassLoader();
        }
        try {
            Class type = classLoader != null
                    ? classLoader.loadClass(factoryClassName)
                    : Class.forName(factoryClassName);
            return (DocumentBuilderFactory) type.newInstance();
        } catch (ClassNotFoundException e) {
            throw new FactoryConfigurationError(e);
        } catch (InstantiationException e) {
            throw new FactoryConfigurationError(e);
        } catch (IllegalAccessException e) {
            throw new FactoryConfigurationError(e);
        }
    }

    /**
     * Creates a new instance of a {@link javax.xml.parsers.DocumentBuilder}
     * using the currently configured parameters.
     *
     * @exception ParserConfigurationException if a DocumentBuilder
     * cannot be created which satisfies the configuration requested.
     * @return A new instance of a DocumentBuilder.
     */

    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
     * to false
     *
     * @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 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 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 to 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 false * .

* * @param ignoreComments 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. * @exception 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. * @exception 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 and DocumentBuilders created by this factory.

* *

* Feature names are fully qualified {@link java.net.URI}s. * Implementations may define their own features. * An {@link ParserConfigurationException} is thrown if this DocumentBuilderFactory or the * DocumentBuilders it creates cannot support the feature. * It is possible for an DocumentBuilderFactory 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:

*
    *
  • * 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 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. *
  • *
* * @param name Feature name. * @param value Is feature state true or false. * * @throws ParserConfigurationException if this DocumentBuilderFactory or the DocumentBuilders * it creates cannot support this feature. * @throws NullPointerException If the name 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 DocumentBuilderFactory or the * DocumentBuilders it creates cannot support the feature. * It is possible for an DocumentBuilderFactory to expose a feature value but be unable to change its state. *

* * @param name Feature name. * * @return State of the named feature. * * @throws ParserConfigurationException if this DocumentBuilderFactory * or the DocumentBuilders it creates cannot support this feature. */ public abstract boolean getFeature(String name) throws ParserConfigurationException; /** * 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 DocumentBuilderFactory} * 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 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. * *

* Initially, 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 {@link Schema} object. * Such configuration will cause a {@link ParserConfigurationException} * exception when the {@link #newDocumentBuilder()} is invoked.

* * *

Note for implementors

*

* 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 or 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() + "\"" ); } }




© 2015 - 2024 Weber Informatics LLC | Privacy Policy