1. /*
  2. * Copyright 2003 Sun Microsystems, Inc. All rights reserved.
  3. * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
  4. */
  5. /*
  6. * @(#)DocumentBuilder.java 1.9 03/01/23
  7. */
  8. package javax.xml.parsers;
  9. import java.io.InputStream;
  10. import java.io.IOException;
  11. import java.io.File;
  12. import org.xml.sax.Parser;
  13. import org.xml.sax.HandlerBase;
  14. import org.xml.sax.InputSource;
  15. import org.xml.sax.SAXException;
  16. import org.w3c.dom.Document;
  17. import org.w3c.dom.DOMImplementation;
  18. /**
  19. * Defines the API to obtain DOM Document instances from an XML
  20. * document. Using this class, an application programmer can obtain a
  21. * {@link org.w3c.dom.Document} from XML.<p>
  22. *
  23. * An instance of this class can be obtained from the
  24. * {@link javax.xml.parsers.DocumentBuilderFactory#newDocumentBuilder()
  25. * DocumentBuilderFactory.newDocumentBuilder} method. Once
  26. * an instance of this class is obtained, XML can be parsed from a
  27. * variety of input sources. These input sources are InputStreams,
  28. * Files, URLs, and SAX InputSources.<p>
  29. *
  30. * Note that this class reuses several classes from the SAX API. This
  31. * does not require that the implementor of the underlying DOM
  32. * implementation use a SAX parser to parse XML document into a
  33. * <code>Document</code>. It merely requires that the implementation
  34. * communicate with the application using these existing APIs. <p>
  35. *
  36. * An implementation of <code>DocumentBuilder</code> is <em>NOT</em>
  37. * guaranteed to behave as per the specification if it is used concurrently by
  38. * two or more threads. It is recommended to have one instance of the
  39. * <code>DocumentBuilder</code> per thread or it is upto the application to
  40. * make sure about the use of <code>DocumentBuilder</code> from more than one
  41. * thread.
  42. *
  43. * @since JAXP 1.0
  44. * @version 1.0
  45. */
  46. public abstract class DocumentBuilder {
  47. protected DocumentBuilder () {
  48. }
  49. /**
  50. * Parse the content of the given <code>InputStream</code> as an XML
  51. * document and return a new DOM {@link org.w3c.dom.Document} object.
  52. *
  53. * @param is InputStream containing the content to be parsed.
  54. * @exception IOException If any IO errors occur.
  55. * @exception SAXException If any parse errors occur.
  56. * @exception IllegalArgumentException If the InputStream is null
  57. * @see org.xml.sax.DocumentHandler
  58. */
  59. public Document parse(InputStream is)
  60. throws SAXException, IOException
  61. {
  62. if (is == null) {
  63. throw new IllegalArgumentException("InputStream cannot be null");
  64. }
  65. InputSource in = new InputSource(is);
  66. return parse(in);
  67. }
  68. /**
  69. * Parse the content of the given <code>InputStream</code> as an XML
  70. * document and return a new DOM {@link org.w3c.dom.Document} object.
  71. *
  72. * @param is InputStream containing the content to be parsed.
  73. * @param systemId Provide a base for resolving relative URIs.
  74. * @exception IOException If any IO errors occur.
  75. * @exception SAXException If any parse errors occur.
  76. * @exception IllegalArgumentException If the InputStream is null.
  77. * @see org.xml.sax.DocumentHandler
  78. * @return A new DOM Document object.
  79. */
  80. public Document parse(InputStream is, String systemId)
  81. throws SAXException, IOException
  82. {
  83. if (is == null) {
  84. throw new IllegalArgumentException("InputStream cannot be null");
  85. }
  86. InputSource in = new InputSource(is);
  87. in.setSystemId(systemId);
  88. return parse(in);
  89. }
  90. /**
  91. * Parse the content of the given URI as an XML document
  92. * and return a new DOM {@link org.w3c.dom.Document} object.
  93. *
  94. * @param uri The location of the content to be parsed.
  95. * @exception IOException If any IO errors occur.
  96. * @exception SAXException If any parse errors occur.
  97. * @exception IllegalArgumentException If the URI is null.
  98. * @see org.xml.sax.DocumentHandler
  99. * @return A new DOM Document object.
  100. */
  101. public Document parse(String uri)
  102. throws SAXException, IOException
  103. {
  104. if (uri == null) {
  105. throw new IllegalArgumentException("URI cannot be null");
  106. }
  107. InputSource in = new InputSource(uri);
  108. return parse(in);
  109. }
  110. /**
  111. * Parse the content of the given file as an XML document
  112. * and return a new DOM {@link org.w3c.dom.Document} object.
  113. *
  114. * @param f The file containing the XML to parse.
  115. * @exception IOException If any IO errors occur.
  116. * @exception SAXException If any parse errors occur.
  117. * @exception IllegalArgumentException If the file is null.
  118. * @see org.xml.sax.DocumentHandler
  119. * @return A new DOM Document object.
  120. */
  121. public Document parse(File f)
  122. throws SAXException, IOException
  123. {
  124. if (f == null) {
  125. throw new IllegalArgumentException("File cannot be null");
  126. }
  127. String uri = "file:" + f.getAbsolutePath();
  128. if (File.separatorChar == '\\') {
  129. uri = uri.replace('\\', '/');
  130. }
  131. InputSource in = new InputSource(uri);
  132. return parse(in);
  133. }
  134. /**
  135. * Parse the content of the given input source as an XML document
  136. * and return a new DOM {@link org.w3c.dom.Document} object.
  137. *
  138. * @param is InputSource containing the content to be parsed.
  139. * @exception IOException If any IO errors occur.
  140. * @exception SAXException If any parse errors occur.
  141. * @exception IllegalArgumentException If the InputSource is null.
  142. * @see org.xml.sax.DocumentHandler
  143. * @return A new DOM Document object.
  144. */
  145. public abstract Document parse(InputSource is)
  146. throws SAXException, IOException;
  147. /**
  148. * Indicates whether or not this parser is configured to
  149. * understand namespaces.
  150. *
  151. * @return true if this parser is configured to understand
  152. * namespaces; false otherwise.
  153. */
  154. public abstract boolean isNamespaceAware();
  155. /**
  156. * Indicates whether or not this parser is configured to
  157. * validate XML documents.
  158. *
  159. * @return true if this parser is configured to validate
  160. * XML documents; false otherwise.
  161. */
  162. public abstract boolean isValidating();
  163. /**
  164. * Specify the {@link org.xml.sax.EntityResolver} to be used to resolve
  165. * entities present in the XML document to be parsed. Setting
  166. * this to <code>null</code> will result in the underlying
  167. * implementation using it's own default implementation and
  168. * behavior.
  169. *
  170. * @param er The <code>EntityResolver</code> to be used to resolve entities
  171. * present in the XML document to be parsed.
  172. */
  173. public abstract void setEntityResolver(org.xml.sax.EntityResolver er);
  174. /**
  175. * Specify the {@link org.xml.sax.ErrorHandler} to be used to report
  176. * errors present in the XML document to be parsed. Setting
  177. * this to <code>null</code> will result in the underlying
  178. * implementation using it's own default implementation and
  179. * behavior.
  180. *
  181. * @param eh The <code>ErrorHandler</code> to be used to report errors
  182. * present in the XML document to be parsed.
  183. */
  184. public abstract void setErrorHandler(org.xml.sax.ErrorHandler eh);
  185. /**
  186. * Obtain a new instance of a DOM {@link org.w3c.dom.Document} object
  187. * to build a DOM tree with. An alternative way to create a DOM
  188. * Document object is to use the
  189. * {@link #getDOMImplementation() getDOMImplementation}
  190. * method to get a DOM Level 2 DOMImplementation object and then use
  191. * DOM Level 2 methods on that object to create a DOM Document object.
  192. *
  193. * @return A new instance of a DOM Document object.
  194. */
  195. public abstract Document newDocument();
  196. /**
  197. * Obtain an instance of a {@link org.w3c.dom.DOMImplementation} object.
  198. *
  199. * @return A new instance of a <code>DOMImplementation</code>.
  200. */
  201. public abstract DOMImplementation getDOMImplementation();
  202. }