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  ;
26  
27  import org.w3c.dom.Document  ;
28  import org.w3c.dom.Element  ;
29  import org.xml.sax.ContentHandler  ;
30  import org.xml.sax.ErrorHandler  ;
31  import org.xml.sax.ext.LexicalHandler  ;
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   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   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   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   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   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   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   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   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   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   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   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   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   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  ;
170 }
171
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags