View Javadoc
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   */
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 }