DocumentBuilder


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