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