com.simba.dsi.dataengine.interfaces
Interface IResultSet

All Known Implementing Classes:
DSIEmptyResultSet, DSIExtResultSet, DSIMetadataOnlyResultSet, DSIMetadataResultSet, DSISimpleResultSet

public interface IResultSet

An IResultSet exposes metadata and data for a result set generated by a query. The column metadata may be requested before the corresponding query is executed. Character and binary data may be retrieved in chunks. An IResultSet holds an internal cursor used to traverse rows of the result set in sequential order. After execution, the IResultSet's internal cursor is expected to be positioned before the first row of results.


Field Summary
static int CURSOR_POSITION_BEFORE
          Constant indicating that the internal (client) cursor is positioned before the result set
static long RETRIEVE_ALL_DATA
          Special value that may be passed in as maxSize to IResultSet.getData() in order to indicate that all data at the corresponding cell should be retrieved.
static long ROW_COUNT_UNKNOWN
          Used in Execute() to indicate that the row count is not known
 
Method Summary
 void appendRow()
          Append an empty row to the end of the result set.
 void close()
          Closes the ResultSet and releases any resources held by it.
 void closeCursor()
          Closes the result set's internal cursor.
 void deleteRow()
          Delete the current row from the result set.
 boolean getData(int column, long offset, long maxSize, DataWrapper retrievedData)
          Fills in retrievedData with the corresponding chunk of data.
 boolean getDataNeeded(int column)
          Indicates whether getData() might be called on the given column after the next call to moveToNextRow().
 int getFetchSize()
          Retrieves the fetch size being used for this ResultSet.
 long getRowCount()
          Returns the number of rows in the result set.
 java.util.ArrayList<? extends IColumn> getSelectColumns()
          Returns an ArrayList of ColumnMetadatas, corresponding to the columns for which data is provided in the result set.
 boolean hasMoreRows()
          Returns true if the ResultSet has more rows to fetch.
 boolean hasRowCount()
          Determine if the number of rows is known or not.
 boolean moveToNextRow()
          Moves the result set's internal cursor to the next row.
 void onFinishRowUpdate()
          Indicate that the current row is finished having data written to it.
 void onStartRowUpdate()
          Indicate that the current row is about to have data written to it.
 void registerWarningListener(com.simba.support.IWarningListener listener)
          Registers a warning listener for allowing the IResultSet to post warnings.
 boolean rowDeleted()
          Retrieves whether the current row has been deleted.
 boolean rowInserted()
          Retrieves whether the current row has been inserted.
 boolean rowUpdated()
          Retrieves whether the current row has been updated.
 void setCursorType(CursorType cursorType)
          Sets the type of the cursor to be used for traversing over the result set.
 void setDataNeeded(int column, boolean isDataNeeded)
          Indicates whether getData() might be called on the given column after the next call to moveToNextRow().
 void setFetchSize(int fetchSize)
          Sets the fetch size being used for this ResultSet.
 boolean supportsHasMoreRows()
          Method to notify the JDBC layer if this resultset can support checking if there is a next row through the method hasMoreRows().
 boolean writeData(int column, DataWrapper data, long offset, boolean isDefault)
          Write data to a column in the current row and specified column.
 

Field Detail

RETRIEVE_ALL_DATA

static final long RETRIEVE_ALL_DATA
Special value that may be passed in as maxSize to IResultSet.getData() in order to indicate that all data at the corresponding cell should be retrieved.

See Also:
Constant Field Values

ROW_COUNT_UNKNOWN

static final long ROW_COUNT_UNKNOWN
Used in Execute() to indicate that the row count is not known

See Also:
Constant Field Values

CURSOR_POSITION_BEFORE

static final int CURSOR_POSITION_BEFORE
Constant indicating that the internal (client) cursor is positioned before the result set

See Also:
Constant Field Values
Method Detail

appendRow

void appendRow()
               throws com.simba.support.exceptions.ErrorException
Append an empty row to the end of the result set. The cursor should be positioned on the newly appended row when the function returns.

Throws:
com.simba.support.exceptions.ErrorException - if the result does not support updating.

close

void close()
Closes the ResultSet and releases any resources held by it.

An IResultSet is closed: - just before the parent IQueryExecutor is closed, if the result set was generated by executing a query. - during a call to SQLCancel(), SQLCloseCursor() or SQLFreeStmt(SQL_CLOSE) while dealing with metadata results. - just before preparing a new query or generating a new metadata result on the parent statement while dealing with metadata results.


closeCursor

void closeCursor()
                 throws com.simba.support.exceptions.ErrorException
Closes the result set's internal cursor. After a call to this method, no more calls will be made to moveToNextRow() and getData().

This method will not be called until IQueryExecutor.execute() has been called on the corresponding IQueryExecutor.

Throws:
com.simba.support.exceptions.ErrorException - If an error occurs

deleteRow

void deleteRow()
               throws com.simba.support.exceptions.ErrorException
Delete the current row from the result set. The cursor should be positioned on the previous row when the function returns, so that the next call to Move() would move to the row after the deleted row.

Throws:
com.simba.support.exceptions.ErrorException - if the result does not support updating.

getData

boolean getData(int column,
                long offset,
                long maxSize,
                DataWrapper retrievedData)
                throws com.simba.support.exceptions.ErrorException
Fills in retrievedData with the corresponding chunk of data. retrievedData is an uninitialized DataWrapper, and must be modified by this call.

Data is requested from column for the row that the internal cursor is currently positioned at. column is given as a 0-based index, matching the index of the corresponding column metadata in the ArrayList returned by getSelectColumns().

For character and binary data types, offset is used to indicate an offset within the data cell from which to begin the retrieved chunk. maxSize is used to indicate the suggested maximum size of the retrieved data chunk. offset and maxSize are both given in bytes, and should have no effect when retrieving fixed-width data. Please note that since sql_*char data is returned in the UTF-16 encoding, each codepoint is two bytes, so both maxSize and offset should be divided by two to interpret them as # of codepoints. The value RETRIEVE_ALL_DATA may be provided as maxSize to indicate that all available data is to be retrieved.

The return value indicates if there is more data left in the current cell. The return value should always be false when retrieving data of a fixed-width type.

If the driver attribute DSI_RETRIEVE_DATA_ORDER_RESTRICTION is set to DSI_RETRIEVE_DATA_IN_NONDECREASING_ORDER, data will only be requested from a row in non-decreasing column order. Data within a single cell will always be requested in increasing offset order, with no chunk overlap.

When requesting chunks of character and binary data, maxSize will typically match the chunk size specified in the DSI_MAXIMUM_RETRIEVE_DATA_CHUNK_SIZE driver attribute when it isn't set to RETRIEVE_ALL_DATA.

This method will not be called until IQueryExecutor.execute() has been called on the corresponding IQueryExecutor.

Parameters:
column - 0-based column index.
offset - Data offset in bytes.
maxSize - Suggested data chunk size in bytes, or RETRIEVE_ALL_DATA.
retrievedData - Holder for retrieved data.
Returns:
true if more data is left in the current cell; false otherwise. Return value should always be false when retrieving data of a fixed-width type.
Throws:
com.simba.support.exceptions.ErrorException - if an error occurs.
See Also:
DataWrapper

getDataNeeded

boolean getDataNeeded(int column)
Indicates whether getData() might be called on the given column after the next call to moveToNextRow().

Parameters:
column - A column index. The first column uses index 0.
Returns:
true if data may be retrieved from the given column; false otherwise.

getFetchSize

int getFetchSize()
                 throws com.simba.support.exceptions.ErrorException
Retrieves the fetch size being used for this ResultSet.

Returns:
the number of rows to attempt to fetch at a time.
Throws:
com.simba.support.exceptions.ErrorException - if an error occurs.

getRowCount

long getRowCount()
                 throws com.simba.support.exceptions.ErrorException
Returns the number of rows in the result set. The value returned is undefined if the row count is unknown, in which case hasRowCount() should return false.

The value returned must fit into a 32-bit integer when targeting a 32-bit platform, or a 64-bit integer for a 64-bit platform. The value must be non-negative, except if the row count is unknown.

This method will not be called until IQueryExecutor.execute() has been called on the corresponding IQueryExecutor.

Returns:
Number of rows in the result set.
Throws:
com.simba.support.exceptions.ErrorException - If an error occurs.

getSelectColumns

java.util.ArrayList<? extends IColumn> getSelectColumns()
                                                        throws com.simba.support.exceptions.ErrorException
Returns an ArrayList of ColumnMetadatas, corresponding to the columns for which data is provided in the result set. Even if there are no rows in the result set, the column metadata should still be accurate. Position in the ArrayList should match position in the result set. The first column should be found at position 0, the second at 1, and so on.

Returns:
An ArrayList of ColumnMetadatas describing the columns in the result set.
Throws:
com.simba.support.exceptions.ErrorException - If an error occurs.

hasMoreRows

boolean hasMoreRows()
                    throws com.simba.support.exceptions.ErrorException
Returns true if the ResultSet has more rows to fetch. Returns false if there are no more rows to fetch.

A driver can choose not to support this method by returning false from supportsHasMoreRows(). A Driver might choose to not support this method if it is difficult / costly to determine if there is a next row. In this case, this method will not be called by the JDBC layer.

If this method is not supported, the JDBC API method ResultSet.isLast() will throw a SQLException if it is called by the application.

Returns:
true if there are more rows to fetch, false otherwise.
Throws:
com.simba.support.exceptions.ErrorException - If an error occurs.

hasRowCount

boolean hasRowCount()
Determine if the number of rows is known or not.

Returns:
true if the number of rows is known, false otherwise.

moveToNextRow

boolean moveToNextRow()
                      throws com.simba.support.exceptions.ErrorException
Moves the result set's internal cursor to the next row. Initially, the cursor should be placed before the first row, so the first call to moveToNextRow() moves it to the first row. The return value indicates if the move was successful or not.

This method will not be called until IQueryExecutor.execute() has been called on the corresponding IQueryExecutor.

Returns:
true if the move was successful, false if there is not another row left to move to.
Throws:
com.simba.support.exceptions.ErrorException - If an error occurs.

onFinishRowUpdate

void onFinishRowUpdate()
                       throws com.simba.support.exceptions.ErrorException
Indicate that the current row is finished having data written to it.

Throws:
com.simba.support.exceptions.ErrorException - If there is an error writing the row that cannot be determined until all of the data for the row has been written through calls to writeData(int, DataWrapper, long, boolean). If an error happens when writing a particular column, the preferred behaviour is to throw an exception from writeData.

onStartRowUpdate

void onStartRowUpdate()
Indicate that the current row is about to have data written to it. Note that when AppendRow() is called, OnStartRowUpdate() will not be called as it is implied that the newly added row will be updated.


registerWarningListener

void registerWarningListener(com.simba.support.IWarningListener listener)
Registers a warning listener for allowing the IResultSet to post warnings.

Parameters:
listener - The listener to register with this IResultSet.

rowDeleted

boolean rowDeleted()
Retrieves whether the current row has been deleted.

Returns:
True if the current row has been deleted; false otherwise.

rowInserted

boolean rowInserted()
Retrieves whether the current row has been inserted.

Returns:
True if the current row has been inserted; false otherwise.

rowUpdated

boolean rowUpdated()
Retrieves whether the current row has been updated.

Returns:
True if the current row has been updated; false otherwise.

setCursorType

void setCursorType(CursorType cursorType)
                   throws com.simba.support.exceptions.ErrorException
Sets the type of the cursor to be used for traversing over the result set.

This method must be called before calling move(), otherwise the cursor type used is undefined.

Parameters:
cursorType - The type of cursor used to traverse the result set.
Throws:
com.simba.support.exceptions.ErrorException - if the cursor type is not supported.

setDataNeeded

void setDataNeeded(int column,
                   boolean isDataNeeded)
Indicates whether getData() might be called on the given column after the next call to moveToNextRow(). The value given here applies for any subsequent moveToNextRow() calls.

Parameters:
column - A column index. The first column uses index 0.
isDataNeeded - Indicates whether data may be retrieved from the given column.

setFetchSize

void setFetchSize(int fetchSize)
                  throws com.simba.support.exceptions.ErrorException
Sets the fetch size being used for this ResultSet. This may be ignored in favour of using a preferred default.

If the specified fetch size is zero, the default fetch size will automatically be used.

Parameters:
fetchSize - the number of rows to attempt to fetch at a time.
Throws:
com.simba.support.exceptions.ErrorException - if an error occurs.

supportsHasMoreRows

boolean supportsHasMoreRows()
Method to notify the JDBC layer if this resultset can support checking if there is a next row through the method hasMoreRows(). This method should consistently return the same value per instance.

Returns:
true if hasMoreRows() is supported; false otherwise.

writeData

boolean writeData(int column,
                  DataWrapper data,
                  long offset,
                  boolean isDefault)
                  throws com.simba.support.exceptions.ErrorException
Write data to a column in the current row and specified column. Note that if isDefault is true, then data will be null, and offset should be ignored.

Parameters:
column - The column to write data to.
data - The container for the data to write.
offset - The offset into the column to start writing data at. This is in units of bytes, so it should be divided by two to be interpreted in units of codepoints for sql_*char columns, since they are in the UTF-16 encoding.
isDefault - Flag indicating that the default value should be used for the column.
Returns:
true if data is truncated; false otherwise.
Throws:
com.simba.support.exceptions.ErrorException - if the column is invalid, the offset is invalid or will result in data overflowing the boundaries of the column, or if the result does not support updating.


Copyright © 2006-2014 Simba Technologies Incorporated. All Rights Reserved.