1 /*
2 * Copyright 2000-2006 Sun Microsystems, Inc. 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. Sun designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
22 * CA 95054 USA or visit www.sun.com if you need additional information or
23 * have any 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 */
61
62 public abstract class DocumentBuilder {
63
64
65 /** Protected constructor */
66 protected DocumentBuilder () {
67 }
68
69 /**
70 * <p>Reset this <code>DocumentBuilder</code> to its original configuration.</p>
71 *
72 * <p><code>DocumentBuilder</code> is reset to the same state as when it was created with
73 * {@link DocumentBuilderFactory#newDocumentBuilder()}.
74 * <code>reset()</code> is designed to allow the reuse of existing <code>DocumentBuilder</code>s
75 * thus saving resources associated with the creation of new <code>DocumentBuilder</code>s.</p>
76 *
77 * <p>The reset <code>DocumentBuilder</code> is not guaranteed to have the same {@link EntityResolver} or {@link ErrorHandler}
78 * <code>Object</code>s, e.g. {@link Object#equals(Object obj)}. It is guaranteed to have a functionally equal
79 * <code>EntityResolver</code> and <code>ErrorHandler</code>.</p>
80 *
81 * @throws UnsupportedOperationException When implementation does not
82 * override this method.
83 *
84 * @since 1.5
85 */
86 public void reset() {
87
88 // implementors should override this method
89 throw new UnsupportedOperationException(
90 "This DocumentBuilder, \"" + this.getClass().getName() + "\", does not support the reset functionality."
91 + " Specification \"" + this.getClass().getPackage().getSpecificationTitle() + "\""
92 + " version \"" + this.getClass().getPackage().getSpecificationVersion() + "\""
93 );
94 }
95
96 /**
97 * Parse the content of the given <code>InputStream</code> as an XML
98 * document and return a new DOM {@link Document} object.
99 * An <code>IllegalArgumentException</code> is thrown if the
100 * <code>InputStream</code> is null.
101 *
102 * @param is InputStream containing the content to be parsed.
103 *
104 * @return <code>Document</code> result of parsing the
105 * <code>InputStream</code>
106 *
107 * @throws IOException If any IO errors occur.
108 * @throws SAXException If any parse errors occur.
109 * @throws IllegalArgumentException When <code>is</code> is <code>null</code>
110 *
111 * @see org.xml.sax.DocumentHandler
112 */
113
114 public Document parse(InputStream is)
115 throws SAXException, IOException {
116 if (is == null) {
117 throw new IllegalArgumentException("InputStream cannot be null");
118 }
119
120 InputSource in = new InputSource(is);
121 return parse(in);
122 }
123
124 /**
125 * Parse the content of the given <code>InputStream</code> as an
126 * XML document and return a new DOM {@link Document} object.
127 * An <code>IllegalArgumentException</code> is thrown if the
128 * <code>InputStream</code> is null.
129 *
130 * @param is InputStream containing the content to be parsed.
131 * @param systemId Provide a base for resolving relative URIs.
132 *
133 * @return A new DOM Document object.
134 *
135 * @throws IOException If any IO errors occur.
136 * @throws SAXException If any parse errors occur.
137 * @throws IllegalArgumentException When <code>is</code> is <code>null</code>
138 *
139 * @see org.xml.sax.DocumentHandler
140 */
141
142 public Document parse(InputStream is, String systemId)
143 throws SAXException, IOException {
144 if (is == null) {
145 throw new IllegalArgumentException("InputStream cannot be null");
146 }
147
148 InputSource in = new InputSource(is);
149 in.setSystemId(systemId);
150 return parse(in);
151 }
152
153 /**
154 * Parse the content of the given URI as an XML document
155 * and return a new DOM {@link Document} object.
156 * An <code>IllegalArgumentException</code> is thrown if the
157 * URI is <code>null</code> null.
158 *
159 * @param uri The location of the content to be parsed.
160 *
161 * @return A new DOM Document object.
162 *
163 * @throws IOException If any IO errors occur.
164 * @throws SAXException If any parse errors occur.
165 * @throws IllegalArgumentException When <code>uri</code> is <code>null</code>
166 *
167 * @see org.xml.sax.DocumentHandler
168 */
169
170 public Document parse(String uri)
171 throws SAXException, IOException {
172 if (uri == null) {
173 throw new IllegalArgumentException("URI cannot be null");
174 }
175
176 InputSource in = new InputSource(uri);
177 return parse(in);
178 }
179
180 /**
181 * Parse the content of the given file as an XML document
182 * and return a new DOM {@link Document} object.
183 * An <code>IllegalArgumentException</code> is thrown if the
184 * <code>File</code> is <code>null</code> null.
185 *
186 * @param f The file containing the XML to parse.
187 *
188 * @throws IOException If any IO errors occur.
189 * @throws SAXException If any parse errors occur.
190 * @throws IllegalArgumentException When <code>f</code> is <code>null</code>
191 *
192 * @see org.xml.sax.DocumentHandler
193 * @return A new DOM Document object.
194 */
195
196 public Document parse(File f) throws SAXException, IOException {
197 if (f == null) {
198 throw new IllegalArgumentException("File cannot be null");
199 }
200
201 //convert file to appropriate URI, f.toURI().toASCIIString()
202 //converts the URI to string as per rule specified in
203 //RFC 2396,
204 InputSource in = new InputSource(f.toURI().toASCIIString());
205 return parse(in);
206 }
207
208 /**
209 * Parse the content of the given input source as an XML document
210 * and return a new DOM {@link Document} object.
211 * An <code>IllegalArgumentException</code> is thrown if the
212 * <code>InputSource</code> is <code>null</code> null.
213 *
214 * @param is InputSource containing the content to be parsed.
215 *
216 * @return A new DOM Document object.
217 *
218 * @throws IOException If any IO errors occur.
219 * @throws SAXException If any parse errors occur.
220 * @throws IllegalArgumentException When <code>is</code> is <code>null</code>
221 *
222 * @see org.xml.sax.DocumentHandler
223 */
224
225 public abstract Document parse(InputSource is)
226 throws SAXException, IOException;
227
228
229 /**
230 * Indicates whether or not this parser is configured to
231 * understand namespaces.
232 *
233 * @return true if this parser is configured to understand
234 * namespaces; false otherwise.
235 */
236
237 public abstract boolean isNamespaceAware();
238
239 /**
240 * Indicates whether or not this parser is configured to
241 * validate XML documents.
242 *
243 * @return true if this parser is configured to validate
244 * XML documents; false otherwise.
245 */
246
247 public abstract boolean isValidating();
248
249 /**
250 * Specify the {@link EntityResolver} to be used to resolve
251 * entities present in the XML document to be parsed. Setting
252 * this to <code>null</code> will result in the underlying
253 * implementation using it's own default implementation and
254 * behavior.
255 *
256 * @param er The <code>EntityResolver</code> to be used to resolve entities
257 * present in the XML document to be parsed.
258 */
259
260 public abstract void setEntityResolver(EntityResolver er);
261
262 /**
263 * Specify the {@link ErrorHandler} to be used by the parser.
264 * Setting this to <code>null</code> will result in the underlying
265 * implementation using it's own default implementation and
266 * behavior.
267 *
268 * @param eh The <code>ErrorHandler</code> to be used by the parser.
269 */
270
271 public abstract void setErrorHandler(ErrorHandler eh);
272
273 /**
274 * Obtain a new instance of a DOM {@link Document} object
275 * to build a DOM tree with.
276 *
277 * @return A new instance of a DOM Document object.
278 */
279
280 public abstract Document newDocument();
281
282 /**
283 * Obtain an instance of a {@link DOMImplementation} object.
284 *
285 * @return A new instance of a <code>DOMImplementation</code>.
286 */
287
288 public abstract DOMImplementation getDOMImplementation();
289
290 /** <p>Get current state of canonicalization.</p>
291 *
292 * @return current state canonicalization control
293 */
294 /*
295 public boolean getCanonicalization() {
296 return canonicalState;
297 }
298 */
299
300 /** <p>Get a reference to the the {@link Schema} being used by
301 * the XML processor.</p>
302 *
303 * <p>If no schema is being used, <code>null</code> is returned.</p>
304 *
305 * @return {@link Schema} being used or <code>null</code>
306 * if none in use
307 *
308 * @throws UnsupportedOperationException When implementation does not
309 * override this method
310 *
311 * @since 1.5
312 */
313 public Schema getSchema() {
314 throw new UnsupportedOperationException(
315 "This parser does not support specification \""
316 + this.getClass().getPackage().getSpecificationTitle()
317 + "\" version \""
318 + this.getClass().getPackage().getSpecificationVersion()
319 + "\""
320 );
321 }
322
323
324 /**
325 * <p>Get the XInclude processing mode for this parser.</p>
326 *
327 * @return
328 * the return value of
329 * the {@link DocumentBuilderFactory#isXIncludeAware()}
330 * when this parser was created from factory.
331 *
332 * @throws UnsupportedOperationException When implementation does not
333 * override this method
334 *
335 * @since 1.5
336 *
337 * @see DocumentBuilderFactory#setXIncludeAware(boolean)
338 */
339 public boolean isXIncludeAware() {
340 throw new UnsupportedOperationException(
341 "This parser does not support specification \""
342 + this.getClass().getPackage().getSpecificationTitle()
343 + "\" version \""
344 + this.getClass().getPackage().getSpecificationVersion()
345 + "\""
346 );
347 }
348 }
Save This Page