org.xquark.xml.xdbc
Interface XMLResultSet

All Known Subinterfaces:
XMLDocumentSet

public interface XMLResultSet

This interface represents the set of results of a query.
This interface has setContentHandler(...), setLexicalHandler(...) and setErrorHandler(...) methods allowing the client to get the results as SAX2 events.


Method Summary
 void close()
          Releases this result set object's resources immediately instead of waiting for this to happen when it is automatically closed.
 org.xml.sax.ContentHandler getContentHandler()
          Returns the current content handler.
 org.xml.sax.ErrorHandler getErrorHandler()
          Returns the current error handler.
 XMLDocument getFragmentsAsDocument(java.lang.String namespace, java.lang.String localName, java.lang.String qName)
          Returns the fragments contained in the result set as a single XML document, with a document root element having the specified namespace, local name and qualified name.
 org.xml.sax.ext.LexicalHandler getLexicalHandler()
          Returns the current lexical handler.
 XMLDocument getMetaData()
          Returns the result set metadata (the XML Schema that models the returned data) as an XMLDocument.
 int getPosition()
          Retrieves the current cursor position in ResultSet.
 java.util.Map getPrefixMap()
          Returns the result set prefix map (as prefix-namespace pairs).
 org.xquark.schema.validation.PSVInfoSetProvider getPSVInfoSetProvider()
           
 XMLStatement getStatement()
          Returns the statement that produced this result set.
 boolean hasNext()
          Indicates if there is a next Result after the current Result in ResultSet.
 boolean hasRootTag()
           
 boolean isBeforeFirst()
          Indicates whether the cursor is before the first result in this result set.
 boolean isDocument()
           
 org.w3c.dom.Document nextAsDocument()
          Returns the next result as a DOM2 document and increments by 1 the cursor position.
 org.w3c.dom.Node nextAsDOM()
          Deprecated. Prefer nextAsDocument() or nextAsDOM(Element) becuse a result may return multiple root nodes.
 void nextAsDOM(org.w3c.dom.Element parent)
          Attaches the next result nodes as children of the Element node passed as a parameter to and increments by 1 the cursor position.
 void nextAsSAX()
          Returns the next result as a SAX2 event flow and increments by 1 the cursor position.
 void nextAsStream(java.io.Writer out)
          Returns the next result in a provided character stream and increments by 1 the cursor position.
 java.lang.String nextAsString()
          Returns the next result as an XML string and increments by 1 the cursor position.
 void setContentHandler(org.xml.sax.ContentHandler handler)
          Sets a (SAX2) content handler to intercept events produced when retrieving results as SAX.
 void setErrorHandler(org.xml.sax.ErrorHandler handler)
          Sets a (SAX2) error handler to intercept error events produced when retrieving results as SAX.
 void setLexicalHandler(org.xml.sax.ext.LexicalHandler handler)
          Sets a (SAX2) lexical handler to intercept events produced when retrieving results as SAX.
 

Method Detail

setContentHandler

public void setContentHandler(org.xml.sax.ContentHandler handler)
Sets a (SAX2) content handler to intercept events produced when retrieving results as SAX.

*** ONLY FOR SAX2 ***

Parameters:
handler - the content handler implementation (see org.xml.sax.ContentHandler)

setLexicalHandler

public void setLexicalHandler(org.xml.sax.ext.LexicalHandler handler)
Sets a (SAX2) lexical handler to intercept events produced when retrieving results as SAX.

*** ONLY FOR SAX2 ***

Parameters:
handler - the lexical handler implementation (see org.xml.sax.ext.LexicalHandler)

setErrorHandler

public void setErrorHandler(org.xml.sax.ErrorHandler handler)
Sets a (SAX2) error handler to intercept error events produced when retrieving results as SAX.

*** ONLY FOR SAX2 ***

Parameters:
handler - the error handler implementation (see org.xml.sax.ErrorHandler)

getContentHandler

public org.xml.sax.ContentHandler getContentHandler()
Returns the current content handler.

*** ONLY FOR SAX2 ***


getLexicalHandler

public org.xml.sax.ext.LexicalHandler getLexicalHandler()
Returns the current lexical handler.

*** ONLY FOR SAX2 ***


getErrorHandler

public org.xml.sax.ErrorHandler getErrorHandler()
Returns the current error handler.

*** ONLY FOR SAX2 ***


getStatement

public XMLStatement getStatement()
                          throws XMLDBCException
Returns the statement that produced this result set.

Returns:
the XStatement object that produced this XResultSet object.
Throws:
XMLDBCException - if a data source access error occurs.

getMetaData

public XMLDocument getMetaData()
                        throws XMLDBCException
Returns the result set metadata (the XML Schema that models the returned data) as an XMLDocument. This schema describes the XML type of each result in the set.

Returns:
the result set metadata (a XML Schema).
Throws:
XMLDBCException - if a data source access error occurs.

getPrefixMap

public java.util.Map getPrefixMap()
                           throws XMLDBCException
Returns the result set prefix map (as prefix-namespace pairs). This map is used to produce each result in the set.

Returns:
the result set prefix map.
Throws:
XMLDBCException - if a data source access error occurs.

close

public void close()
           throws XMLDBCException
Releases this result set object's resources immediately instead of waiting for this to happen when it is automatically closed.
Note: A XResultSet object is automatically closed by the XStatement object that generated it when that XStatement object is closed, re-executed, or is used to retrieve the next result from a sequence of multiple results.

Throws:
XMLDBCException - if a data source access error occurs.

isBeforeFirst

public boolean isBeforeFirst()
                      throws XMLDBCException
Indicates whether the cursor is before the first result in this result set.

Returns:
true if the cursor is before the first result; false otherwise.
Throws:
XMLDBCException - if a data source access error occurs.

nextAsDocument

public org.w3c.dom.Document nextAsDocument()
                                    throws XMLDBCException
Returns the next result as a DOM2 document and increments by 1 the cursor position. The cursor is initially positioned before the first result; the first call to the method nextAsDOM() makes the first result the current result.

Returns:
the next result (as a DOM level 2 document) of the result set or null if there is no more result in the result set.
Throws:
XMLDBCException - if a data source access error occurs.

nextAsDOM

public org.w3c.dom.Node nextAsDOM()
                           throws XMLDBCException
Deprecated. Prefer nextAsDocument() or nextAsDOM(Element) becuse a result may return multiple root nodes.

Returns the next result as a DOM2 node and increments by 1 the cursor position. The cursor is initially positioned before the first result; the first call to the method nextAsDOM() makes the first result the current result.

Returns:
the next result (as a DOM level 2 node) of the result set or null if there is no more result in the result set.
Throws:
XMLDBCException - if a data source access error occurs.

nextAsDOM

public void nextAsDOM(org.w3c.dom.Element parent)
               throws XMLDBCException
Attaches the next result nodes as children of the Element node passed as a parameter to and increments by 1 the cursor position. The cursor is initially positioned before the first result; the first call to the method nextAsDOM() makes the first result the current result.

Throws:
XMLDBCException - if a data source access error occurs.

nextAsString

public java.lang.String nextAsString()
                              throws XMLDBCException
Returns the next result as an XML string and increments by 1 the cursor position. The cursor is initially positioned before the first result; the first call to the method nextAsString() makes the first result the current result.

Returns:
the next result (as an XML string) of the result set or null if there is no more result in the result set.
Throws:
XMLDBCException - if a data source access error occurs.

nextAsStream

public void nextAsStream(java.io.Writer out)
                  throws XMLDBCException
Returns the next result in a provided character stream and increments by 1 the cursor position. The cursor is initially positioned before the first result; the first call to the method nextAsString() makes the first result the current result.

Parameters:
out - a Writer object assuming user is responsible for the character encoding.
Throws:
XMLDBCException - if a data source access error occurs.

nextAsSAX

public void nextAsSAX()
               throws XMLDBCException,
                      org.xml.sax.SAXException
Returns the next result as a SAX2 event flow and increments by 1 the cursor position. The cursor is initially positioned before the first result; the first call to the method nextAsSAX makes the first result the current result. This method uses the various SAX2 handlers set by the setXXXHandler() methods.

*** ONLY FOR SAX2 ***

Throws:
XMLDBCException - if a data source access error occurs or if user has not set a content handler.
org.xml.sax.SAXException - if a handler exception occurs.

hasNext

public boolean hasNext()
                throws XMLDBCException
Indicates if there is a next Result after the current Result in ResultSet.

Returns:
true if there is a next Result, false otherwise.
Throws:
XMLDBCException - if a data source access error occurs.

getPosition

public int getPosition()
                throws XMLDBCException
Retrieves the current cursor position in ResultSet. The first position is number 1.

Returns:
the current cursor position in ResultSet (-1 if the cursor is not on a Result).
Throws:
XMLDBCException - if a data source access error occurs.

getFragmentsAsDocument

public XMLDocument getFragmentsAsDocument(java.lang.String namespace,
                                          java.lang.String localName,
                                          java.lang.String qName)
                                   throws XMLDBCException
Returns the fragments contained in the result set as a single XML document, with a document root element having the specified namespace, local name and qualified name. Note: this convenience method can only be called if the cursor is before the first element. It will process the complete result set in one step.

Parameters:
namespace - the namespace of the document root element.
localName - the local name of the document root element.
qName - the qualified name of the document root element.
Returns:
an XML document containing the fragments of the result set, as children of the specified document root element.
Throws:
XMLDBCException - if a data source access error occurs.

hasRootTag

public boolean hasRootTag()
Returns:
true if a root tag is present, false otherwise.

isDocument

public boolean isDocument()
Returns:
true if a document is present, false otherwise.

getPSVInfoSetProvider

public org.xquark.schema.validation.PSVInfoSetProvider getPSVInfoSetProvider()
Returns:
the PSVInfoSetProvider if present null otherwise


Copyright © 2004 Université de Versailles Saint-Quentin, XQuark Group. All rights reserved.