001 /*
002 * Copyright 2000-2006 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package javax.xml.parsers;
027
028 import java.io.File;
029 import java.io.IOException;
030 import java.io.InputStream;
031
032 import javax.xml.validation.Schema;
033
034 import org.w3c.dom.Document;
035 import org.w3c.dom.DOMImplementation;
036
037 import org.xml.sax.EntityResolver;
038 import org.xml.sax.ErrorHandler;
039 import org.xml.sax.InputSource;
040 import org.xml.sax.SAXException;
041
042 /**
043 * Defines the API to obtain DOM Document instances from an XML
044 * document. Using this class, an application programmer can obtain a
045 * {@link Document} from XML.<p>
046 *
047 * An instance of this class can be obtained from the
048 * {@link DocumentBuilderFactory#newDocumentBuilder()} method. Once
049 * an instance of this class is obtained, XML can be parsed from a
050 * variety of input sources. These input sources are InputStreams,
051 * Files, URLs, and SAX InputSources.<p>
052 *
053 * Note that this class reuses several classes from the SAX API. This
054 * does not require that the implementor of the underlying DOM
055 * implementation use a SAX parser to parse XML document into a
056 * <code>Document</code>. It merely requires that the implementation
057 * communicate with the application using these existing APIs.
058 *
059 * @author <a href="mailto:Jeff.Suttor@Sun.com">Jeff Suttor</a>
060 * @version $Revision: 1.5 $, $Date: 2005/11/21 05:57:14 $
061 */
062
063 public abstract class DocumentBuilder {
064
065 /** Protected constructor */
066 protected DocumentBuilder() {
067 }
068
069 /**
070 * <p>Reset this <code>DocumentBuilder</code> to its original configuration.</p>
071 *
072 * <p><code>DocumentBuilder</code> is reset to the same state as when it was created with
073 * {@link DocumentBuilderFactory#newDocumentBuilder()}.
074 * <code>reset()</code> is designed to allow the reuse of existing <code>DocumentBuilder</code>s
075 * thus saving resources associated with the creation of new <code>DocumentBuilder</code>s.</p>
076 *
077 * <p>The reset <code>DocumentBuilder</code> is not guaranteed to have the same {@link EntityResolver} or {@link ErrorHandler}
078 * <code>Object</code>s, e.g. {@link Object#equals(Object obj)}. It is guaranteed to have a functionally equal
079 * <code>EntityResolver</code> and <code>ErrorHandler</code>.</p>
080 *
081 * @throws UnsupportedOperationException When implementation does not
082 * override this method.
083 *
084 * @since 1.5
085 */
086 public void reset() {
087
088 // implementors should override this method
089 throw new UnsupportedOperationException(
090 "This DocumentBuilder, \""
091 + this .getClass().getName()
092 + "\", does not support the reset functionality."
093 + " Specification \""
094 + this .getClass().getPackage()
095 .getSpecificationTitle()
096 + "\""
097 + " version \""
098 + this .getClass().getPackage()
099 .getSpecificationVersion() + "\"");
100 }
101
102 /**
103 * Parse the content of the given <code>InputStream</code> as an XML
104 * document and return a new DOM {@link Document} object.
105 * An <code>IllegalArgumentException</code> is thrown if the
106 * <code>InputStream</code> is null.
107 *
108 * @param is InputStream containing the content to be parsed.
109 *
110 * @return <code>Document</code> result of parsing the
111 * <code>InputStream</code>
112 *
113 * @throws IOException If any IO errors occur.
114 * @throws SAXException If any parse errors occur.
115 * @throws IllegalArgumentException When <code>is</code> is <code>null</code>
116 *
117 * @see org.xml.sax.DocumentHandler
118 */
119
120 public Document parse(InputStream is) throws SAXException,
121 IOException {
122 if (is == null) {
123 throw new IllegalArgumentException(
124 "InputStream cannot be null");
125 }
126
127 InputSource in = new InputSource(is);
128 return parse(in);
129 }
130
131 /**
132 * Parse the content of the given <code>InputStream</code> as an
133 * XML document and return a new DOM {@link Document} object.
134 * An <code>IllegalArgumentException</code> is thrown if the
135 * <code>InputStream</code> is null.
136 *
137 * @param is InputStream containing the content to be parsed.
138 * @param systemId Provide a base for resolving relative URIs.
139 *
140 * @return A new DOM Document object.
141 *
142 * @throws IOException If any IO errors occur.
143 * @throws SAXException If any parse errors occur.
144 * @throws IllegalArgumentException When <code>is</code> is <code>null</code>
145 *
146 * @see org.xml.sax.DocumentHandler
147 */
148
149 public Document parse(InputStream is, String systemId)
150 throws SAXException, IOException {
151 if (is == null) {
152 throw new IllegalArgumentException(
153 "InputStream cannot be null");
154 }
155
156 InputSource in = new InputSource(is);
157 in.setSystemId(systemId);
158 return parse(in);
159 }
160
161 /**
162 * Parse the content of the given URI as an XML document
163 * and return a new DOM {@link Document} object.
164 * An <code>IllegalArgumentException</code> is thrown if the
165 * URI is <code>null</code> null.
166 *
167 * @param uri The location of the content to be parsed.
168 *
169 * @return A new DOM Document object.
170 *
171 * @throws IOException If any IO errors occur.
172 * @throws SAXException If any parse errors occur.
173 * @throws IllegalArgumentException When <code>uri</code> is <code>null</code>
174 *
175 * @see org.xml.sax.DocumentHandler
176 */
177
178 public Document parse(String uri) throws SAXException, IOException {
179 if (uri == null) {
180 throw new IllegalArgumentException("URI cannot be null");
181 }
182
183 InputSource in = new InputSource(uri);
184 return parse(in);
185 }
186
187 /**
188 * Parse the content of the given file as an XML document
189 * and return a new DOM {@link Document} object.
190 * An <code>IllegalArgumentException</code> is thrown if the
191 * <code>File</code> is <code>null</code> null.
192 *
193 * @param f The file containing the XML to parse.
194 *
195 * @throws IOException If any IO errors occur.
196 * @throws SAXException If any parse errors occur.
197 * @throws IllegalArgumentException When <code>f</code> is <code>null</code>
198 *
199 * @see org.xml.sax.DocumentHandler
200 * @return A new DOM Document object.
201 */
202
203 public Document parse(File f) throws SAXException, IOException {
204 if (f == null) {
205 throw new IllegalArgumentException("File cannot be null");
206 }
207
208 //convert file to appropriate URI, f.toURI().toASCIIString()
209 //converts the URI to string as per rule specified in
210 //RFC 2396,
211 InputSource in = new InputSource(f.toURI().toASCIIString());
212 return parse(in);
213 }
214
215 /**
216 * Parse the content of the given input source as an XML document
217 * and return a new DOM {@link Document} object.
218 * An <code>IllegalArgumentException</code> is thrown if the
219 * <code>InputSource</code> is <code>null</code> null.
220 *
221 * @param is InputSource containing the content to be parsed.
222 *
223 * @return A new DOM Document object.
224 *
225 * @throws IOException If any IO errors occur.
226 * @throws SAXException If any parse errors occur.
227 * @throws IllegalArgumentException When <code>is</code> is <code>null</code>
228 *
229 * @see org.xml.sax.DocumentHandler
230 */
231
232 public abstract Document parse(InputSource is) throws SAXException,
233 IOException;
234
235 /**
236 * Indicates whether or not this parser is configured to
237 * understand namespaces.
238 *
239 * @return true if this parser is configured to understand
240 * namespaces; false otherwise.
241 */
242
243 public abstract boolean isNamespaceAware();
244
245 /**
246 * Indicates whether or not this parser is configured to
247 * validate XML documents.
248 *
249 * @return true if this parser is configured to validate
250 * XML documents; false otherwise.
251 */
252
253 public abstract boolean isValidating();
254
255 /**
256 * Specify the {@link EntityResolver} to be used to resolve
257 * entities present in the XML document to be parsed. Setting
258 * this to <code>null</code> will result in the underlying
259 * implementation using it's own default implementation and
260 * behavior.
261 *
262 * @param er The <code>EntityResolver</code> to be used to resolve entities
263 * present in the XML document to be parsed.
264 */
265
266 public abstract void setEntityResolver(EntityResolver er);
267
268 /**
269 * Specify the {@link ErrorHandler} to be used by the parser.
270 * Setting this to <code>null</code> will result in the underlying
271 * implementation using it's own default implementation and
272 * behavior.
273 *
274 * @param eh The <code>ErrorHandler</code> to be used by the parser.
275 */
276
277 public abstract void setErrorHandler(ErrorHandler eh);
278
279 /**
280 * Obtain a new instance of a DOM {@link Document} object
281 * to build a DOM tree with.
282 *
283 * @return A new instance of a DOM Document object.
284 */
285
286 public abstract Document newDocument();
287
288 /**
289 * Obtain an instance of a {@link DOMImplementation} object.
290 *
291 * @return A new instance of a <code>DOMImplementation</code>.
292 */
293
294 public abstract DOMImplementation getDOMImplementation();
295
296 /** <p>Get current state of canonicalization.</p>
297 *
298 * @return current state canonicalization control
299 */
300 /*
301 public boolean getCanonicalization() {
302 return canonicalState;
303 }
304 */
305
306 /** <p>Get a reference to the the {@link Schema} being used by
307 * the XML processor.</p>
308 *
309 * <p>If no schema is being used, <code>null</code> is returned.</p>
310 *
311 * @return {@link Schema} being used or <code>null</code>
312 * if none in use
313 *
314 * @throws UnsupportedOperationException When implementation does not
315 * override this method
316 *
317 * @since 1.5
318 */
319 public Schema getSchema() {
320 throw new UnsupportedOperationException(
321 "This parser does not support specification \""
322 + this .getClass().getPackage()
323 .getSpecificationTitle()
324 + "\" version \""
325 + this .getClass().getPackage()
326 .getSpecificationVersion() + "\"");
327 }
328
329 /**
330 * <p>Get the XInclude processing mode for this parser.</p>
331 *
332 * @return
333 * the return value of
334 * the {@link DocumentBuilderFactory#isXIncludeAware()}
335 * when this parser was created from factory.
336 *
337 * @throws UnsupportedOperationException When implementation does not
338 * override this method
339 *
340 * @since 1.5
341 *
342 * @see DocumentBuilderFactory#setXIncludeAware(boolean)
343 */
344 public boolean isXIncludeAware() {
345 throw new UnsupportedOperationException(
346 "This parser does not support specification \""
347 + this .getClass().getPackage()
348 .getSpecificationTitle()
349 + "\" version \""
350 + this .getClass().getPackage()
351 .getSpecificationVersion() + "\"");
352 }
353 }
|