001: /**
002: * $Id: DocumentBuilderFactory.java,v 1.2 2002/05/08 19:44:06 yuvalo Exp $
003: *
004: * Copyright (c) 1998-2000 Sun Microsystems, Inc. All Rights Reserved.
005: *
006: * This software is the confidential and proprietary information of Sun
007: * Microsystems, Inc. ("Confidential Information"). You shall not
008: * disclose such Confidential Information and shall use it only in
009: * accordance with the terms of the license agreement you entered into
010: * with Sun.
011: *
012: * SUN MAKES NO REPRESENTATIONS OR WARRANTIES ABOUT THE SUITABILITY OF THE
013: * SOFTWARE, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
014: * IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
015: * PURPOSE, OR NON-INFRINGEMENT. SUN SHALL NOT BE LIABLE FOR ANY DAMAGES
016: * SUFFERED BY LICENSEE AS A RESULT OF USING, MODIFYING OR DISTRIBUTING
017: * THIS SOFTWARE OR ITS DERIVATIVES.
018: */package javax.xml.parsers;
019:
020: import java.io.InputStream;
021: import java.io.IOException;
022: import java.io.File;
023: import java.io.FileInputStream;
024:
025: import java.util.Properties;
026: import java.io.BufferedReader;
027: import java.io.InputStreamReader;
028:
029: /**
030: * Defines a factory API that enables applications to obtain a
031: * parser that produces DOM object trees from XML documents.
032: *
033: * An implementation of the <code>DocumentBuilderFactory</code> class is
034: * <em>NOT</em> guaranteed to be thread safe. It is up to the user application
035: * to make sure about the use of the <code>DocumentBuilderFactory</code> from
036: * more than one thread. Alternatively the application can have one instance
037: * of the <code>DocumentBuilderFactory</code> per thread.
038: * An application can use the same instance of the factory to obtain one or
039: * more instances of the <code>DocumentBuilder</code> provided the instance
040: * of the factory isn't being used in more than one thread at a time.
041: *
042: * @since JAXP 1.0
043: * @version 1.0
044: */
045:
046: public abstract class DocumentBuilderFactory {
047: private boolean validating = false;
048: private boolean namespaceAware = false;
049: private boolean whitespace = false;
050: private boolean expandEntityRef = true;
051: private boolean ignoreComments = false;
052: private boolean coalescing = false;
053:
054: protected DocumentBuilderFactory() {
055:
056: }
057:
058: /**
059: * Obtain a new instance of a
060: * <code>DocumentBuilderFactory</code>. This static method creates
061: * a new factory instance.
062: * This method uses the following ordered lookup procedure to determine
063: * the <code>DocumentBuilderFactory</code> implementation class to
064: * load:
065: * <ul>
066: * <li>
067: * Use the <code>javax.xml.parsers.DocumentBuilderFactory</code> system
068: * property.
069: * </li>
070: * <li>
071: * Use the properties file "lib/jaxp.properties" in the JRE directory.
072: * This configuration file is in standard <code>java.util.Properties
073: * </code> format and contains the fully qualified name of the
074: * implementation class with the key being the system property defined
075: * above.
076: * </li>
077: * <li>
078: * Use the Services API (as detailed in the JAR specification), if
079: * available, to determine the classname. The Services API will look
080: * for a classname in the file
081: * <code>META-INF/services/javax.xml.parsers.DocumentBuilderFactory</code>
082: * in jars available to the runtime.
083: * </li>
084: * <li>
085: * Platform default <code>DocumentBuilderFactory</code> instance.
086: * </li>
087: * </ul>
088: *
089: * Once an application has obtained a reference to a
090: * <code>DocumentBuilderFactory</code> it can use the factory to
091: * configure and obtain parser instances.
092: *
093: * @exception FactoryConfigurationError if the implementation is not
094: * available or cannot be instantiated.
095: */
096:
097: public static DocumentBuilderFactory newInstance()
098: throws FactoryConfigurationError {
099: try {
100: return (DocumentBuilderFactory) FactoryFinder.find(
101: /* The default property name according to the JAXP spec */
102: "javax.xml.parsers.DocumentBuilderFactory",
103: /* The fallback implementation class name */
104: "org.apache.crimson.jaxp.DocumentBuilderFactoryImpl");
105: } catch (FactoryFinder.ConfigurationError e) {
106: throw new FactoryConfigurationError(e.getException(), e
107: .getMessage());
108: }
109: }
110:
111: /**
112: * Creates a new instance of a {@link javax.xml.parsers.DocumentBuilder}
113: * using the currently configured parameters.
114: *
115: * @exception ParserConfigurationException if a DocumentBuilder
116: * cannot be created which satisfies the configuration requested.
117: * @return A new instance of a DocumentBuilder.
118: */
119:
120: public abstract DocumentBuilder newDocumentBuilder()
121: throws ParserConfigurationException;
122:
123: /**
124: * Specifies that the parser produced by this code will
125: * provide support for XML namespaces. By default the value of this is set
126: * to <code>false</code>
127: *
128: * @param awareness true if the parser produced will provide support
129: * for XML namespaces; false otherwise.
130: */
131:
132: public void setNamespaceAware(boolean awareness) {
133: this .namespaceAware = awareness;
134: }
135:
136: /**
137: * Specifies that the parser produced by this code will
138: * validate documents as they are parsed. By default the value of this
139: * is set to <code>false</code>.
140: *
141: * @param validating true if the parser produced will validate documents
142: * as they are parsed; false otherwise.
143: */
144:
145: public void setValidating(boolean validating) {
146: this .validating = validating;
147: }
148:
149: /**
150: * Specifies that the parsers created by this factory must eliminate
151: * whitespace in element content (sometimes known loosely as
152: * 'ignorable whitespace') when parsing XML documents (see XML Rec
153: * 2.10). Note that only whitespace which is directly contained within
154: * element content that has an element only content model (see XML
155: * Rec 3.2.1) will be eliminated. Due to reliance on the content model
156: * this setting requires the parser to be in validating mode. By default
157: * the value of this is set to <code>false</code>.
158: *
159: * @param whitespace true if the parser created must eliminate whitespace
160: * in the element content when parsing XML documents;
161: * false otherwise.
162: */
163:
164: public void setIgnoringElementContentWhitespace(boolean whitespace) {
165: this .whitespace = whitespace;
166: }
167:
168: /**
169: * Specifies that the parser produced by this code will
170: * expand entity reference nodes. By default the value of this is set to
171: * <code>true</code>
172: *
173: * @param expandEntityRef true if the parser produced will expand entity
174: * reference nodes; false otherwise.
175: */
176:
177: public void setExpandEntityReferences(boolean expandEntityRef) {
178: this .expandEntityRef = expandEntityRef;
179: }
180:
181: /**
182: * Specifies that the parser produced by this code will
183: * ignore comments. By default the value of this is set to <code>false
184: * </code>
185: */
186:
187: public void setIgnoringComments(boolean ignoreComments) {
188: this .ignoreComments = ignoreComments;
189: }
190:
191: /**
192: * Specifies that the parser produced by this code will
193: * convert CDATA nodes to Text nodes and append it to the
194: * adjacent (if any) text node. By default the value of this is set to
195: * <code>false</code>
196: *
197: * @param coalescing true if the parser produced will convert CDATA nodes
198: * to Text nodes and append it to the adjacent (if any)
199: * text node; false otherwise.
200: */
201:
202: public void setCoalescing(boolean coalescing) {
203: this .coalescing = coalescing;
204: }
205:
206: /**
207: * Indicates whether or not the factory is configured to produce
208: * parsers which are namespace aware.
209: *
210: * @return true if the factory is configured to produce parsers which
211: * are namespace aware; false otherwise.
212: */
213:
214: public boolean isNamespaceAware() {
215: return namespaceAware;
216: }
217:
218: /**
219: * Indicates whether or not the factory is configured to produce
220: * parsers which validate the XML content during parse.
221: *
222: * @return true if the factory is configured to produce parsers
223: * which validate the XML content during parse; false otherwise.
224: */
225:
226: public boolean isValidating() {
227: return validating;
228: }
229:
230: /**
231: * Indicates whether or not the factory is configured to produce
232: * parsers which ignore ignorable whitespace in element content.
233: *
234: * @return true if the factory is configured to produce parsers
235: * which ignore ignorable whitespace in element content;
236: * false otherwise.
237: */
238:
239: public boolean isIgnoringElementContentWhitespace() {
240: return whitespace;
241: }
242:
243: /**
244: * Indicates whether or not the factory is configured to produce
245: * parsers which expand entity reference nodes.
246: *
247: * @return true if the factory is configured to produce parsers
248: * which expand entity reference nodes; false otherwise.
249: */
250:
251: public boolean isExpandEntityReferences() {
252: return expandEntityRef;
253: }
254:
255: /**
256: * Indicates whether or not the factory is configured to produce
257: * parsers which ignores comments.
258: *
259: * @return true if the factory is configured to produce parsers
260: * which ignores comments; false otherwise.
261: */
262:
263: public boolean isIgnoringComments() {
264: return ignoreComments;
265: }
266:
267: /**
268: * Indicates whether or not the factory is configured to produce
269: * parsers which converts CDATA nodes to Text nodes and appends it to
270: * the adjacent (if any) Text node.
271: *
272: * @return true if the factory is configured to produce parsers
273: * which converts CDATA nodes to Text nodes and appends it to
274: * the adjacent (if any) Text node; false otherwise.
275: */
276:
277: public boolean isCoalescing() {
278: return coalescing;
279: }
280:
281: /**
282: * Allows the user to set specific attributes on the underlying
283: * implementation.
284: * @param name The name of the attribute.
285: * @param value The value of the attribute.
286: * @exception IllegalArgumentException thrown if the underlying
287: * implementation doesn't recognize the attribute.
288: */
289: public abstract void setAttribute(String name, Object value)
290: throws IllegalArgumentException;
291:
292: /**
293: * Allows the user to retrieve specific attributes on the underlying
294: * implementation.
295: * @param name The name of the attribute.
296: * @return value The value of the attribute.
297: * @exception IllegalArgumentException thrown if the underlying
298: * implementation doesn't recognize the attribute.
299: */
300: public abstract Object getAttribute(String name)
301: throws IllegalArgumentException;
302: }
|