/*
* Copyright (C) 2007 The Android Open Source Project
*
* Licensed 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.
*/
package javax.xml.parsers;
import org.apache.harmony.xml.parsers.DocumentBuilderFactoryImpl;
/**
* Provides a factory for {@link DocumentBuilder} instances. The class first
* needs to be instantiated using the {@link #newInstance()} method. The
* instance can be configured as desired. A call to
* {@link #newDocumentBuilder()} then provides a {@code DocumentBuilder}
* instance matching this configuration (if possible).
*
* @since Android 1.0
*/
public abstract class DocumentBuilderFactory extends Object {
private boolean coalesce;
private boolean expandEntityReferences;
private boolean ignoreComments;
private boolean ignoreElementContentWhitespace;
private boolean namespaceAware;
private boolean validate;
/**
* Do-nothing constructor. To be overridden by concrete document builders.
*
* @since Android 1.0
*/
protected DocumentBuilderFactory() {
// Does nothing.
}
/**
* Queries an attribute from the underlying implementation.
*
* @param name the name of the attribute.
* @return the value of the attribute.
*
* @throws IllegalArgumentException if the argument is unknown to the
* underlying implementation.
*
* @since Android 1.0
*/
public abstract Object getAttribute(String name)
throws IllegalArgumentException;
/**
* Queries a feature from the underlying implementation.
*
* @param name The name of the feature. The default Android implementation
* of {@link DocumentBuilder} supports only the following three
* features:
*
* <dl>
* <dt>{@code http://xml.org/sax/features/namespaces}</dt>
* <dd>Queries the state of namespace-awareness.</dd>
*
* <dt>
* {@code http://xml.org/sax/features/namespace-prefixes}
* </dt>
* <dd>Queries the state of namespace prefix processing</dd>
*
* <dt>
* {@code http://xml.org/sax/features/validation}
* </dt>
* <dd>Queries the state of validation.</dd>
* </dl>
*
* Note that despite the ability to query the validation
* feature, there is currently no validating parser available.
* Also note that currently either namespaces or
* namespace prefixes can be enabled, but not both at the same
* time.
*
* @return the status of the feature.
*
* @throws IllegalArgumentException if the feature is unknown to
* the underlying implementation.
* @throws ParserConfigurationException if the feature is
* known, but not supported.
*
* @since Android 1.0
*/
public abstract boolean getFeature(String name)
throws ParserConfigurationException;
// TODO No XSchema support in Android 1.0. Maybe later.
// /**
// * Queries the desired XML Schema object.
// *
// * @return The XML Schema object, if it has been set by a call to setSchema,
// * or null otherwise.
// */
// public javax.xml.validation.Schema getSchema() {
// return schema;
// }
/**
* Queries whether the factory is configured to deliver parsers that convert
* CDATA nodes to text nodes and melt them with neighboring nodes. This is
* called "coalescing".
*
* @return {@code true} if coalescing is desired, {@code false} otherwise.
*
* @since Android 1.0
*/
public boolean isCoalescing() {
return coalesce;
}
/**
* Queries whether the factory is configured to deliver parsers that expand
* entity references.
*
* @return {@code true} if entity expansion is desired, {@code false}
* otherwise.
*
* @since Android 1.0
*/
public boolean isExpandEntityReferences() {
return expandEntityReferences;
}
/**
* Queries whether the factory is configured to deliver parsers that ignore
* comments.
*
* @return {@code true} if comment ignorance is desired, {@code false}
* otherwise.
*
* @since Android 1.0
*/
public boolean isIgnoringComments() {
return ignoreComments;
}
/**
* Queries whether the factory is configured to deliver parsers that ignore
* whitespace in elements.
*
* @return {@code true} if whitespace ignorance is desired, {@code false}
* otherwise.
*
* @since Android 1.0
*/
public boolean isIgnoringElementContentWhitespace() {
return ignoreElementContentWhitespace;
}
/**
* Queries whether the factory is configured to deliver parsers that are
* namespace-aware.
*
* @return {@code true} if namespace-awareness is desired, {@code false}
* otherwise.
*
* @since Android 1.0
*/
public boolean isNamespaceAware() {
return namespaceAware;
}
/**
* Queries whether the factory is configured to deliver parsers that are
* validating.
*
* @return {@code true} if validating is desired, {@code false} otherwise.
*
* @since Android 1.0
*/
public boolean isValidating() {
return validate;
}
/**
* Queries whether the factory is configured to deliver parsers that are
* XInclude-aware.
*
* @return {@code true} if XInclude-awareness is desired, {@code false}
* otherwise.
*
* @since Android 1.0
*/
public boolean isXIncludeAware() {
throw new UnsupportedOperationException();
}
/**
* Creates a new {@link DocumentBuilder} that matches the current
* configuration of the factory.
*
* @return the DocumentBuilder.
* @throws ParserConfigurationException if no matching
* {@code DocumentBuilder} could be found.
*
* @since Android 1.0
*/
public abstract DocumentBuilder newDocumentBuilder()
throws ParserConfigurationException;
/**
* Creates a new DocumentBuilderFactory that can be configured and then be
* used for creating DocumentBuilder objects. The method first checks the
* value of the {@code DocumentBuilderFactory} property.
* If this is non-{@code null}, it is assumed to be the name of a class
* that serves as the factory. The class is instantiated, and the instance
* is returned. If the property value is {@code null}, the system's default
* factory implementation is returned.
*
* @return the DocumentBuilderFactory.
* @throws FactoryConfigurationError if no {@code DocumentBuilderFactory}
* can be created.
*
* @since Android 1.0
*/
public static DocumentBuilderFactory newInstance()
throws FactoryConfigurationError {
// TODO Properties file and META-INF case missing here. See spec.
String factory = System
.getProperty("javax.xml.parsers.DocumentBuilderFactory");
if (factory != null) {
try {
return (DocumentBuilderFactory) Class.forName(factory)
.newInstance();
} catch (Exception ex) {
// Ignore.
}
}
try {
return new DocumentBuilderFactoryImpl();
} catch (Exception ex) {
// Ignore.
}
throw new FactoryConfigurationError(
"Cannot create DocumentBuilderFactory");
}
/**
* Sets an attribute in the underlying implementation.
*
* @param name the name of the attribute.
* @param value the value of the attribute.
*
* @throws IllegalArgumentException if the argument is unknown to the
* underlying implementation.
*
* @since Android 1.0
*/
public abstract void setAttribute(String name, Object value)
throws IllegalArgumentException;
/**
* Determines whether the factory is configured to deliver parsers that
* convert CDATA nodes to text nodes and melt them with neighboring nodes.
* This is called "coalescing".
*
* @param value turns coalescing on or off.
*
* @since Android 1.0
*/
public void setCoalescing(boolean value) {
coalesce = value;
}
/**
* Determines whether the factory is configured to deliver parsers that
* expands entity references.
*
* @param value turns entity reference expansion on or off.
*
* @since Android 1.0
*/
public void setExpandEntityReferences(boolean value) {
expandEntityReferences = value;
}
/**
* Sets a feature in the underlying implementation.
*
* @param name the name of the feature. The default Android implementation
* of {@link DocumentBuilder} supports only the following three
* features:
*
* <dl>
* <dt>{@code http://xml.org/sax/features/namespaces}</dt>
* <dd>Sets the state of namespace-awareness.</dd>
*
* <dt>
* {@code http://xml.org/sax/features/namespace-prefixes}
* </dt>
* <dd>Sets the state of namespace prefix processing</dd>
*
* <dt>{@code http://xml.org/sax/features/validation}</dt>
* <dd>Sets the state of validation.</dd>
* </dl>
*
* Note that despite the ability to set the validation
* feature, there is currently no validating parser available.
* Also note that currently either namespaces or
* namespace prefixes can be enabled, but not both at the same
* time.
*
* @param value the value of the feature.
*
* @throws ParserConfigurationException if the feature is unknown to the
* underlying implementation.
*
* @since Android 1.0
*/
public abstract void setFeature(String name, boolean value)
throws ParserConfigurationException;
/**
* Determines whether the factory is configured to deliver parsers that
* ignore comments.
*
* @param value turns comment ignorance on or off.
*
* @since Android 1.0
*/
public void setIgnoringComments(boolean value) {
ignoreComments = value;
}
/**
* Determines whether the factory is configured to deliver parsers that
* ignores element whitespace.
*
* @param value turns element whitespace ignorance on or off.
*
* @since Android 1.0
*/
public void setIgnoringElementContentWhitespace(boolean value) {
ignoreElementContentWhitespace = value;
}
/**
* Determines whether the factory is configured to deliver parsers that are
* namespace-aware.
*
* @param value turns namespace-awareness on or off.
*
* @since Android 1.0
*/
public void setNamespaceAware(boolean value) {
namespaceAware = value;
}
// TODO No XSchema support in Android 1.0. Maybe later.
// /**
// * Sets the desired XML Schema object.
// *
// * @param schema The XML Schema object.
// */
// public void setSchema(Schema schema) {
// this.schema = schema;
// }
/**
* Determines whether the factory is configured to deliver parsers that are
* validating.
*
* @param value turns validation on or off.
*
* @since Android 1.0
*/
public void setValidating(boolean value) {
validate = value;
}
/**
* Determines whether the factory is configured to deliver parsers that are
* XInclude-aware.
*
* @param value turns XInclude-awareness on or off.
*
* @since Android 1.0
*/
public void setXIncludeAware(boolean value) {
throw new UnsupportedOperationException();
}
}
|
