001: /*--
002:
003: $Id: DOMAdapter.java,v 1.1 2005/04/27 09:32:43 wittek Exp $
004:
005: Copyright (C) 2000-2004 Jason Hunter & Brett McLaughlin.
006: All rights reserved.
007:
008: Redistribution and use in source and binary forms, with or without
009: modification, are permitted provided that the following conditions
010: are met:
011:
012: 1. Redistributions of source code must retain the above copyright
013: notice, this list of conditions, and the following disclaimer.
014:
015: 2. Redistributions in binary form must reproduce the above copyright
016: notice, this list of conditions, and the disclaimer that follows
017: these conditions in the documentation and/or other materials
018: provided with the distribution.
019:
020: 3. The name "JDOM" must not be used to endorse or promote products
021: derived from this software without prior written permission. For
022: written permission, please contact <request_AT_jdom_DOT_org>.
023:
024: 4. Products derived from this software may not be called "JDOM", nor
025: may "JDOM" appear in their name, without prior written permission
026: from the JDOM Project Management <request_AT_jdom_DOT_org>.
027:
028: In addition, we request (but do not require) that you include in the
029: end-user documentation provided with the redistribution and/or in the
030: software itself an acknowledgement equivalent to the following:
031: "This product includes software developed by the
032: JDOM Project (http://www.jdom.org/)."
033: Alternatively, the acknowledgment may be graphical using the logos
034: available at http://www.jdom.org/images/logos.
035:
036: THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
037: WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
038: OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
039: DISCLAIMED. IN NO EVENT SHALL THE JDOM AUTHORS OR THE PROJECT
040: CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
041: SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
042: LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
043: USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
044: ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
045: OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
046: OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
047: SUCH DAMAGE.
048:
049: This software consists of voluntary contributions made by many
050: individuals on behalf of the JDOM Project and was originally
051: created by Jason Hunter <jhunter_AT_jdom_DOT_org> and
052: Brett McLaughlin <brett_AT_jdom_DOT_org>. For more information
053: on the JDOM Project, please see <http://www.jdom.org/>.
054:
055: */
056:
057: package org.jdom.adapters;
058:
059: import java.io.*;
060:
061: import org.jdom.*;
062: import org.w3c.dom.Document;
063:
064: /**
065: * Defines a standard set of adapter methods for interfacing with a DOM parser
066: * and obtaining a DOM {@link org.w3c.dom.Document org.w3c.dom.Document} object.
067: * Implementing classes map these calls to DOM parser-specific calls, allowing
068: * any third-party parser to be used with JDOM.
069: *
070: * @version $Revision: 1.1 $, $Date: 2005/04/27 09:32:43 $
071: * @author Brett McLaughlin
072: * @author Jason Hunter
073: */
074: public interface DOMAdapter {
075:
076: /**
077: * This creates a new <code>Document</code> from a
078: * given filename by letting a DOM parser handle parsing from the file.
079: *
080: * @param filename file to parse.
081: * @param validate <code>boolean</code> to indicate if validation
082: * should occur.
083: * @return <code>Document</code> - instance ready for use.
084: * @throws IOException when I/O error occurs.
085: * @throws JDOMException when errors occur in parsing.
086: */
087: public Document getDocument(File filename, boolean validate)
088: throws IOException, JDOMException;
089:
090: /**
091: * This creates a new <code>Document</code> from an
092: * existing <code>InputStream</code> by letting a DOM
093: * parser handle parsing using the supplied stream.
094: *
095: * @param in <code>InputStream</code> to parse.
096: * @param validate <code>boolean</code> to indicate if validation
097: * should occur.
098: * @return <code>Document</code> - instance ready for use.
099: * @throws IOException when I/O error occurs.
100: * @throws JDOMException when errors occur in parsing.
101: */
102: public Document getDocument(InputStream in, boolean validate)
103: throws IOException, JDOMException;
104:
105: /**
106: * This creates an empty <code>Document</code> object based
107: * on a specific parser implementation.
108: *
109: * @return <code>Document</code> - created DOM Document.
110: * @throws JDOMException when errors occur.
111: */
112: public Document createDocument() throws JDOMException;
113:
114: /**
115: * This creates an empty <code>Document</code> object based
116: * on a specific parser implementation with the given DOCTYPE.
117: *
118: * @param doctype Initial <code>DocType</code> of the document.
119: * @return <code>Document</code> - created DOM Document.
120: * @throws JDOMException when errors occur.
121: */
122: public Document createDocument(DocType doctype)
123: throws JDOMException;
124: }
|