1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements. See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17
18 // $Id: DocumentBuilder.java 584483 2007-10-14 02:54:48Z mrglavas $
19
20 package javax.xml.parsers;
21
22 import java.io.File;
23 import java.io.IOException;
24 import java.io.InputStream;
25
26 import javax.xml.validation.Schema;
27
28 import org.w3c.dom.Document;
29 import org.w3c.dom.DOMImplementation;
30
31 import org.xml.sax.EntityResolver;
32 import org.xml.sax.ErrorHandler;
33 import org.xml.sax.InputSource;
34 import org.xml.sax.SAXException;
35
36 /**
37 * Defines the API to obtain DOM Document instances from an XML
38 * document. Using this class, an application programmer can obtain a
39 * {@link Document} from XML.<p>
40 *
41 * An instance of this class can be obtained from the
42 * {@link DocumentBuilderFactory#newDocumentBuilder()} method. Once
43 * an instance of this class is obtained, XML can be parsed from a
44 * variety of input sources. These input sources are InputStreams,
45 * Files, URLs, and SAX InputSources.<p>
46 *
47 * Note that this class reuses several classes from the SAX API. This
48 * does not require that the implementor of the underlying DOM
49 * implementation use a SAX parser to parse XML document into a
50 * <code>Document</code>. It merely requires that the implementation
51 * communicate with the application using these existing APIs.
52 *
53 * @author <a href="mailto:Jeff.Suttor@Sun.com">Jeff Suttor</a>
54 * @version $Revision: 584483 $, $Date: 2007-10-13 22:54:48 -0400 (Sat, 13 Oct 2007) $
55 */
56
57 public abstract class DocumentBuilder {
58
59 private static final boolean DEBUG = false;
60
61 /** Protected constructor */
62 protected DocumentBuilder () {
63 }
64
65 /**
66 * <p>Reset this <code>DocumentBuilder</code> to its original configuration.</p>
67 *
68 * <p><code>DocumentBuilder</code> is reset to the same state as when it was created with
69 * {@link DocumentBuilderFactory#newDocumentBuilder()}.
70 * <code>reset()</code> is designed to allow the reuse of existing <code>DocumentBuilder</code>s
71 * thus saving resources associated with the creation of new <code>DocumentBuilder</code>s.</p>
72 *
73 * <p>The reset <code>DocumentBuilder</code> is not guaranteed to have the same {@link EntityResolver} or {@link ErrorHandler}
74 * <code>Object</code>s, e.g. {@link Object#equals(Object obj)}. It is guaranteed to have a functionally equal
75 * <code>EntityResolver</code> and <code>ErrorHandler</code>.</p>
76 *
77 * @since 1.5
78 */
79 public void reset() {
80
81 // implementors should override this method
82 throw new UnsupportedOperationException(
83 "This DocumentBuilder, \"" + this.getClass().getName() + "\", does not support the reset functionality."
84 + " Specification \"" + this.getClass().getPackage().getSpecificationTitle() + "\""
85 + " version \"" + this.getClass().getPackage().getSpecificationVersion() + "\""
86 );
87 }
88
89 /**
90 * Parse the content of the given <code>InputStream</code> as an XML
91 * document and return a new DOM {@link Document} object.
92 * An <code>IllegalArgumentException</code> is thrown if the
93 * <code>InputStream</code> is null.
94 *
95 * @param is InputStream containing the content to be parsed.
96 * @return <code>Document</code> result of parsing the
97 * <code>InputStream</code>
98 * @exception IOException If any IO errors occur.
99 * @exception SAXException If any parse errors occur.
100 * @see org.xml.sax.DocumentHandler
101 */
102
103 public Document parse(InputStream is)
104 throws SAXException, IOException {
105 if (is == null) {
106 throw new IllegalArgumentException("InputStream cannot be null");
107 }
108
109 InputSource in = new InputSource(is);
110 return parse(in);
111 }
112
113 /**
114 * Parse the content of the given <code>InputStream</code> as an
115 * XML document and return a new DOM {@link Document} object.
116 * An <code>IllegalArgumentException</code> is thrown if the
117 * <code>InputStream</code> is null.
118 *
119 * @param is InputStream containing the content to be parsed.
120 * @param systemId Provide a base for resolving relative URIs.
121 * @return A new DOM Document object.
122 * @exception IOException If any IO errors occur.
123 * @exception SAXException If any parse errors occur.
124 * @see org.xml.sax.DocumentHandler
125 */
126
127 public Document parse(InputStream is, String systemId)
128 throws SAXException, IOException {
129 if (is == null) {
130 throw new IllegalArgumentException("InputStream cannot be null");
131 }
132
133 InputSource in = new InputSource(is);
134 in.setSystemId(systemId);
135 return parse(in);
136 }
137
138 /**
139 * Parse the content of the given URI as an XML document
140 * and return a new DOM {@link Document} object.
141 * An <code>IllegalArgumentException</code> is thrown if the
142 * URI is <code>null</code> null.
143 *
144 * @param uri The location of the content to be parsed.
145 * @return A new DOM Document object.
146 * @exception IOException If any IO errors occur.
147 * @exception SAXException If any parse errors occur.
148 * @see org.xml.sax.DocumentHandler
149 */
150
151 public Document parse(String uri)
152 throws SAXException, IOException {
153 if (uri == null) {
154 throw new IllegalArgumentException("URI cannot be null");
155 }
156
157 InputSource in = new InputSource(uri);
158 return parse(in);
159 }
160
161 /**
162 * Parse the content of the given file as an XML document
163 * and return a new DOM {@link Document} object.
164 * An <code>IllegalArgumentException</code> is thrown if the
165 * <code>File</code> is <code>null</code> null.
166 *
167 * @param f The file containing the XML to parse.
168 * @exception IOException If any IO errors occur.
169 * @exception SAXException If any parse errors occur.
170 * @see org.xml.sax.DocumentHandler
171 * @return A new DOM Document object.
172 */
173
174 public Document parse(File f) throws SAXException, IOException {
175 if (f == null) {
176 throw new IllegalArgumentException("File cannot be null");
177 }
178
179 String escapedURI = FilePathToURI.filepath2URI(f.getAbsolutePath());
180
181 if (DEBUG) {
182 System.out.println("Escaped URI = " + escapedURI);
183 }
184
185 InputSource in = new InputSource(escapedURI);
186 return parse(in);
187 }
188
189 /**
190 * Parse the content of the given input source as an XML document
191 * and return a new DOM {@link Document} object.
192 * An <code>IllegalArgumentException</code> is thrown if the
193 * <code>InputSource</code> is <code>null</code> null.
194 *
195 * @param is InputSource containing the content to be parsed.
196 * @exception IOException If any IO errors occur.
197 * @exception SAXException If any parse errors occur.
198 * @see org.xml.sax.DocumentHandler
199 * @return A new DOM Document object.
200 */
201
202 public abstract Document parse(InputSource is)
203 throws SAXException, IOException;
204
205
206 /**
207 * Indicates whether or not this parser is configured to
208 * understand namespaces.
209 *
210 * @return true if this parser is configured to understand
211 * namespaces; false otherwise.
212 */
213
214 public abstract boolean isNamespaceAware();
215
216 /**
217 * Indicates whether or not this parser is configured to
218 * validate XML documents.
219 *
220 * @return true if this parser is configured to validate
221 * XML documents; false otherwise.
222 */
223
224 public abstract boolean isValidating();
225
226 /**
227 * Specify the {@link EntityResolver} to be used to resolve
228 * entities present in the XML document to be parsed. Setting
229 * this to <code>null</code> will result in the underlying
230 * implementation using it's own default implementation and
231 * behavior.
232 *
233 * @param er The <code>EntityResolver</code> to be used to resolve entities
234 * present in the XML document to be parsed.
235 */
236
237 public abstract void setEntityResolver(EntityResolver er);
238
239 /**
240 * Specify the {@link ErrorHandler} to be used by the parser.
241 * Setting this to <code>null</code> will result in the underlying
242 * implementation using it's own default implementation and
243 * behavior.
244 *
245 * @param eh The <code>ErrorHandler</code> to be used by the parser.
246 */
247
248 public abstract void setErrorHandler(ErrorHandler eh);
249
250 /**
251 * Obtain a new instance of a DOM {@link Document} object
252 * to build a DOM tree with.
253 *
254 * @return A new instance of a DOM Document object.
255 */
256
257 public abstract Document newDocument();
258
259 /**
260 * Obtain an instance of a {@link DOMImplementation} object.
261 *
262 * @return A new instance of a <code>DOMImplementation</code>.
263 */
264
265 public abstract DOMImplementation getDOMImplementation();
266
267 /** <p>Get a reference to the the {@link Schema} being used by
268 * the XML processor.</p>
269 *
270 * <p>If no schema is being used, <code>null</code> is returned.</p>
271 *
272 * @return {@link Schema} being used or <code>null</code>
273 * if none in use
274 *
275 * @throws UnsupportedOperationException
276 * For backward compatibility, when implementations for
277 * earlier versions of JAXP is used, this exception will be
278 * thrown.
279 *
280 * @since 1.5
281 */
282 public Schema getSchema() {
283 throw new UnsupportedOperationException(
284 "This parser does not support specification \""
285 + this.getClass().getPackage().getSpecificationTitle()
286 + "\" version \""
287 + this.getClass().getPackage().getSpecificationVersion()
288 + "\""
289 );
290 }
291
292
293 /**
294 * <p>Get the XInclude processing mode for this parser.</p>
295 *
296 * @return
297 * the return value of
298 * the {@link DocumentBuilderFactory#isXIncludeAware()}
299 * when this parser was created from factory.
300 *
301 * @throws UnsupportedOperationException
302 * For backward compatibility, when implementations for
303 * earlier versions of JAXP is used, this exception will be
304 * thrown.
305 *
306 * @since 1.5
307 *
308 * @see DocumentBuilderFactory#setXIncludeAware(boolean)
309 */
310 public boolean isXIncludeAware() {
311 throw new UnsupportedOperationException(
312 "This parser does not support specification \""
313 + this.getClass().getPackage().getSpecificationTitle()
314 + "\" version \""
315 + this.getClass().getPackage().getSpecificationVersion()
316 + "\""
317 );
318 }
319 }