001: /**
002: * $Id: DocumentBuilder.java,v 1.2 2002/05/08 19:44:06 yuvalo Exp $
003: *
004: * Copyright (c) 1998-2000 Sun Microsystems, Inc. All Rights Reserved.
005: *
006: * This software is the confidential and proprietary information of Sun
007: * Microsystems, Inc. ("Confidential Information"). You shall not
008: * disclose such Confidential Information and shall use it only in
009: * accordance with the terms of the license agreement you entered into
010: * with Sun.
011: *
012: * SUN MAKES NO REPRESENTATIONS OR WARRANTIES ABOUT THE SUITABILITY OF THE
013: * SOFTWARE, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
014: * IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
015: * PURPOSE, OR NON-INFRINGEMENT. SUN SHALL NOT BE LIABLE FOR ANY DAMAGES
016: * SUFFERED BY LICENSEE AS A RESULT OF USING, MODIFYING OR DISTRIBUTING
017: * THIS SOFTWARE OR ITS DERIVATIVES.
018: */package javax.xml.parsers;
019:
020: import java.io.InputStream;
021: import java.io.IOException;
022: import java.io.File;
023:
024: import org.xml.sax.Parser;
025: import org.xml.sax.HandlerBase;
026: import org.xml.sax.InputSource;
027: import org.xml.sax.SAXException;
028:
029: import org.w3c.dom.Document;
030: import org.w3c.dom.DOMImplementation;
031:
032: /**
033: * Defines the API to obtain DOM Document instances from an XML
034: * document. Using this class, an application programmer can obtain a
035: * {@link org.w3c.dom.Document} from XML.<p>
036: *
037: * An instance of this class can be obtained from the
038: * {@link javax.xml.parsers.DocumentBuilderFactory#newDocumentBuilder()
039: * DocumentBuilderFactory.newDocumentBuilder} method. Once
040: * an instance of this class is obtained, XML can be parsed from a
041: * variety of input sources. These input sources are InputStreams,
042: * Files, URLs, and SAX InputSources.<p>
043: *
044: * Note that this class reuses several classes from the SAX API. This
045: * does not require that the implementor of the underlying DOM
046: * implementation use a SAX parser to parse XML document into a
047: * <code>Document</code>. It merely requires that the implementation
048: * communicate with the application using these existing APIs. <p>
049: *
050: * An implementation of <code>DocumentBuilder</code> is <em>NOT</em>
051: * guaranteed to behave as per the specification if it is used concurrently by
052: * two or more threads. It is recommended to have one instance of the
053: * <code>DocumentBuilder</code> per thread or it is upto the application to
054: * make sure about the use of <code>DocumentBuilder</code> from more than one
055: * thread.
056: *
057: * @since JAXP 1.0
058: * @version 1.0
059: */
060:
061: public abstract class DocumentBuilder {
062:
063: protected DocumentBuilder() {
064: }
065:
066: /**
067: * Parse the content of the given <code>InputStream</code> as an XML
068: * document and return a new DOM {@link org.w3c.dom.Document} object.
069: *
070: * @param is InputStream containing the content to be parsed.
071: * @exception IOException If any IO errors occur.
072: * @exception SAXException If any parse errors occur.
073: * @exception IllegalArgumentException If the InputStream is null
074: * @see org.xml.sax.DocumentHandler
075: */
076:
077: public Document parse(InputStream is) throws SAXException,
078: IOException {
079: if (is == null) {
080: throw new IllegalArgumentException(
081: "InputStream cannot be null");
082: }
083:
084: InputSource in = new InputSource(is);
085: return parse(in);
086: }
087:
088: /**
089: * Parse the content of the given <code>InputStream</code> as an XML
090: * document and return a new DOM {@link org.w3c.dom.Document} object.
091: *
092: * @param is InputStream containing the content to be parsed.
093: * @param systemId Provide a base for resolving relative URIs.
094: * @exception IOException If any IO errors occur.
095: * @exception SAXException If any parse errors occur.
096: * @exception IllegalArgumentException If the InputStream is null.
097: * @see org.xml.sax.DocumentHandler
098: * @return A new DOM Document object.
099: */
100:
101: public Document parse(InputStream is, String systemId)
102: throws SAXException, IOException {
103: if (is == null) {
104: throw new IllegalArgumentException(
105: "InputStream cannot be null");
106: }
107:
108: InputSource in = new InputSource(is);
109: in.setSystemId(systemId);
110: return parse(in);
111: }
112:
113: /**
114: * Parse the content of the given URI as an XML document
115: * and return a new DOM {@link org.w3c.dom.Document} object.
116: *
117: * @param uri The location of the content to be parsed.
118: * @exception IOException If any IO errors occur.
119: * @exception SAXException If any parse errors occur.
120: * @exception IllegalArgumentException If the URI is null.
121: * @see org.xml.sax.DocumentHandler
122: * @return A new DOM Document object.
123: */
124:
125: public Document parse(String uri) throws SAXException, IOException {
126: if (uri == null) {
127: throw new IllegalArgumentException("URI cannot be null");
128: }
129:
130: InputSource in = new InputSource(uri);
131: return parse(in);
132: }
133:
134: /**
135: * Parse the content of the given file as an XML document
136: * and return a new DOM {@link org.w3c.dom.Document} object.
137: *
138: * @param f The file containing the XML to parse.
139: * @exception IOException If any IO errors occur.
140: * @exception SAXException If any parse errors occur.
141: * @exception IllegalArgumentException If the file is null.
142: * @see org.xml.sax.DocumentHandler
143: * @return A new DOM Document object.
144: */
145:
146: public Document parse(File f) throws SAXException, IOException {
147: if (f == null) {
148: throw new IllegalArgumentException("File cannot be null");
149: }
150:
151: String uri = "file:" + f.getAbsolutePath();
152: if (File.separatorChar == '\\') {
153: uri = uri.replace('\\', '/');
154: }
155: InputSource in = new InputSource(uri);
156: return parse(in);
157: }
158:
159: /**
160: * Parse the content of the given input source as an XML document
161: * and return a new DOM {@link org.w3c.dom.Document} object.
162: *
163: * @param is InputSource containing the content to be parsed.
164: * @exception IOException If any IO errors occur.
165: * @exception SAXException If any parse errors occur.
166: * @exception IllegalArgumentException If the InputSource is null.
167: * @see org.xml.sax.DocumentHandler
168: * @return A new DOM Document object.
169: */
170:
171: public abstract Document parse(InputSource is) throws SAXException,
172: IOException;
173:
174: /**
175: * Indicates whether or not this parser is configured to
176: * understand namespaces.
177: *
178: * @return true if this parser is configured to understand
179: * namespaces; false otherwise.
180: */
181:
182: public abstract boolean isNamespaceAware();
183:
184: /**
185: * Indicates whether or not this parser is configured to
186: * validate XML documents.
187: *
188: * @return true if this parser is configured to validate
189: * XML documents; false otherwise.
190: */
191:
192: public abstract boolean isValidating();
193:
194: /**
195: * Specify the {@link org.xml.sax.EntityResolver} to be used to resolve
196: * entities present in the XML document to be parsed. Setting
197: * this to <code>null</code> will result in the underlying
198: * implementation using it's own default implementation and
199: * behavior.
200: *
201: * @param er The <code>EntityResolver</code> to be used to resolve entities
202: * present in the XML document to be parsed.
203: */
204:
205: public abstract void setEntityResolver(org.xml.sax.EntityResolver er);
206:
207: /**
208: * Specify the {@link org.xml.sax.ErrorHandler} to be used to report
209: * errors present in the XML document to be parsed. Setting
210: * this to <code>null</code> will result in the underlying
211: * implementation using it's own default implementation and
212: * behavior.
213: *
214: * @param eh The <code>ErrorHandler</code> to be used to report errors
215: * present in the XML document to be parsed.
216: */
217:
218: public abstract void setErrorHandler(org.xml.sax.ErrorHandler eh);
219:
220: /**
221: * Obtain a new instance of a DOM {@link org.w3c.dom.Document} object
222: * to build a DOM tree with. An alternative way to create a DOM
223: * Document object is to use the
224: * {@link #getDOMImplementation() getDOMImplementation}
225: * method to get a DOM Level 2 DOMImplementation object and then use
226: * DOM Level 2 methods on that object to create a DOM Document object.
227: *
228: * @return A new instance of a DOM Document object.
229: */
230:
231: public abstract Document newDocument();
232:
233: /**
234: * Obtain an instance of a {@link org.w3c.dom.DOMImplementation} object.
235: *
236: * @return A new instance of a <code>DOMImplementation</code>.
237: */
238:
239: public abstract DOMImplementation getDOMImplementation();
240: }
|