com.bluestream.xdb
Interface XResultSet

public interface XResultSet

This class represents the results of a Query.

// Initialize.
SystemManager.init();

// Get the server.  Note that you might have to add a server first,
// if this is your first time connecting.
Server srv = SystemManager.getServer("MyServer");

// Set up a login object.
AuthenticationInfo ai = new AuthenticationInfo("foo", "foopass");

// Get a connection.
XConnection xc = srv.getConnection(ai);

// Build up a query.  This one just lists Database roots.
String qry = "FOR $a IN root('testDB', 'Mytest') RETURN $a";

// Begin a transaction.
xc.beginTransaction();

// Get a statement object.
XStatement xs = xc.createStatement();

// Voila, the result.
XResultSet result = xs.execute(qry, XStatement.SF_DEFAULT);

// ... work with the results.
FlexStringBuffer fsb = new FlexStringBuffer();

// Get into position... - it defaults to first so you can omit this.
result.beforeFirst();

while (result.nextValue()) {
    result.fsbGet(fsb, false);
}
// Close the statement.
xs.close();
// Close the transaction.
xc.commiTransaction();
// Close the connection.
xc.close();
// Exit completely.
SystemManager.shutdown();

// At this point, remember that the results are in fsb.

Method Summary

void	beforeFirst() Set the position to one before the first result.
void	close() Release the resources used by this result set.
void	emit() emit the current value to the registered docHandler.
void	emitAll() Emit the entire result set to the registered docHandler.
void	fsbGet(FlexStringBuffer fsb, boolean bAppend) Get the current value as a string buffer.
void	fsbGetAll(FlexStringBuffer fsb, boolean bAppend) Get all the values in this result - effectively get all results.
BigDecimal	getBigDecimal(String path) Gets the value of the designated column in the current row of this ResultSet object as a BigDecimal.
InputStream	getBinaryStream(String path) Retrieve the value at the given path as an InputStream of binary values.
boolean	getBoolean(String path, com.bluestream.sys.util.BooleanWrap isNull) Gets the value of the designated column in the current row of this ResultSet object as a boolean in the Java programming language.
String	getCDataText(String path) Gets the value of the CDATA text of the designated column in the current row of this ResultSet object as a String.
Date	getDate(String path) Gets the value of the designated column in the current row of this ResultSet object as a Date.
void	getDocId(FlexStringBuffer docIdStr) return the document id as an opaque string identifier.
void	getDocNum(FlexStringBuffer docNum) Get the document number for the current document.
byte	getEntityEncoding() Returns the current setting of the Entity Encoding property for this ResultSet.
boolean	getFSB(String path, FlexStringBuffer fsb) Gets the value of the designated column in the current row of this ResultSet object as a String.
int	getInt(String path, com.bluestream.sys.util.BooleanWrap isNull) Gets the value of the designated column in the current row of this ResultSet object as an int in the Java programming language.
long	getLong(String path, com.bluestream.sys.util.BooleanWrap isNull) Gets the value of the designated column in the current row of this ResultSet object as a long in the Java programming language.
String	getString() Get String is for those who want the value returned as a String.
String	getString(String path) Gets the value of the designated column in the current row of this ResultSet object as a String.
boolean	nextValue() Position the result set to the next value in this result set.
void	registerDocHandler(XDBDocHandler docHandler) Register a user provided docHandler as the target for SAX like events.
void	registerSaxHandler(org.xml.sax.ContentHandler contentHandler, org.xml.sax.ext.LexicalHandler lexicalHandler) Register a user provided content and lexical Handlers as the target for SAXevents.
void	setEntityEncoding(String enc) Configure the ResultSet to encode all entities in returned results.
void	setXHTMLTransMode(boolean flag)
int	skipValues(int skipCount) From the current position in the result set, skip the number of values specified in skipCount.
void	xdmValueGetAll(com.bluestream.sys.xml.xdm.XDMValue xdmValue) Get all the values in the ResultSet as an XDMValue.

Method Detail

setEntityEncoding

public void setEntityEncoding(String enc)

Configure the ResultSet to encode all entities in returned results. Specifying this property is optional as all ResultSets are initialized with DEFAULT.

Parameters:

enc - a String which can be one of these values:

• NONE - they will be left as Unicode characters.
• DEFAULT - use the default entity encoding indicated by the system properties:
  • XDBClient.Entity.Encoding - may be ON or OFF
  • XDBClient.Entity.Encoding.Format - may be HEX or DECIMAL
• HEX - Unicode characters whose values are > 0x7F will be encoded as entities using hexadecimal character references.
• DECIMAL - Unicode values whose values are > 0x7F will be encoded as entities using decimal character references.

If the encoding string is not one of the above valid values, an XDBException will be thrown with error code: EC_InvalidArg.

getEntityEncoding

public byte getEntityEncoding()

Returns the current setting of the Entity Encoding property for this ResultSet.

See Also:

setEntityEncoding(java.lang.String)

setXHTMLTransMode

public void setXHTMLTransMode(boolean flag)

beforeFirst

public void beforeFirst()
                 throws XDBException

Set the position to one before the first result.

Throws:

XDBException

nextValue

public boolean nextValue()
                  throws XDBException

Position the result set to the next value in this result set. This value becomes the current value.

Returns:

true, for success; false, for end reached

Throws:

XDBException - - EC_DeadLockRollBack: A deadlock occurred and this thread, as the victim, was rolled back to break deadlock. Transaction will be rolled back. - EC_DuplicateKeyFound: An attempt to insert a duplicate key into an index was detected. The transaction will be rolled back to recover from this. - EC_SchemaValidation: A schema validation failed. The transaction will be rolled back to recover from this. - EC_AccessedDenied: Access to perform this operation has been denied, the transaction will be rolled back automatically. - EC_Deleted: A request was made to delete a document that is already deleted. Transaction will be rolled back automatically.

skipValues

public int skipValues(int skipCount)
               throws XDBException

From the current position in the result set, skip the number of values specified in skipCount. Calling skipValues(n) is the same as executing nextValue n times except skipValues(n) is faster since the skipping is done on the server. If the skipCount is larger than the number of remaining values in the result set then the skip will skip to the end and return the actual number of values skipped in the numberSkipped return value.

Returns:

numberSkipped. This is the number of values actually skipped. Often numberSkipped == skipCount unless the end of the result set is reached.

Throws:

XDBException - - EC_DeadLockRollBack: A deadlock occurred and this thread, as the victim, was rolled back to break deadlock. Transaction will be rolled back. - EC_DuplicateKeyFound: An attempt to insert a duplicate key into an index was detected. The transaction will be rolled back to recover from this. - EC_SchemaValidation: A schema validation failed. The transaction will be rolled back to recover from this. - EC_AccessedDenied: Access to perform this operation has been denied, the transaction will be rolled back automatically. - EC_Deleted: A request was made to delete a document that is already deleted. Transaction will be rolled back automatically.

fsbGet

public void fsbGet(FlexStringBuffer fsb,
                   boolean bAppend)
            throws XDBException

Get the current value as a string buffer. A value can be a node or a simpleValue. This follows the XQuery data model.

Throws:

XDBException

getString

public String getString()
                 throws XDBException

Get String is for those who want the value returned as a String.

Returns:

strValue. Newly allocated string with the value.

Throws:

XDBException

getBinaryStream

public InputStream getBinaryStream(String path)
                            throws XDBException

Retrieve the value at the given path as an InputStream of binary values. The InputStream is only valid for this row. Any call to nextValue() will automatically close the InputStream.

Returns:

InputStream: This will be closed on the next call to nextValue() and may be re-used at that time. If the value at this path is 0 length, then the returned InputStream will be null.

Throws:

xdbEx - - SysErr.EC_MissingPath: The path specified does not occur in the current value.

XDBException

getLong

public long getLong(String path,
                    com.bluestream.sys.util.BooleanWrap isNull)
             throws XDBException

Gets the value of the designated column in the current row of this ResultSet object as a long in the Java programming language.

Returns:

long: If the value at this path is 0 length, then the long value returned will be 0.

Throws:

XDBException - - SysErr.EC_MissingPath: The path specified does not occur in the current value.

getInt

public int getInt(String path,
                  com.bluestream.sys.util.BooleanWrap isNull)
           throws XDBException

Gets the value of the designated column in the current row of this ResultSet object as an int in the Java programming language.

Returns:

int: If the value at this path is 0 length, then the int value returned will be 0.

Throws:

XDBException - - SysErr.EC_MissingPath: The path specified does not occur in the current value.

getBoolean

public boolean getBoolean(String path,
                          com.bluestream.sys.util.BooleanWrap isNull)
                   throws XDBException

Gets the value of the designated column in the current row of this ResultSet object as a boolean in the Java programming language.

Returns:

boolean: If the value at this path is 0 length, then the boolean value returned will be false. Valid boolean string values are "true" and "false"

Throws:

XDBException - - SysErr.EC_MissingPath: The path specified does not occur in the current value.

getDate

public Date getDate(String path)
             throws XDBException

Gets the value of the designated column in the current row of this ResultSet object as a Date.

Returns:

date: If the value at this path is 0 length, then the returned date value is null.

Throws:

XDBException - - SysErr.EC_MissingPath: The path specified does not occur in the current value.

getBigDecimal

public BigDecimal getBigDecimal(String path)
                         throws XDBException

Gets the value of the designated column in the current row of this ResultSet object as a BigDecimal.

Returns:

bigDecimal: Return the big decimal value from the underlying compatible value. If the value at this path is 0 length, then null is returned.

Throws:

XDBException - - SysErr.EC_MissingPath: The path specified does not occur in the current value.

getString

public String getString(String path)
                 throws XDBException

Gets the value of the designated column in the current row of this ResultSet object as a String.

Returns:

string: Return the string value from the underlying compatible value. There is currently no way to distinguish between an empty string and a null value, so empty string is returned.

Throws:

XDBException - - SysErr.EC_MissingPath: The path specified does not occur in the current value.

getCDataText

public String getCDataText(String path)
                    throws XDBException

Gets the value of the CDATA text of the designated column in the current row of this ResultSet object as a String.

Returns:

string: Return the string value from the underlying compatible value. There is currently no way to distinguish between an empty string and a null value, so empty string is returned.

Throws:

XDBException - - SysErr.EC_MissingPath: The path specified does not occur in the current value.

getFSB

public boolean getFSB(String path,
                      FlexStringBuffer fsb)
               throws XDBException

Gets the value of the designated column in the current row of this ResultSet object as a String. This flavor of the call allows you to re-use the same fsb instance over and over.

Returns:

isNotNull: This is reserved for future use when we can determine the difference between NULL and empty string. For now, the return is always true.

Throws:

XDBException - - SysErr.EC_MissingPath: The path specified does not occur in the current value.

emit

public void emit()
          throws XDBException

emit the current value to the registered docHandler.

Throws:

XDBException

fsbGetAll

public void fsbGetAll(FlexStringBuffer fsb,
                      boolean bAppend)
               throws XDBException

Get all the values in this result - effectively get all results.

Throws:

XDBException

xdmValueGetAll

public void xdmValueGetAll(com.bluestream.sys.xml.xdm.XDMValue xdmValue)
                    throws XDBException

Get all the values in the ResultSet as an XDMValue. This may result in a sequence, node or SimpleValue. This follows the XQuery data model.

Throws:

XDBException

emitAll

public void emitAll()
             throws XDBException

Emit the entire result set to the registered docHandler.

Throws:

XDBException - - EC_DeadLockRollBack: A deadlock occurred and this thread, as the victim, was rolled back to break deadlock. Transaction will be rolled back. - EC_DuplicateKeyFound: An attempt to insert a duplicate key into an index was detected. The transaction will be rolled back to recover from this. - EC_SchemaValidation: A schema validation failed. The transaction will be rolled back to recover from this. - EC_AccessedDenied: Access to perform this operation has been denied, the transaction will be rolled back automatically. - EC_Deleted: A request was made to delete a document that is already deleted. Transaction will be rolled back automatically.

registerDocHandler

public void registerDocHandler(XDBDocHandler docHandler)
                        throws XDBException

Register a user provided docHandler as the target for SAX like events. In order to start the event stream one of the emit calls below has to be made. This cannot be done unless ContentHandler, as registered below in registerSaxHandler, is null which is the default.

Throws:

XDBException

registerSaxHandler

public void registerSaxHandler(org.xml.sax.ContentHandler contentHandler,
                               org.xml.sax.ext.LexicalHandler lexicalHandler)
                        throws XDBException

Register a user provided content and lexical Handlers as the target for SAXevents. In order to start the event stream one of the emit calls below has to be made. This cannot be done unless XDBDocHandler, as registered above in registerDocHandler, is null which is the default.

Throws:

XDBException

getDocId

public void getDocId(FlexStringBuffer docIdStr)
              throws XDBException

return the document id as an opaque string identifier. Note that this method is only defined on Document node sets. The document id string may be used to subsequently update the document through either the REPLACE DOCUMENT or the DELETE DOCUMENT statements. Examples: 1) REPLACE DOCUMENT WITH Expression 2) DELETE DOCUMENT

Throws:

XDBException: - thrown if the current node is not a Document node.

XDBException

getDocNum

public void getDocNum(FlexStringBuffer docNum)
               throws XDBException

Get the document number for the current document. This function only works on result sets that return the entire document. Note: for foreign keys use DocNum or some other id but not DocumentId.

Throws:

XDBException

close

public void close()
           throws XDBException

Release the resources used by this result set. This call is not necessary as a close will automatically happen when the associated XStatement is closed, or when the associated XStatement issues execute again.

Throws:

XDBException