KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > xquark > xml > xdbc > XMLDocument


1 /*
2  * This file belongs to the XQuark distribution.
3  * Copyright (C) 2003 Universite de Versailles Saint-Quentin.
4  *
5  * This program is free software; you can redistribute it and/or
6  * modify it under the terms of the GNU Lesser General Public
7  * License as published by the Free Software Foundation; either
8  * version 2.1 of the License, or (at your option) any later version.
9  *
10  * This program is distributed in the hope that it will be useful,
11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13  * Lesser General Public License for more details.
14  *
15  * You should have received a copy of the GNU Lesser General Public
16  * License along with this program; if not, write to the Free Software
17  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307.
18  * You can also get it at http://www.gnu.org/licenses/lgpl.html
19  *
20  * For more information on this software, see http://www.xquark.org.
21  */

22
23 package org.xquark.xml.xdbc;
24
25 import java.io.Writer JavaDoc;
26
27 import org.w3c.dom.Document JavaDoc;
28 import org.w3c.dom.Element JavaDoc;
29 import org.xml.sax.ContentHandler JavaDoc;
30 import org.xml.sax.ErrorHandler JavaDoc;
31 import org.xml.sax.ext.LexicalHandler JavaDoc;
32
33 /**
34  * This interface describes a document object which provides access to XML data
35  * in several ways. When the underlying object is a stored document, it also
36  * supports a number of document management methods also available in the
37  * XMLCollection interface.<BR><BR>
38  */

39 public interface XMLDocument
40 {
41
42
43     
44     /**
45      * Returns the document identifier in the XML collection.
46      * return the document identifier as a String, or null if the document is not a stored
47      * object.
48      */

49     public String JavaDoc getIdentifier();
50     
51     /**
52      * Changes the document identifier in the XML collection. This change is persistent in the
53      * data source.
54      * Note: Depending on the auto-commit mode of the underlying data source connection, the
55      * change may only become definitive after a commit operation.
56      * @param identifier the new document identifier
57      * @throws XMLDBCException if a data source access error occurs.
58      * @throws XMLDBCNotSupportedException if the renaming operation is not supported.
59      */

60     public void setIdentifier(String JavaDoc identifier) throws XMLDBCException, XMLDBCNotSupportedException;
61     
62     /**
63      * Returns the XML collection to which this document belongs. This may be null if
64      * the document is not a stored object.
65      * @return an XMLCollection object, or null if the document is not a stored object.
66      */

67     public XMLCollection getCollection();
68     
69     /**
70      * Removes the document from the collection to which it belongs. The object should
71      * not be accessed any more after this method is called.
72      * Note: Depending on the auto-commit mode of the underlying data source connection, the
73      * change may only become definitive after a commit operation.
74      * @throws XMLDBCException if a data source access error occurs.
75      * @throws XMLDBCNotSupportedException if the remove operation is not supported.
76      */

77     public void remove() throws XMLDBCException, XMLDBCNotSupportedException;
78     
79     /**
80      * Sets a (SAX2) content handler to intercept events produced when retrieving
81      * the document content.<BR>
82      * <P>*** ONLY FOR SAX2 ***</P>
83      * @param handler the content handler implementation (see org.xml.sax.ContentHandler)
84      */

85     public void setContentHandler(ContentHandler JavaDoc handler);
86     
87     /**
88      * Sets a (SAX2) lexical handler to intercept events produced when retrieving
89      * the document content.<BR>
90      * <P>*** ONLY FOR SAX2 ***</P>
91      * @param handler the lexical handler implementation (see org.xml.sax.ext.LexicalHandler)
92      */

93     public void setLexicalHandler(LexicalHandler JavaDoc handler);
94     
95     /**
96      * Sets a (SAX2) error handler to intercept error events produced when retrieving
97      * the document content.<BR>
98      * <P>*** ONLY FOR SAX2 ***</P>
99      * @param handler the error handler implementation (see org.xml.sax.ErrorHandler)
100      */

101     public void setErrorHandler(ErrorHandler JavaDoc handler);
102     
103     /**
104      * Retrieves the current (SAX2) content handler.<BR>
105      * <P>*** ONLY FOR SAX2 ***</P>
106      * @return the content handler implementation (see org.xml.sax.ContentHandler)
107      */

108     public ContentHandler JavaDoc getContentHandler();
109     
110     /**
111      * Retrieves the current (SAX2) lexical handler.<BR>
112      * <P>*** ONLY FOR SAX2 ***</P>
113      * @return the lexical handler implementation (see org.xml.sax.ext.LexicalHandler)
114      */

115     public LexicalHandler JavaDoc getLexicalHandler();
116     
117     /**
118      * SRetrieves the current (SAX2) error handler.<BR>
119      * <P>*** ONLY FOR SAX2 ***</P>
120      * @return the error handler implementation (see org.xml.sax.ErrorHandler)
121      */

122     public ErrorHandler JavaDoc getErrorHandler();
123     
124     /**
125      * Returns the document content as a DOM2 Document.
126      * @return the DOM2 Document containing the document data.
127      * @throws XMLDBCException if a data source access error occurs.
128      */

129     public Document JavaDoc getAsDocument() throws XMLDBCException;
130     
131     /**
132      * Returns the document content as a DOM2 Document.
133      * @return the DOM2 Document containing the document data.
134      * @throws XMLDBCException if a data source access error occurs.
135      * @deprecated New method name is {@link #getAsDocument()}
136      */

137     public Document JavaDoc getAsDOM() throws XMLDBCException;
138     
139     /**
140      * Attaches a DOM2 fragment corresponding to the XML document to the Element
141      * node passed as a parameter.
142      * @throws XMLDBCException if a data source access error occurs.
143      */

144     public void getAsDOM(Element JavaDoc parent) throws XMLDBCException;
145     
146     /**
147      * Returns the document content as an XML string.
148      * @return the XML string containing the document data.
149      * @throws XMLDBCException if a data source access error occurs.
150      */

151     public String JavaDoc getAsString() throws XMLDBCException;
152     
153     /**
154      * Returns the document content in a provided character stream.
155      * @param out a {@link java.io.Writer Writer} object assuming user is
156      * responsible for the character encoding.
157      * @throws XMLDBCException if a data source access error occurs.
158      */

159     public void getAsStream(Writer JavaDoc out) throws XMLDBCException;
160     
161     /**
162      * Returns the document content as a SAX2 event flow.
163      * This method uses the various SAX2 handlers set by the setXXXHandler() methods.
164      * <P>*** ONLY FOR SAX2 ***</P>
165      * @throws XMLDBCException if a data source access error occurs
166      * or if the user has not set a content handler.
167      * @throws org.xml.sax.SAXException if a handler exception occurs.
168      */

169     public void getAsSAX() throws XMLDBCException, org.xml.sax.SAXException JavaDoc;
170 }
171
Popular Tags