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