2
* Copyright 2003-2005 The Apache Software Foundation.
4
* Licensed under the Apache License, Version 2.0 (the "License");
5
* you may not use this file except in compliance with the License.
6
* You may obtain a copy of the License at
8
* http://www.apache.org/licenses/LICENSE-2.0
10
* Unless required by applicable law or agreed to in writing, software
11
* distributed under the License is distributed on an "AS IS" BASIS,
12
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13
* See the License for the specific language governing permissions and
14
* limitations under the License.
17
// $Id: DocumentBuilder.java 226208 2005-06-03 18:28:57Z mrglavas $
19
package javax.xml.parsers;
22
import java.io.IOException;
23
import java.io.InputStream;
25
import javax.xml.validation.Schema;
27
import org.w3c.dom.Document;
28
import org.w3c.dom.DOMImplementation;
30
import org.xml.sax.EntityResolver;
31
import org.xml.sax.ErrorHandler;
32
import org.xml.sax.InputSource;
33
import org.xml.sax.SAXException;
36
* Defines the API to obtain DOM Document instances from an XML
37
* document. Using this class, an application programmer can obtain a
38
* {@link Document} from XML.<p>
40
* An instance of this class can be obtained from the
41
* {@link DocumentBuilderFactory#newDocumentBuilder()} method. Once
42
* an instance of this class is obtained, XML can be parsed from a
43
* variety of input sources. These input sources are InputStreams,
44
* Files, URLs, and SAX InputSources.<p>
46
* Note that this class reuses several classes from the SAX API. This
47
* does not require that the implementor of the underlying DOM
48
* implementation use a SAX parser to parse XML document into a
49
* <code>Document</code>. It merely requires that the implementation
50
* communicate with the application using these existing APIs.
52
* @author <a href="mailto:Jeff.Suttor@Sun.com">Jeff Suttor</a>
53
* @version $Revision: 226208 $, $Date: 2005-06-03 14:28:57 -0400 (Fri, 03 Jun 2005) $
56
public abstract class DocumentBuilder {
58
private static final boolean DEBUG = false;
60
/** Protected constructor */
61
protected DocumentBuilder () {
65
* <p>Reset this <code>DocumentBuilder</code> to its original configuration.</p>
67
* <p><code>DocumentBuilder</code> is reset to the same state as when it was created with
68
* {@link DocumentBuilderFactory#newDocumentBuilder()}.
69
* <code>reset()</code> is designed to allow the reuse of existing <code>DocumentBuilder</code>s
70
* thus saving resources associated with the creation of new <code>DocumentBuilder</code>s.</p>
72
* <p>The reset <code>DocumentBuilder</code> is not guaranteed to have the same {@link EntityResolver} or {@link ErrorHandler}
73
* <code>Object</code>s, e.g. {@link Object#equals(Object obj)}. It is guaranteed to have a functionally equal
74
* <code>EntityResolver</code> and <code>ErrorHandler</code>.</p>
80
// implementors should override this method
81
throw new UnsupportedOperationException(
82
"This DocumentBuilder, \"" + this.getClass().getName() + "\", does not support the reset functionality."
83
+ " Specification \"" + this.getClass().getPackage().getSpecificationTitle() + "\""
84
+ " version \"" + this.getClass().getPackage().getSpecificationVersion() + "\""
89
* Parse the content of the given <code>InputStream</code> as an XML
90
* document and return a new DOM {@link Document} object.
91
* An <code>IllegalArgumentException</code> is thrown if the
92
* <code>InputStream</code> is null.
94
* @param is InputStream containing the content to be parsed.
95
* @return <code>Document</code> result of parsing the
96
* <code>InputStream</code>
97
* @exception IOException If any IO errors occur.
98
* @exception SAXException If any parse errors occur.
99
* @see org.xml.sax.DocumentHandler
102
public Document parse(InputStream is)
103
throws SAXException, IOException {
105
throw new IllegalArgumentException("InputStream cannot be null");
108
InputSource in = new InputSource(is);
113
* Parse the content of the given <code>InputStream</code> as an
114
* XML document and return a new DOM {@link Document} object.
115
* An <code>IllegalArgumentException</code> is thrown if the
116
* <code>InputStream</code> is null.
118
* @param is InputStream containing the content to be parsed.
119
* @param systemId Provide a base for resolving relative URIs.
120
* @return A new DOM Document object.
121
* @exception IOException If any IO errors occur.
122
* @exception SAXException If any parse errors occur.
123
* @see org.xml.sax.DocumentHandler
126
public Document parse(InputStream is, String systemId)
127
throws SAXException, IOException {
129
throw new IllegalArgumentException("InputStream cannot be null");
132
InputSource in = new InputSource(is);
133
in.setSystemId(systemId);
138
* Parse the content of the given URI as an XML document
139
* and return a new DOM {@link Document} object.
140
* An <code>IllegalArgumentException</code> is thrown if the
141
* URI is <code>null</code> null.
143
* @param uri The location of the content to be parsed.
144
* @return A new DOM Document object.
145
* @exception IOException If any IO errors occur.
146
* @exception SAXException If any parse errors occur.
147
* @see org.xml.sax.DocumentHandler
150
public Document parse(String uri)
151
throws SAXException, IOException {
153
throw new IllegalArgumentException("URI cannot be null");
156
InputSource in = new InputSource(uri);
161
* Parse the content of the given file as an XML document
162
* and return a new DOM {@link Document} object.
163
* An <code>IllegalArgumentException</code> is thrown if the
164
* <code>File</code> is <code>null</code> null.
166
* @param f The file containing the XML to parse.
167
* @exception IOException If any IO errors occur.
168
* @exception SAXException If any parse errors occur.
169
* @see org.xml.sax.DocumentHandler
170
* @return A new DOM Document object.
173
public Document parse(File f) throws SAXException, IOException {
175
throw new IllegalArgumentException("File cannot be null");
178
String escapedURI = FilePathToURI.filepath2URI(f.getAbsolutePath());
181
System.out.println("Escaped URI = " + escapedURI);
184
InputSource in = new InputSource(escapedURI);
189
* Parse the content of the given input source as an XML document
190
* and return a new DOM {@link Document} object.
191
* An <code>IllegalArgumentException</code> is thrown if the
192
* <code>InputSource</code> is <code>null</code> null.
194
* @param is InputSource containing the content to be parsed.
195
* @exception IOException If any IO errors occur.
196
* @exception SAXException If any parse errors occur.
197
* @see org.xml.sax.DocumentHandler
198
* @return A new DOM Document object.
201
public abstract Document parse(InputSource is)
202
throws SAXException, IOException;
206
* Indicates whether or not this parser is configured to
207
* understand namespaces.
209
* @return true if this parser is configured to understand
210
* namespaces; false otherwise.
213
public abstract boolean isNamespaceAware();
216
* Indicates whether or not this parser is configured to
217
* validate XML documents.
219
* @return true if this parser is configured to validate
220
* XML documents; false otherwise.
223
public abstract boolean isValidating();
226
* Specify the {@link EntityResolver} to be used to resolve
227
* entities present in the XML document to be parsed. Setting
228
* this to <code>null</code> will result in the underlying
229
* implementation using it's own default implementation and
232
* @param er The <code>EntityResolver</code> to be used to resolve entities
233
* present in the XML document to be parsed.
236
public abstract void setEntityResolver(EntityResolver er);
239
* Specify the {@link ErrorHandler} to be used by the parser.
240
* Setting this to <code>null</code> will result in the underlying
241
* implementation using it's own default implementation and
244
* @param eh The <code>ErrorHandler</code> to be used by the parser.
247
public abstract void setErrorHandler(ErrorHandler eh);
250
* Obtain a new instance of a DOM {@link Document} object
251
* to build a DOM tree with.
253
* @return A new instance of a DOM Document object.
256
public abstract Document newDocument();
259
* Obtain an instance of a {@link DOMImplementation} object.
261
* @return A new instance of a <code>DOMImplementation</code>.
264
public abstract DOMImplementation getDOMImplementation();
266
/** <p>Get current state of canonicalization.</p>
268
* @return current state canonicalization control
271
public boolean getCanonicalization() {
272
return canonicalState;
276
/** <p>Get a reference to the the {@link Schema} being used by
277
* the XML processor.</p>
279
* <p>If no schema is being used, <code>null</code> is returned.</p>
281
* @return {@link Schema} being used or <code>null</code>
284
* @throws UnsupportedOperationException
285
* For backward compatibility, when implementations for
286
* earlier versions of JAXP is used, this exception will be
291
public Schema getSchema() {
292
throw new UnsupportedOperationException(
293
"This parser does not support specification \""
294
+ this.getClass().getPackage().getSpecificationTitle()
296
+ this.getClass().getPackage().getSpecificationVersion()
303
* <p>Get the XInclude processing mode for this parser.</p>
306
* the return value of
307
* the {@link DocumentBuilderFactory#isXIncludeAware()}
308
* when this parser was created from factory.
310
* @throws UnsupportedOperationException
311
* For backward compatibility, when implementations for
312
* earlier versions of JAXP is used, this exception will be
317
* @see DocumentBuilderFactory#setXIncludeAware(boolean)
319
public boolean isXIncludeAware() {
320
throw new UnsupportedOperationException(
321
"This parser does not support specification \""
322
+ this.getClass().getPackage().getSpecificationTitle()
324
+ this.getClass().getPackage().getSpecificationVersion()
added
removed
javax/xml/parsers/DocumentBuilder.java
