1 /*
2 * Copyright (c) 2000, 2006, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package javax.xml.parsers;
27
28 import java.io.File;
29 import java.io.IOException;
30 import java.io.InputStream;
31
32 import javax.xml.validation.Schema;
33
34 import org.w3c.dom.Document;
35 import org.w3c.dom.DOMImplementation;
36
37 import org.xml.sax.EntityResolver;
38 import org.xml.sax.ErrorHandler;
39 import org.xml.sax.InputSource;
40 import org.xml.sax.SAXException;
41
42 /**
43 * Defines the API to obtain DOM Document instances from an XML
44 * document. Using this class, an application programmer can obtain a
45 * {@link Document} from XML.<p>
46 *
47 * An instance of this class can be obtained from the
48 * {@link DocumentBuilderFactory#newDocumentBuilder()} method. Once
49 * an instance of this class is obtained, XML can be parsed from a
50 * variety of input sources. These input sources are InputStreams,
51 * Files, URLs, and SAX InputSources.<p>
52 *
53 * Note that this class reuses several classes from the SAX API. This
54 * does not require that the implementor of the underlying DOM
55 * implementation use a SAX parser to parse XML document into a
56 * <code>Document</code>. It merely requires that the implementation
57 * communicate with the application using these existing APIs.
58 *
59 * @author <a href="mailto:Jeff.Suttor@Sun.com">Jeff Suttor</a>
60 * @since 1.4
61 */
62
63 public abstract class DocumentBuilder {
64
65
66 /** Protected constructor */
67 protected DocumentBuilder () {
68 }
69
70 /**
71 * <p>Reset this <code>DocumentBuilder</code> to its original configuration.</p>
72 *
73 * <p><code>DocumentBuilder</code> is reset to the same state as when it was created with
74 * {@link DocumentBuilderFactory#newDocumentBuilder()}.
75 * <code>reset()</code> is designed to allow the reuse of existing <code>DocumentBuilder</code>s
76 * thus saving resources associated with the creation of new <code>DocumentBuilder</code>s.</p>
77 *
78 * <p>The reset <code>DocumentBuilder</code> is not guaranteed to have the same {@link EntityResolver} or {@link ErrorHandler}
79 * <code>Object</code>s, e.g. {@link Object#equals(Object obj)}. It is guaranteed to have a functionally equal
80 * <code>EntityResolver</code> and <code>ErrorHandler</code>.</p>
81 *
82 * @throws UnsupportedOperationException When implementation does not
83 * override this method.
84 *
85 * @since 1.5
86 */
87 public void reset() {
88
89 // implementors should override this method
90 throw new UnsupportedOperationException(
91 "This DocumentBuilder, \"" + this.getClass().getName() + "\", does not support the reset functionality."
92 + " Specification \"" + this.getClass().getPackage().getSpecificationTitle() + "\""
93 + " version \"" + this.getClass().getPackage().getSpecificationVersion() + "\""
94 );
95 }
96
97 /**
98 * Parse the content of the given <code>InputStream</code> as an XML
99 * document and return a new DOM {@link Document} object.
100 * An <code>IllegalArgumentException</code> is thrown if the
101 * <code>InputStream</code> is null.
102 *
103 * @param is InputStream containing the content to be parsed.
104 *
105 * @return <code>Document</code> result of parsing the
106 * <code>InputStream</code>
107 *
108 * @throws IOException If any IO errors occur.
109 * @throws SAXException If any parse errors occur.
110 * @throws IllegalArgumentException When <code>is</code> is <code>null</code>
111 *
112 * @see org.xml.sax.DocumentHandler
113 */
114
115 public Document parse(InputStream is)
116 throws SAXException, IOException {
117 if (is == null) {
118 throw new IllegalArgumentException("InputStream cannot be null");
119 }
120
121 InputSource in = new InputSource(is);
122 return parse(in);
123 }
124
125 /**
126 * Parse the content of the given <code>InputStream</code> as an
127 * XML document and return a new DOM {@link Document} object.
128 * An <code>IllegalArgumentException</code> is thrown if the
129 * <code>InputStream</code> is null.
130 *
131 * @param is InputStream containing the content to be parsed.
132 * @param systemId Provide a base for resolving relative URIs.
133 *
134 * @return A new DOM Document object.
135 *
136 * @throws IOException If any IO errors occur.
137 * @throws SAXException If any parse errors occur.
138 * @throws IllegalArgumentException When <code>is</code> is <code>null</code>
139 *
140 * @see org.xml.sax.DocumentHandler
141 */
142
143 public Document parse(InputStream is, String systemId)
144 throws SAXException, IOException {
145 if (is == null) {
146 throw new IllegalArgumentException("InputStream cannot be null");
147 }
148
149 InputSource in = new InputSource(is);
150 in.setSystemId(systemId);
151 return parse(in);
152 }
153
154 /**
155 * Parse the content of the given URI as an XML document
156 * and return a new DOM {@link Document} object.
157 * An <code>IllegalArgumentException</code> is thrown if the
158 * URI is <code>null</code> null.
159 *
160 * @param uri The location of the content to be parsed.
161 *
162 * @return A new DOM Document object.
163 *
164 * @throws IOException If any IO errors occur.
165 * @throws SAXException If any parse errors occur.
166 * @throws IllegalArgumentException When <code>uri</code> is <code>null</code>
167 *
168 * @see org.xml.sax.DocumentHandler
169 */
170
171 public Document parse(String uri)
172 throws SAXException, IOException {
173 if (uri == null) {
174 throw new IllegalArgumentException("URI cannot be null");
175 }
176
177 InputSource in = new InputSource(uri);
178 return parse(in);
179 }
180
181 /**
182 * Parse the content of the given file as an XML document
183 * and return a new DOM {@link Document} object.
184 * An <code>IllegalArgumentException</code> is thrown if the
185 * <code>File</code> is <code>null</code> null.
186 *
187 * @param f The file containing the XML to parse.
188 *
189 * @throws IOException If any IO errors occur.
190 * @throws SAXException If any parse errors occur.
191 * @throws IllegalArgumentException When <code>f</code> is <code>null</code>
192 *
193 * @see org.xml.sax.DocumentHandler
194 * @return A new DOM Document object.
195 */
196
197 public Document parse(File f) throws SAXException, IOException {
198 if (f == null) {
199 throw new IllegalArgumentException("File cannot be null");
200 }
201
202 //convert file to appropriate URI, f.toURI().toASCIIString()
203 //converts the URI to string as per rule specified in
204 //RFC 2396,
205 InputSource in = new InputSource(f.toURI().toASCIIString());
206 return parse(in);
207 }
208
209 /**
210 * Parse the content of the given input source as an XML document
211 * and return a new DOM {@link Document} object.
212 * An <code>IllegalArgumentException</code> is thrown if the
213 * <code>InputSource</code> is <code>null</code> null.
214 *
215 * @param is InputSource containing the content to be parsed.
216 *
217 * @return A new DOM Document object.
218 *
219 * @throws IOException If any IO errors occur.
220 * @throws SAXException If any parse errors occur.
221 * @throws IllegalArgumentException When <code>is</code> is <code>null</code>
222 *
223 * @see org.xml.sax.DocumentHandler
224 */
225
226 public abstract Document parse(InputSource is)
227 throws SAXException, IOException;
228
229
230 /**
231 * Indicates whether or not this parser is configured to
232 * understand namespaces.
233 *
234 * @return true if this parser is configured to understand
235 * namespaces; false otherwise.
236 */
237
238 public abstract boolean isNamespaceAware();
239
240 /**
241 * Indicates whether or not this parser is configured to
242 * validate XML documents.
243 *
244 * @return true if this parser is configured to validate
245 * XML documents; false otherwise.
246 */
247
248 public abstract boolean isValidating();
249
250 /**
251 * Specify the {@link EntityResolver} to be used to resolve
252 * entities present in the XML document to be parsed. Setting
253 * this to <code>null</code> will result in the underlying
254 * implementation using it's own default implementation and
255 * behavior.
256 *
257 * @param er The <code>EntityResolver</code> to be used to resolve entities
258 * present in the XML document to be parsed.
259 */
260
261 public abstract void setEntityResolver(EntityResolver er);
262
263 /**
264 * Specify the {@link ErrorHandler} to be used by the parser.
265 * Setting this to <code>null</code> will result in the underlying
266 * implementation using it's own default implementation and
267 * behavior.
268 *
269 * @param eh The <code>ErrorHandler</code> to be used by the parser.
270 */
271
272 public abstract void setErrorHandler(ErrorHandler eh);
273
274 /**
275 * Obtain a new instance of a DOM {@link Document} object
276 * to build a DOM tree with.
277 *
278 * @return A new instance of a DOM Document object.
279 */
280
281 public abstract Document newDocument();
282
283 /**
284 * Obtain an instance of a {@link DOMImplementation} object.
285 *
286 * @return A new instance of a <code>DOMImplementation</code>.
287 */
288
289 public abstract DOMImplementation getDOMImplementation();
290
291 /** <p>Get current state of canonicalization.</p>
292 *
293 * @return current state canonicalization control
294 */
295 /*
296 public boolean getCanonicalization() {
297 return canonicalState;
298 }
299 */
300
301 /** <p>Get a reference to the the {@link Schema} being used by
302 * the XML processor.</p>
303 *
304 * <p>If no schema is being used, <code>null</code> is returned.</p>
305 *
306 * @return {@link Schema} being used or <code>null</code>
307 * if none in use
308 *
309 * @throws UnsupportedOperationException When implementation does not
310 * override this method
311 *
312 * @since 1.5
313 */
314 public Schema getSchema() {
315 throw new UnsupportedOperationException(
316 "This parser does not support specification \""
317 + this.getClass().getPackage().getSpecificationTitle()
318 + "\" version \""
319 + this.getClass().getPackage().getSpecificationVersion()
320 + "\""
321 );
322 }
323
324
325 /**
326 * <p>Get the XInclude processing mode for this parser.</p>
327 *
328 * @return
329 * the return value of
330 * the {@link DocumentBuilderFactory#isXIncludeAware()}
331 * when this parser was created from factory.
332 *
333 * @throws UnsupportedOperationException When implementation does not
334 * override this method
335 *
336 * @since 1.5
337 *
338 * @see DocumentBuilderFactory#setXIncludeAware(boolean)
339 */
340 public boolean isXIncludeAware() {
341 throw new UnsupportedOperationException(
342 "This parser does not support specification \""
343 + this.getClass().getPackage().getSpecificationTitle()
344 + "\" version \""
345 + this.getClass().getPackage().getSpecificationVersion()
346 + "\""
347 );
348 }
349 }