DSIExtIndex Class Reference

An abstract class representing an index on a relation. More...

List of all members.

Public Member Functions

virtual void Close ()=0
 Close the index. After this is called, the SQLEngine will not call the methods listed in Open() before another call to Open().
virtual void DeleteRow ()
 Delete the current row from the associated result set. By default indexes do not support delete operations.
virtual const IBookmarkComparatorGetBookmarkComparator () const =0
 Gets the bookmark comparator object for the bookmarks returned by GetTableBookmark().
virtual Simba::DSI::IColumnsGetColumns ()=0
 Gets metadata for columns included in this index.
virtual const
IUseableIndexMetadata
GetIndexMetadata () const =0
 Gets metadata describing this index.
const simba_byte * GetTableBookmark () const
 Retrieve a bookmark uniquely identifying the current row in the parent relation.
virtual bool MaintainsOrder () const =0
 Whether this index traverses its rows in index order.
virtual bool MoveToNextRow ()=0
 Moves to the next row which matches the last set seek condition.
virtual void OnFinishDMLBatch (AutoPtr< Simba::DSI::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 (DSIExtResultSet::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 (DSIExtResultSet::DMLType in_type, 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 void Open ()=0
 Open the index. This will be called before any calls to Seek(), Reset(), MoveNext(), GetTableBookmark(), or RetrieveData() from the SQLEngine.
virtual void Reset ()=0
 Resets the index so it is ready to move through the rows which match the last set seek condition again.
virtual bool RetrieveData (simba_uint16 in_column, SqlData *in_data, simba_signed_native in_offset, simba_signed_native in_maxSize)=0
 Fills in in_data with a chunk of data for the given column in the current row.
virtual void Seek (const DSIExtSeekCondition *in_seekCondition)=0
 Seek in this index using the seek condition.
virtual bool SupportsTableBookmarks () const =0
 Whether GetBookmarkComparator() and GetTableBookmark() may be called on this object.
virtual bool WriteData (simba_uint16 in_column, SqlData *in_data, simba_signed_native in_offset, bool in_isDefault)
 Write data to a column in the current row and specified column. By default indexes do not support updating.
virtual ~DSIExtIndex ()
 Destructor.

Protected Member Functions

 DSIExtIndex ()
 Constructor.

Protected Attributes

const simba_byte * m_currTableBookmark
 A pointer to bookmark data for the current row. (NOT OWN).

Detailed Description

An abstract class representing an index on a relation.

There are two main ways objects of this class will be used: 1) To retrieve bookmarks into the 'base' relation. 2) To retrieve column data, either as part of an 'index-only scan', or to use in screening predicates as part of (1).

Upon construction, or after a call to Close(), a DSIExtIndex object is considered to be in a 'closed' state, and before using the object to retrieve data or bookmarks, an Open(), followed by an initial Seek() will be performed.

        Open()                   --------------------------------------
          |                      | (if MoveToNextRow() returned false) |
          V                      |                                     V
        Seek() -> MoveToNextRow() --> GetTableBookmark()/RetrieveData() ---> Reset() -
          ^             ^                                                |            |
          |             |                                                V            V
          ----------------------------------------------------------------------------
        

Notes:


Constructor & Destructor Documentation

virtual ~DSIExtIndex (  )  [inline, virtual]

Destructor.

DSIExtIndex (  )  [inline, protected]

Constructor.


Member Function Documentation

virtual void Close (  )  [pure virtual]

Close the index. After this is called, the SQLEngine will not call the methods listed in Open() before another call to Open().

virtual void DeleteRow (  )  [virtual]

Delete the current row from the associated result set. By default indexes do not support delete operations.

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 index does not support delete.
virtual const IBookmarkComparator* GetBookmarkComparator (  )  const [pure virtual]

Gets the bookmark comparator object for the bookmarks returned by GetTableBookmark().

Exceptions:
SEInvalidArgumentException If SupportsTableBookmarks() returns false.
Returns:
The bookmark comparator object for the bookmarks returned by GetTableBookmark(). (NOT OWN)
virtual Simba::DSI::IColumns* GetColumns (  )  [pure virtual]

Gets metadata for columns included in this index.

Returns:
Metadata for columns included in this index. (NOT OWN)
virtual const IUseableIndexMetadata& GetIndexMetadata (  )  const [pure virtual]

Gets metadata describing this index.

Returns:
Metadata describing this index.
const simba_byte* GetTableBookmark (  )  const

Retrieve a bookmark uniquely identifying the current row in the parent relation.

The size of the bookmark should always be that of returned by this->GetBookmarkComparator()->GetBookmarkSize().

The lifetime of the returned pointer is until the next call to MoveToNextRow(), Seek(), Reset(), or until this object is destroyed.

Exceptions:
SEInvalidOperationException If SupportsTableBookmarks() returns false, or this index is not positioned on a row.
Returns:
A pointer to a buffer holding the bookmark data for the current row. (NOT OWN)
virtual bool MaintainsOrder (  )  const [pure virtual]

Whether this index traverses its rows in index order.

Specifically, if the index is sorted, the rows should be traversed in the index's sort order, and if the index is clustered, the rows should be traversed in the bookmark comparator's order.

Note: If this object was created with DSIExtResultSet::OpenIndex(), with in_mustKeepOrder == true, this _must_ also return true.

Returns:
Whether this index traverses its rows in index order.
virtual bool MoveToNextRow (  )  [pure virtual]

Moves to the next row which matches the last set seek condition.

Note: Can only be used after Seek() has been called.

Returns:
True if there was another row, false otherwise.
virtual void OnFinishDMLBatch ( AutoPtr< Simba::DSI::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 DSIExtIndex.

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.

Do nothing by default

virtual void OnFinishRowUpdate (  )  [virtual]

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

Do nothing by default

virtual void OnStartDMLBatch ( DSIExtResultSet::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 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,

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

The rows may be returned in arbitrary order.

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 ( DSIExtResultSet::DMLType  in_type,
simba_unsigned_native  in_numAffectedRows 
) [virtual]

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

Do nothing by default

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 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.

Do nothing by default

Note that when AppendRow() is called, OnStartRowUpdate() will not be called as it is implied that the newly added row will be updated.

virtual void Open (  )  [pure virtual]

Open the index. This will be called before any calls to Seek(), Reset(), MoveNext(), GetTableBookmark(), or RetrieveData() from the SQLEngine.

virtual void Reset (  )  [pure virtual]

Resets the index so it is ready to move through the rows which match the last set seek condition again.

virtual bool RetrieveData ( simba_uint16  in_column,
SqlData in_data,
simba_signed_native  in_offset,
simba_signed_native  in_maxSize 
) [pure virtual]

Fills in in_data with a chunk of data for the given column in the current row.

The SqlTypeMetadata* used by in_data is the same SqlTypeMetadata* exposed by the IColumn describing the column from GetColumns().

The following procedure should be implemented by this method:

  • if the data is null, call in_data->SetNull(true). in_offset and in_maxSize can be ignored
  • if the data is not of a character or binary type, then the value should be copied into the pointer returned by in_data->GetBuffer(). in_offset and in_maxSize can be ignored
  • if the data is of a character or binary type:
    • in_offset specifies the starting point to copy data from, in # of bytes from the start of that piece of data
      • in_offset must be aligned properly to the start of a data element
    • in_maxSize indicates the maximum number of bytes to copy
      • if in_maxSize is RETRIEVE_ALL_DATA, it means that the whole piece of data should be copied
    • the size of the data chunk being copied should be set with in_data->SetLength()
      • this length is the number of bytes copied
      • if there's only room for a partial element at the end, it does not need to be copied, and should not be included in the SetLength() length
      • calling SetLength() must be done before copying data in, because it modifies the size of the data buffer
    • the chunk of data starting at in_offset which is at a maximum in_size bytes long should be copied into the pointer returned by in_data->GetBuffer().
      • null termination is not necessary
Parameters:
in_column A column index. The first column uses index 0. The column order used is as is exposed in this->GetIndexMetadata().GetIncludedColumns().
in_data Holds a buffer to store the requested data. Must not be NULL. (NOT OWN)
in_offset Number of bytes in the data to skip before copying into in_data.
in_maxSize Maximum number of bytes of data to return in in_data.
Exceptions:
SEInvalidArgumentException If the column denoted by in_column was not set as 'needed' using SetDataNeeded() in the parent table.
Returns:
True if there is more data; false otherwise.
virtual void Seek ( const DSIExtSeekCondition in_seekCondition  )  [pure virtual]

Seek in this index using the seek condition.

in_seekCondition defines the subset of rows which subsequent calls to MoveToNextRow() will traverse. If it is NULL, then the whole index should be traversed. Otherwise, only the subset which passes in_seekCondition should.

Seek() may be called multiple times, with intervening calls to MoveToNextRow(), RetrieveData(), and Reset().

After Seek() returns, the cursor will be placed before the first row of the subset defined by in_seekCondition.

Parameters:
in_seekCondition The seek condition to seek with. (NOT OWN) This should not be cached, as it may change after Seek() returns.
virtual bool SupportsTableBookmarks (  )  const [pure virtual]

Whether GetBookmarkComparator() and GetTableBookmark() may be called on this object.

Note: If this object was created with DSIExtResultSet::OpenIndex(), with in_mustSupplyBookmarks == true, this _must_ also return true.

This may return false when this->GetIndexMetadata().CanProduceTableBookmarks() returns true if this object was instantiated without asking for the use of table bookmarks.

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

Write data to a column in the current row and specified column. By default indexes do not support updating.

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 OWNED)
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 index does not support updating.
Returns:
true if data is truncated; false otherwise.

Member Data Documentation

const simba_byte* m_currTableBookmark [protected]

A pointer to bookmark data for the current row. (NOT OWN).

Should be NULL if the index is not currently positioned on a row, or SupportsTableBookmarks() returns false.

The DSIExtIndex implementation is responsible for updating m_currTableBookmark on every row change.


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