DSIExtResultSet Class Reference

An abstract class that represents a result set from the DSII. More...

Inherits Simba::DSI::IResult, Simba::DSI::IBookmarkable, and Simba::Support::UnsafeSharedObject.

Inherited by DSIExtSimpleResultSet.

List of all members.

Public Types

enum  DMLType { DML_INSERT, DML_UPDATE, DML_DELETE }

Public Member Functions

virtual void AppendRow ()
 Append an empty row to the end of the result set.
virtual simba_unsigned_native BulkFetch (simba_unsigned_native in_rowsetSize, const std::vector< Simba::DSI::IBulkProcessor * > &in_bulkProcessors)
virtual void CreateIndex (const simba_wstring &in_name, std::vector< DSIExtIndexColumn > &in_columns, const simba_wstring &in_type, bool in_isUnique)
 Create an index on the table represented by this ResultSet.
virtual void DeleteRow ()
 Delete the current row from the result set.
virtual void DropIndex (const IIndexMetadata *in_index)
 Drop the given index from the table represented by this ResultSet.
virtual void GetBookmark (simba_byte *out_bookmark)
 Retrieve a bookmark uniquely identifying the current row.
virtual simba_uint16 GetBookmarkSize ()
 Retrieve the length in bytes of the bookmark on the table.
virtual void GetCatalogName (simba_wstring &out_catalogName)=0
 Get the catalog name of the table.
virtual const IIndexMetadataListGetIndexes () const =0
 Get the indexes for this result set.
virtual Simba::DSI::ResultType GetResultType ()
 Get the result type.
virtual void GetSchemaName (simba_wstring &out_schemaName)=0
 Get the schema name of the table.
virtual void GetTableName (simba_wstring &out_tableName)=0
 Get the name of the table.
virtual bool GotoBookmark (const simba_byte *in_bookmark)
 Move the cursor to the row identified by the given bookmark.
virtual bool HasRowCount ()=0
 Indicate whether the table has the row count information.
virtual bool IsBulkFetchSupported (std::set< simba_uint32 > &in_boundColumnIndex)
 Determine if the DSII can support bulk fetching for the current query and the given list of bound columns.
virtual bool IsOffsetSupported ()
 Indicate whether fetching offset is supported in the Move(...) method.
virtual Simba::DSI::ICellmarkMarkCell (simba_uint16 in_column)
 Returns a cellmark to the column of the row at which the cursor is positioned.
virtual void OnFinishDMLBatch (AutoPtr< IResult > &out_generatedKeys)
 Indicate that the current DML batch (started with OnStartDMLBatch()) is done.
virtual void OnFinishDMLBatch ()
 Indicate that the current DML batch (started with OnStartDMLBatch()) is done.
virtual void OnFinishRowUpdate ()
 Indicate that the current row is finished having data written to it.
virtual void OnStartDMLBatch (DMLType in_dmlType, simba_unsigned_native in_numAffectedRows, const std::vector< simba_uint16 > &in_generatedColumns)
 Indicate that the SDK is about to perform a batch of DML operations on this table.
virtual void OnStartDMLBatch (DMLType in_dmlType, simba_unsigned_native in_numAffectedRows)
 Indicate that the SDK is about to perform a batch of DML operations on this table.
virtual void OnStartRowUpdate ()
 Indicate that the current row is about to have data written to it.
virtual AutoPtr< DSIExtIndexOpenIndex (const IUseableIndexMetadata *in_indexMeta, bool in_mustKeepOrder=false, bool in_mustSupplyBookmarks=false)=0
 Create and return an DSIExtIndex object to use for indexing this DSIExtResultSet.
virtual void Reset ()=0
 Resets the cursor to before the first row.
virtual simba_uint16 ResolveColumn (SharedPtr< DSIExtResultSet > in_table, simba_uint16 in_colIndex)
 Resolve the column reference that refers the given table to this result set.
virtual void SetBookmarkSource (DSIExtBookmarkSource *in_bookmarkSource)=0
 Set a bookmark source on this result set.
virtual void SetFetchRowsetSize (simba_unsigned_native in_rowsetSize)
 Sets the number of rows that are to be fetched to the client application.
virtual bool WriteData (simba_uint16 in_column, SqlData *in_sqlData, simba_signed_native in_offset, bool in_isDefault)
 Write data to a column in the current row and specified column.

Protected Member Functions

 DSIExtResultSet ()
 Constructor.
virtual ~DSIExtResultSet ()
 Destructor.

Detailed Description

An abstract class that represents a result set from the DSII.

A concrete implementation of this abstract class could represent,

  1. A physical table or view from the data store, or
  2. The filtered result if the DSII supports passing down FILTERs, or
  3. The joined result if the DSII supports passing down JOINs, or
  4. The aggregated result if the DSII supports passing down AGGREGATIONs, or
  5. The projected result if the DSII supports passing down PROJECTIONs, etc.

NOTE: This class inherits extends from the UnsafedSharedObject base class so that a pointer object of this class can be managed by an SharedPtr.


Member Enumeration Documentation

enum DMLType
Enumerator:
DML_INSERT 
DML_UPDATE 
DML_DELETE 

Constructor & Destructor Documentation

DSIExtResultSet (  )  [protected]

Constructor.

virtual ~DSIExtResultSet (  )  [inline, protected, virtual]

Destructor.

The destructor is protected to prevent client code from explicitly using delete instead of calling Release() to release the resources.


Member Function Documentation

virtual void AppendRow (  )  [virtual]

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.

Exceptions:
SEInvalidOperationException if the table does not support updating.
SEInvalidOperationException if the table was opened as read-only.
virtual simba_unsigned_native BulkFetch ( simba_unsigned_native  in_rowsetSize,
const std::vector< Simba::DSI::IBulkProcessor * > &  in_bulkProcessors 
) [virtual]
virtual void CreateIndex ( const simba_wstring in_name,
std::vector< DSIExtIndexColumn > &  in_columns,
const simba_wstring in_type,
bool  in_isUnique 
) [virtual]

Create an index on the table represented by this ResultSet.

Parameters:
in_name The name of the index.
in_columns The columns included in the index. The columns are supplied in the order that the index should be created.
in_type The type of the index, can be a NULL wstring.
in_isUnique True if the index is unique.
virtual void DeleteRow (  )  [virtual]

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.

Exceptions:
SEInvalidOperationException if the table does not support updating.
SEInvalidOperationException if the table was opened as read-only.
virtual void DropIndex ( const IIndexMetadata in_index  )  [virtual]

Drop the given index from the table represented by this ResultSet.

Parameters:
in_index The metadata of the index to drop. (NOT OWN)
virtual void GetBookmark ( simba_byte *  out_bookmark  )  [virtual]

Retrieve a bookmark uniquely identifying the current row.

The size of the bookmark should always be that of returned by GetBookmarkSize().

This default implementation simply throws an SEInvalidOperationException to indicate that bookmarks are not supported. Sub-classes should override this implementation to add support for bookmarks if desired.

Parameters:
out_bookmark The output buffer for the bookmark. The length of the buffer is assumed to be greater than or equal to the bookmark size.
Exceptions:
SEInvalidOperationException if bookmarks are not supported.

Implements IBookmarkable.

virtual simba_uint16 GetBookmarkSize (  )  [virtual]

Retrieve the length in bytes of the bookmark on the table.

This method can be called before SetCursorType() is called.

If the table does not support bookmarks, this method returns BOOKMARK_NOT_SUPPORTED.

This default implementation simply returns BOOKMARK_NOT_SUPPORTED. Sub-classes should override this implementation to add support for bookmarks if desired.

Returns:
The length of the bookmark in bytes if bookmark is supported, BOOKMARK_NOT_SUPPORTED otherwise.

Implements IBookmarkable.

virtual void GetCatalogName ( simba_wstring out_catalogName  )  [pure virtual]

Get the catalog name of the table.

If catalog is not supported, out_catalogName will be empty after the method is returned.

Parameters:
out_catalogName The catalog name.
virtual const IIndexMetadataList& GetIndexes (  )  const [pure virtual]

Get the indexes for this result set.

Return an empty collection of indexes if indexes are not supported.

Returns:
The indexes for this result set.

Implemented in DSIExtSimpleResultSet.

virtual Simba::DSI::ResultType GetResultType (  )  [virtual]

Get the result type.

Since a table is always a result set, this method always returns RESULT_SET. All sub-classes should _not_ attempt to override this method.

Returns:
RESULT_SET always.

Implements IResult.

virtual void GetSchemaName ( simba_wstring out_schemaName  )  [pure virtual]

Get the schema name of the table.

If catalog is not supported, out_schemaName will be empty after the method is returned.

Parameters:
out_schemaName The schema name.
virtual void GetTableName ( simba_wstring out_tableName  )  [pure virtual]

Get the name of the table.

Parameters:
out_tableName The name of the table.
virtual bool GotoBookmark ( const simba_byte *  in_bookmark  )  [virtual]

Move the cursor to the row identified by the given bookmark.

NOTE: The bookmark should have been obtained through GetBookmark() and the size of the bookmark is of that returned by GetBookmarkSize().

This default implementation simply throws an SEInvalidOperationException always to indicate that bookmarks are not supported. Sub-classes should override this implementation to add support for bookmarks if desired.

Parameters:
in_bookmark The bookmark uniquely identifying a row in the table.
Exceptions:
SEInvalidOperationException if bookmark is not supported.
DSIException if the given bookmark is invalid.
Returns:
true if successfully moved to the bookmarked row, false otherwise.

Implements IBookmarkable.

virtual bool HasRowCount (  )  [pure virtual]

Indicate whether the table has the row count information.

Without this information, certain query optimization (for example, join optimization) can not be performed.

Returns:
true if the row count is known for this result set.

Implements IResult.

virtual bool IsBulkFetchSupported ( std::set< simba_uint32 > &  in_boundColumnIndexes  )  [virtual]

Determine if the DSII can support bulk fetching for the current query and the given list of bound columns.

Parameters:
in_boundColumnIndexes Set containing the indexes of all bound columns (meaning the column values are 0-based).
Returns:
true if the DSII supports bulk fetch; false otherwise.

Implements IResult.

virtual bool IsOffsetSupported (  )  [virtual]

Indicate whether fetching offset is supported in the Move(...) method.

This method is designed for optimization. Although SimbaEngine could support fetch offset even the underlying data store does not support it, it is more efficient if the data store supports it directly in certain situations such as the following,

  • Simple fetching everything from a table (i.e., SELECT * FROM T)
  • Fetching a subset of columns without filtering (i.e., SELECT C1,C2 FROM T)

The default implementation here always return false to indicate that Move() with an offset is not supported.

Returns:
True if supports fetch offset, false otherwise.
virtual Simba::DSI::ICellmark* MarkCell ( simba_uint16  in_column  )  [virtual]

Returns a cellmark to the column of the row at which the cursor is positioned.

This default implementation always throws an SEInvalidOperationException. Sub-classes should override this function if cellmarks are supported.

If an implementation does not support cellmarking, it should _NOT_ throw an exception for performance reasons. It should simply return NULL.

Parameters:
in_column A column index for this cellmark. The first column uses index 0.
Returns:
A cellmark to mark the column of the row if supported and is a success, NULL otherwise. (OWN)

Implements IResult.

Reimplemented in DSIExtSimpleResultSet.

virtual void OnFinishDMLBatch ( AutoPtr< IResult > &  out_generatedKeys  )  [virtual]

Indicate that the current DML batch (started with OnStartDMLBatch()) is done.

Parameters:
out_generatedKeys Output parameter for retrieving the generated keys requested in the matching call to OnStartDMLBatch().

Will be provided with a result if and only if the matching call to OnStartDMLBatch() provided a non-empty 'in_generatedColumns' parameter. Otherwise will be set to NULL.

The SQLEngine guarantees the returned IResult will be destroyed before this DSIExtResultSet.

Note: The default implementation of this method calls OnFinishDMLBatch() and clears out_generatedKeys.

virtual void OnFinishDMLBatch (  )  [virtual]

Indicate that the current DML batch (started with OnStartDMLBatch()) is done.

virtual void OnFinishRowUpdate (  )  [virtual]

Indicate that the current row is finished having data written to it.

virtual void OnStartDMLBatch ( DMLType  in_dmlType,
simba_unsigned_native  in_numAffectedRows,
const std::vector< simba_uint16 > &  in_generatedColumns 
) [virtual]

Indicate that the SDK is about to perform a batch of DML operations on this table.

Parameters:
in_dmlType What operation the SDK will perform in this batch.
in_numAffectedRows How many rows will be affected in this batch. (i.e. how many rows inserted, deleted, or updated). ROW_COUNT_UNKNOWN if not known.
in_generatedColumns The generated columns which are requested. If non-empty, OnFinishDMLBatch() will return a Simba::DSI::IResult which contains 1 row for each row modified during the DML Batch. Specifically,

  • Added rows in the case of DML_INSERT,
  • Updated rows in the case of DML_UPDATE (With row values being post-update), and
  • Deleted rows in the case of DML_DELETE.

In the case of DML_INSERT, the rows in the result returned by OnFinishDMLBatch() must be in the order they were added to this DSIExtResultSet via AppendRow(). Otherwise, the order of returned rows is arbitrary.

The returned resultset will contain one column for every element of this vector, with the i'th (0-based) column in the returned resultset returned from the j'th (0-based) column of this DSIExtResultset, with j = in_generatedColumns[i].

Note: The default implementation of this method throws if in_generatedColumns is non-empty, and calls OnStartDMLBatch(DMLType, simba_unsigned_native) otherwise.

virtual void OnStartDMLBatch ( DMLType  in_dmlType,
simba_unsigned_native  in_numAffectedRows 
) [virtual]

Indicate that the SDK is about to perform a batch of DML operations on this table.

Parameters:
in_dmlType What operation the SDK will perform in this batch.
in_numAffectedRows How many rows will be affected in this batch. (i.e. how many rows inserted, deleted, or updated). ROW_COUNT_UNKNOWN if not known.
virtual void OnStartRowUpdate (  )  [virtual]

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.

virtual AutoPtr<DSIExtIndex> OpenIndex ( const IUseableIndexMetadata in_indexMeta,
bool  in_mustKeepOrder = false,
bool  in_mustSupplyBookmarks = false 
) [pure virtual]

Create and return an DSIExtIndex object to use for indexing this DSIExtResultSet.

Note: If this is called multiple times for the same index, independent DSIExtIndex objects should be returned. I.E., they can be moved through independently without affecting each other.

Parameters:
in_indexMeta The IIndexMetadata object corresponding to the index to open. Should have been retrieved via GetIndexes(). (NOT OWN)
in_mustKeepOrder Whether the produced DSIExtIndex must traverse its rows in the order of the index. For a sorted index, this means that rows will be traversed in the index's sort order. For a clustered index, this means that rows will be traversed in the order of the associated IBookmarkComparator. (default is false)
in_mustSupplyBookmarks Whether the produced index must support the use of DSIExtIndex::GetTableBookmark() and associated methods. (default is false)
Exceptions:
SEInvalidArgumentException If in_indexMeta was not from GetIndexes().
SEInvalidArgumentException If in_mustSupplyBookmarks is true and the index is incapable of doing so. (see IIndexMetadata::CanProduceTableBookmarks())
SEInvalidOperationException If this result set doesn't support indexes.
Returns:
An DSIExtIndex object which can be used to index this DSIExtResultSet.

Implemented in DSIExtSimpleResultSet.

virtual void Reset (  )  [pure virtual]

Resets the cursor to before the first row.

If there is currently a bookmark source set on this table, DSIExtBookmarkSource::Reset() should be called on it, and then it should be used to dictate traversal of rows as if it had just been set on the table using SetBookmarkSource().

As an optimization, if DSIExtBookmarkSource::Reset() return false, this indicates that the same bookmarks which were returned for the last traversal through the bookmark source will be returned for the next traversal so if the rows which have just been traversed have been cached in some way, that cache can be used instead of using the bookmark source directly.

If this is done, the next time that Reset() is called on this object, DSIExtBookmarkSource::Reset() _must_ be called again to check its return value, as it may change from call to call, as it depends on state in the SQLEngine.

Implemented in DSIExtSimpleResultSet.

virtual simba_uint16 ResolveColumn ( SharedPtr< DSIExtResultSet in_table,
simba_uint16  in_colIndex 
) [virtual]

Resolve the column reference that refers the given table to this result set.

IMPORTANT: This method applies only when this table represents a joined result after a JOIN operation is passed down. Before the pass down JOIN operation is finalized, all column references in the SQL statement need to be resolved so that they no longer reference the original tables. Instead, they reference this table.

For example in the following query,

select T1.C1, T2.C2 from T1 JOIN T2 on T1.C1 = T2.C1

After the JOIN operation is passed down, ResolveColumn() will be called on the returned table to resolve T1.C1 and T2.C2 in the SELECT_LIST.

See also:
DSIBooleanExprHandler for details on how a JOIN operation is passed down.
Parameters:
in_table The original table that the column refers to.
in_colIndex The column number in the original table (in_table).
Exceptions:
SEInvalidOperationException if the table does not represent a joined result.
Returns:
Resolved zero-based column index if successful, SE_INVALID_COLUMN_NUMBER otherwise.
virtual void SetBookmarkSource ( DSIExtBookmarkSource in_bookmarkSource  )  [pure virtual]

Set a bookmark source on this result set.

Sets a bookmark source on this result set. If this method is called, this result set should be only used with a forward-only cursor, and Move() should move through the rows designated by the bookmark source.

Every time this method is called, the cursor is implicitly moved to 'before the first (bookmarked) row'. This method only needs to be supported if bookmarks are supported.

If a NULL bookmarkSource is set, this reverts the DSIExtResultSet to moving through its rows in its 'natural' order. (the one it would use if a bookmark source was never set)

For example, let's say that in the following code, the bookmark source bSource initially has 2 bookmarks in it, (b1, b2). Then the following two snippets of code are two equivalent ways to visit the rows of the result set specified by the bookmark source.

Snippet 1:

DSIExtResultSet* rs = GetResultSet(); IBookmarkSource* bSource = GetBookmarkSource(); rs->SetBookmarkSource(bSource); rs is positioned 'before' bSource's first bookmark. rs->Move(DSI_DIR_NEXT); // returns true rs is now at the row specified by bSource's first bookmark (b1). rs->Move(DSI_DIR_NEXT); // returns true rs is now at the row specified by bSource's second bookmark (b2). rs->Move(DSI_DIR_NEXT); // returns false rs is not positioned on a row. rs->Reset(); // This should implicitly call bSource->Reset(). Note: after a bookmark source has been reset via Reset(), it may return a different list of bookmarks. In this case, DSIExtBookmarkSource::Reset() will return true. For this example, after it is reset, bSource will have 3 bookmarks, (b3, b1, b4).

rs is positioned 'before' bSource's first bookmark. rs->Move(DSI_DIR_NEXT); // returns true rs is now at the row specified by bSource's first bookmark (b3). rs->Move(DSI_DIR_NEXT); // returns true rs is now at the row specified by bSource's second bookmark (b1). rs->Move(DSI_DIR_NEXT); // returns true rs is now at the row specified by bSource's third bookmark (b4). rs->Move(DSI_DIR_NEXT); // returns false rs is not positioned on a row.

Snippet 2:

DSIExtResultSet* rs = GetResultSet(); IBookmarkSource* bSource = GetBookmarkSource(); bSource->MoveNext(); // returns true rs->GotoBookmark(bSource->GetBookmark()); rs is now at the row specified by bSource's first bookmark (b1). bSource->MoveNext(); // returns true rs->GotoBookmark(bSource->GetBookmark()); rs is now at the row specified by bSource's second bookmark (b2). bSource->MoveNext(); // returns false

bSource->Reset(); // returns true since the bookmark list changes to (b3, b1, b4). bSource->MoveNext(); // returns true rs->GotoBookmark(bSource->GetBookmark()); rs is now at the row specified by bSource's first bookmark (b3). bSource->MoveNext(); // returns true rs->GotoBookmark(bSource->GetBookmark()); rs is now at the row specified by bSource's second bookmark (b1). bSource->MoveNext(); // returns true rs->GotoBookmark(bSource->GetBookmark()); rs is now at the row specified by bSource's third bookmark (b4). bSource->MoveNext(); // returns false

This method is provided to allow the DSIExtResultSet implementation to retrieve multiple bookmarks at a time for performance purposes (i.e. retrieve multiple table rows at a time, pre-fetching, etc).

As seen above, it is important that the implementation calls DSIExtBookmarkSource::Reset() when (and only when) DSIExtResultSet::Reset() is called on it, as the bookmark list it produces may change in between calls to DSIExtBookmarkSource::Reset().

Parameters:
in_bookmarkSource The bookmark source to set on this object. (NOT OWN)
Exceptions:
SEInvalidOperationException if bookmarks are not supported.

Implemented in DSIExtSimpleResultSet.

virtual void SetFetchRowsetSize ( simba_unsigned_native  in_rowsetSize  )  [virtual]

Sets the number of rows that are to be fetched to the client application.

This value is to be used as an optimization hint by the DSII to possibly implement pre-fetching of data. It should not affect the number of rows the Move() function moves by.

Eg. If SetFetchRowsetSize(10) is called. The next call to Move() may choose to use this information to fetch and cache 10 or more rows of data. The following 9 calls to Move() do not necessarily need to fetch more data and can just use cached data.

Note that the DSII is not limited to only pre-fetching in_rowsetSize number of rows.

This method should be called before calling Move() and may be called again if the application changes this value. If it is not called, the default rowset size should be assumed to be 1.

This method should not throw an exception. If pre-fetching is not supported, the value can simply be ignored.

The default implementation in DSIExtResultSet ignores this value and does not do any pre-fetching of data.

Parameters:
in_rowsetSize The number of rows the application is requesting per fetch.

Implements IResult.

virtual bool WriteData ( simba_uint16  in_column,
SqlData in_sqlData,
simba_signed_native  in_offset,
bool  in_isDefault 
) [virtual]

Write data to a column in the current row and specified column.

Note that if in_isDefault is true, then in_sqlData will be NULL, and in_offset should be ignored.

Parameters:
in_column The column to write data to.
in_sqlData The container for the data to write to the column. (NOT OWN)
in_offset The offset into the column to start writing data at.
in_isDefault Flag indicating that the default value should be used for the column.
Exceptions:
SEInvalidArgumentException if the column is invalid.
SEInvalidArgumentException if the offset is invalid for the column, or it will result in the given data overflowing the boundaries of the column.
SEInvalidOperationException if the table does not support updating.
SEInvalidOperationException if the table was opened as read-only.
Returns:
true if data is truncated; false otherwise.

The documentation for this class was generated from the following file:

Generated on Wed May 17 14:21:17 2017 for SimbaEngine 10.1.3.1011 by simba