XMLResultSet


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  import java.util.Map  ;
27  
28  import org.w3c.dom.Document  ;
29  import org.w3c.dom.Element  ;
30  import org.w3c.dom.Node  ;
31  import org.xml.sax.ContentHandler  ;
32  import org.xml.sax.ErrorHandler  ;
33  import org.xml.sax.ext.LexicalHandler  ;
34  import org.xquark.schema.validation.PSVInfoSetProvider;
35  
36  /**
37   * This interface represents the set of results of a query.<BR>
38   * This interface has setContentHandler(...), setLexicalHandler(...) and setErrorHandler(...)
39   * methods allowing the client to get the results as SAX2 events.<BR><BR>
40   */
41  public interface XMLResultSet
42  {
43      /*********************************************************************/
44      /*************************** SAX management functions ****************/
45      /*********************************************************************/
46      
47      /**
48       * Sets a (SAX2) content handler to intercept events produced when retrieving results as SAX.<BR>
49       * <P>*** ONLY FOR SAX2 ***</P>
50       * @param handler the content handler implementation (see org.xml.sax.ContentHandler)
51       */
52      public void setContentHandler(ContentHandler   handler);
53      
54      /**
55       * Sets a (SAX2) lexical handler to intercept events produced when retrieving results as SAX.<BR>
56       * <P>*** ONLY FOR SAX2 ***</P>
57       * @param handler the lexical handler implementation (see org.xml.sax.ext.LexicalHandler)
58       */
59      public void setLexicalHandler(LexicalHandler   handler);
60      
61      /**
62       * Sets a (SAX2) error handler to intercept error events produced when retrieving results as SAX.<BR>
63       * <P>*** ONLY FOR SAX2 ***</P>
64       * @param handler the error handler implementation (see org.xml.sax.ErrorHandler)
65       */
66      public void setErrorHandler(ErrorHandler   handler);
67      
68      /**
69       * Returns the current content handler.<BR>
70       * <P>*** ONLY FOR SAX2 ***</P>
71       */
72      public ContentHandler   getContentHandler();
73      
74      /**
75       * Returns the current lexical handler.<BR>
76       * <P>*** ONLY FOR SAX2 ***</P>
77       */
78      public LexicalHandler   getLexicalHandler();
79      
80      /**
81       * Returns the current error handler.<BR>
82       * <P>*** ONLY FOR SAX2 ***</P>
83       */
84      public ErrorHandler   getErrorHandler();
85      
86      /*********************************************************************/
87      /*************************** ResultSet management ********************/
88      /*********************************************************************/
89      
90      /**
91       * Returns the statement that produced this result set.
92       * @return the XStatement object that produced this XResultSet object.
93       * @throws XMLDBCException if a data source access error occurs.
94       */
95      public XMLStatement getStatement() throws XMLDBCException;
96      
97      /**
98       * Returns the result set metadata (the XML Schema that models the returned data)
99       * as an XMLDocument.
100      * This schema describes the XML type of each result in the set.
101      * @return the result set metadata (a XML Schema).
102      * @throws XMLDBCException if a data source access error occurs.
103      */
104     public XMLDocument getMetaData() throws XMLDBCException;
105     
106     /**
107      * Returns the result set prefix map (as prefix-namespace pairs).
108      * This map is used to produce each result in the set.
109      * @return the result set prefix map.
110      * @throws XMLDBCException if a data source access error occurs.
111      */
112     public Map   getPrefixMap() throws XMLDBCException;
113     
114     /**
115      * Releases this result set object's resources immediately instead of waiting
116      * for this to happen when it is automatically closed.<BR>
117      * <B>Note:</B> A XResultSet object is automatically closed by the XStatement
118      * object that generated it when that XStatement object is closed,
119      * re-executed, or is used to retrieve the next result from a sequence of
120      * multiple results.
121      * @throws XMLDBCException if a data source access error occurs.
122      */
123     public void close() throws XMLDBCException;
124     
125     /**
126      * Indicates whether the cursor is before the first result in this result set.
127      * @return true if the cursor is before the first result; false otherwise.
128      * @throws XMLDBCException if a data source access error occurs.
129      */
130     public boolean isBeforeFirst() throws XMLDBCException;
131     
132     /**
133      * Returns the next result as a DOM2 document and increments by 1 the cursor
134      * position.
135      * The cursor is initially positioned before the first result; the first
136      * call to the method nextAsDOM() makes the first result the current result.
137      * @return the next result (as a DOM level 2 document) of the result set or null
138      * if there is no more result in the result set.
139      * @throws XMLDBCException if a data source access error occurs.
140      */
141     public Document   nextAsDocument() throws XMLDBCException;
142     
143     /**
144      * Returns the next result as a DOM2 node and increments by 1 the cursor position.
145      * The cursor is initially positioned before the first result; the first
146      * call to the method nextAsDOM() makes the first result the current result.
147      * @deprecated Prefer {@link #nextAsDocument()} or {@link #nextAsDOM(Element)}
148      * becuse a result may return multiple root nodes.
149      * @return the next result (as a DOM level 2 node) of the result set or
150      * null if there is no more result in the result set.
151      * @throws XMLDBCException if a data source access error occurs.
152      */
153     public Node   nextAsDOM() throws XMLDBCException;
154     
155     /**
156      * Attaches the next result nodes as children of the Element node passed
157      * as a parameter to and increments by 1 the cursor position.
158      * The cursor is initially positioned before the first result; the first
159      * call to the method nextAsDOM() makes the first result the current result.
160      * @throws XMLDBCException if a data source access error occurs.
161      */
162     public void nextAsDOM(Element   parent) throws XMLDBCException;
163     
164     /**
165      * Returns the next result as an XML string and increments by 1 the cursor position.
166      * The cursor is initially positioned before the first result; the first
167      * call to the method nextAsString() makes the first result the current result.
168      * @return the next result (as an XML string) of the result set or null if
169      * there is no more result in the result set.
170      * @throws XMLDBCException if a data source access error occurs.
171      */
172     public String   nextAsString() throws XMLDBCException;
173     
174     /**
175      * Returns the next result in a provided character stream and increments
176      * by 1 the cursor position.
177      * The cursor is initially positioned before the first result; the first
178      * call to the method nextAsString() makes the first result the current result.
179      * @param out a {@link java.io.Writer Writer} object assuming user is
180      * responsible for the character encoding.
181      * @throws XMLDBCException if a data source access error occurs.
182      */
183     public void nextAsStream(Writer   out) throws XMLDBCException;
184     
185     /**
186      * Returns the next result as a SAX2 event flow and increments by 1 the cursor position.
187      * The cursor is initially positioned before the first result; the first
188      * call to the method nextAsSAX makes the first result the current result.
189      * This method uses the various SAX2 handlers set by the setXXXHandler() methods.
190      * <P>*** ONLY FOR SAX2 ***</P>
191      * @throws XMLDBCException if a data source access error occurs
192      * or if user has not set a content handler.
193      * @throws org.xml.sax.SAXException if a handler exception occurs.
194      */
195     public void nextAsSAX() throws XMLDBCException, org.xml.sax.SAXException  ;
196     
197     /**
198      * Indicates if there is a next Result after the current Result in ResultSet.
199      * @return true if there is a next Result, false otherwise.
200      * @throws XMLDBCException if a data source access error occurs.
201      */
202     public boolean hasNext() throws XMLDBCException;
203     
204     /**
205      * Retrieves the current cursor position in ResultSet. The first position is number 1.
206      * @return the current cursor position in ResultSet (-1 if the cursor is not on a Result).
207      * @throws XMLDBCException if a data source access error occurs.
208      */
209     public int getPosition() throws XMLDBCException;
210     
211     /**
212      * Returns the fragments contained in the result set as a single XML document, with
213      * a document root element having the specified namespace, local name and qualified name.
214      * Note: this convenience method can only be called if the cursor is before the
215      * first element. It will process the complete result set in one step.
216      * @param namespace the namespace of the document root element.
217      * @param localName the local name of the document root element.
218      * @param qName the qualified name of the document root element.
219      * @return an XML document containing the fragments of the result set, as children of
220      * the specified document root element.
221      * @throws XMLDBCException if a data source access error occurs.
222      */
223     public XMLDocument getFragmentsAsDocument(String   namespace, String   localName, String   qName)
224     throws XMLDBCException;
225 
226     /**
227      * 
228      * @return true if a root tag is present, false otherwise.
229      */
230     public boolean hasRootTag();
231     
232     /**
233      * 
234      * @return true if a document is present, false otherwise.
235      */
236     public boolean isDocument();
237     
238     /**
239      * 
240      * @return the PSVInfoSetProvider if present null otherwise
241      */
242     public PSVInfoSetProvider getPSVInfoSetProvider();
243     
244 }
245
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags