DSIExtSqlDataEngine Class Reference

An abstract class that partially implements and extends the IDataEngine interface. More...

Inherits Simba::DSI::DSIDataEngine.

List of all members.

Public Member Functions

virtual AutoPtr
< Simba::DSI::ITableTemplate
BeginCreateTable (SharedPtr< TableSpecification > in_specification)
 Create a table template from a TableSpecification.
virtual AutoPtr
< Simba::SQLEngine::DSIExtCustomBehaviorProvider
CreateCustomBehaviorProvider ()
 Create a DSIExtCustomBehaviorProvider object that provides accessors to handlers and factories for user data types.
virtual AutoPtr
< Simba::SQLEngine::DSIExtMetadataHelper
CreateMetadataHelper ()
 Create a helper object to retrieve basic metadata that can be used to provide default implementations of catalog metadata sources.
virtual AutoPtr
< Simba::SQLEngine::DSIExtOperationHandlerFactory
CreateOperationHandlerFactory ()
 Create a "handler" object to pass down operations such as filters, joins and aggregations.
virtual AutoPtr
< Simba::SQLEngine::DSIExtPassdownInformation
CreatePassdownInformation ()
 Create a Passdown Information object that provides information about which pass down operations are supported by the DSII.
virtual void CreateTable (const SharedPtr< TableSpecification > in_specification)
 Create a table based on the given TableSpecification.
virtual bool DoesTableExist (const simba_wstring &in_catalogName, const simba_wstring &in_schemaName, const simba_wstring &in_tableName)
 Determine if the given table exists.
virtual void DropTable (const simba_wstring &in_catalogName, const simba_wstring &in_schemaName, const simba_wstring &in_tableName, Simba::SQLEngine::DSIExtTableDropOption in_dropOption)
 Drop the given table.
Simba::SQLEngine::DSIExtDataEngineContextGetContext ()
 Get a pointer reference to the data engine context.
virtual const AttributeDataGetProperty (DSIExtDataEnginePropertyKey in_key)
 Returns a date engine property corresponding to the in_key.
virtual
DSIExtDataEnginePropertyKeyValueMap
GetPropertyMap ()
 Gets the property map for this data engine.
virtual
Simba::DSI::DSIMetadataSource
MakeNewMetadataTable (Simba::DSI::DSIMetadataTableID in_metadataTableID, Simba::DSI::DSIMetadataRestrictions &in_restrictions, const simba_wstring &in_escapeChar, const simba_wstring &in_identifierQuoteChar, bool in_filterAsIdentifier)=0
 Makes a new metadata source that contains raw metadata.
virtual SharedPtr
< Simba::SQLEngine::DSIExtAggregateFunction
OpenAggregateFunction (const simba_wstring &in_aggrName, Simba::SQLEngine::SESetQuantifier in_setQuantifier, simba_size_t in_numArguments)
 Open a custom aggregate function.
virtual SharedPtr
< Simba::SQLEngine::DSIExtProcedure
OpenProcedure (const simba_wstring &in_catalogName, const simba_wstring &in_schemaName, const simba_wstring &in_procName)
 Open a stored procedure.
virtual SharedPtr
< Simba::SQLEngine::DSIExtScalarFunction
OpenScalarFunction (const simba_wstring &in_scalarName, simba_size_t in_numArguments)
 Open a custom scalar function.
virtual SharedPtr
< Simba::SQLEngine::DSIExtResultSet
OpenTable (const simba_wstring &in_catalogName, const simba_wstring &in_schemaName, const simba_wstring &in_tableName, Simba::SQLEngine::DSIExtTableOpenType in_openType)=0
 Open a physical table/view.
Simba::DSI::IQueryExecutorPrepare (const simba_wstring &in_sqlStatement)
 Prepare the given SQL statement(s).
virtual void SetProperty (DSIExtDataEnginePropertyKey in_key, AttributeData *in_value)
 Sets the data engine property with the given key to the given value.
virtual ~DSIExtSqlDataEngine ()
 Destructor.

Protected Member Functions

virtual
Simba::DSI::IQueryExecutor
CreateQueryExecutor (AutoPtr< Simba::SQLEngine::AEStatements > in_aeStatements)
 Create a query executor for the SQL statements currently preparing.
 DSIExtSqlDataEngine (Simba::DSI::IStatement *in_statement, bool in_initializeDefaults=true)
 Constructor.
virtual Simba::DSI::IResultGetMetadataResultImplementation (Simba::DSI::DSIMetadataTableID in_metadataTableID, Simba::DSI::DSIMetadataRestrictions &in_restrictions, Simba::DSI::DSIMetadataSource *in_metadataSource, std::vector< Simba::DSI::DSIOutputMetadataColumn * > &in_columnMetadata, std::vector< Simba::DSI::DSIMetadataFilter * > &in_filters)
 Returns a concrete implementation of metadata result set.

Protected Attributes

SharedPtr
< Simba::SQLEngine::DSIExtDataEngineContext
m_context
 The context for the current batch of SQL statements.
DSIExtDataEnginePropertyKeyValueMap m_engineProperties

Detailed Description

An abstract class that partially implements and extends the IDataEngine interface.

This class incorporates Simba's standard-based SQL processing capability. In other words, it uses Simba's SQLEngine to process SQL statements.

A DSII wishing to fully or partially employs Simba's SQLEngine should extend this class.


Constructor & Destructor Documentation

virtual ~DSIExtSqlDataEngine (  )  [virtual]

Destructor.

DSIExtSqlDataEngine ( Simba::DSI::IStatement in_statement,
bool  in_initializeDefaults = true 
) [protected]

Constructor.

The constructor is protected since this class is abstract.

Parameters:
in_statement The parent statement. (NOT OWN)
in_initializeDefaults Flag indicating if default property values should be initialized. Only set this to false if you know you are going to initialize every DataEngine property.
Exceptions:
SEInvalidArgumentException when in_statement is NULL.

Member Function Documentation

virtual AutoPtr<Simba::DSI::ITableTemplate> BeginCreateTable ( SharedPtr< TableSpecification in_specification  )  [virtual]

Create a table template from a TableSpecification.

The table name described in in_tableSpecification will already have been verified to not exist in the data source by calling DoesTableExist().

Parameters:
in_specification The specification for the to be created table.
virtual AutoPtr<Simba::SQLEngine::DSIExtCustomBehaviorProvider> CreateCustomBehaviorProvider (  )  [virtual]

Create a DSIExtCustomBehaviorProvider object that provides accessors to handlers and factories for user data types.

The default implementation in this class returns DSIExtCustomBehaviorProvider.

Returns:
A DSIExtCustomBehaviorProvider object.
virtual AutoPtr<Simba::SQLEngine::DSIExtMetadataHelper> CreateMetadataHelper (  )  [virtual]

Create a helper object to retrieve basic metadata that can be used to provide default implementations of catalog metadata sources.

The default implementation in this class returns NULL. That is, no default metadata is supported.

Returns:
A helper object to retrieve basic metadata if supported, NULL otherwise.
virtual AutoPtr<Simba::SQLEngine::DSIExtOperationHandlerFactory> CreateOperationHandlerFactory (  )  [virtual]

Create a "handler" object to pass down operations such as filters, joins and aggregations.

The default implementation in this class returns NULL. That is, no operation pass-down is supported.

Returns:
A "handler" object to pass down operations if supported, NULL otherwise.
virtual AutoPtr<Simba::SQLEngine::DSIExtPassdownInformation> CreatePassdownInformation (  )  [virtual]

Create a Passdown Information object that provides information about which pass down operations are supported by the DSII.

The default implementation in this class returns DSIExtPassdownInformation. That is, it uses the defaults as defined in DSIExtPassdownInformation.h.

Returns:
A Passdown Information object to supply information about pass down operations.
virtual Simba::DSI::IQueryExecutor* CreateQueryExecutor ( AutoPtr< Simba::SQLEngine::AEStatements in_aeStatements  )  [protected, virtual]

Create a query executor for the SQL statements currently preparing.

This method is called in the Prepare() method of this class. This default implementation creates an DSIExtQueryExecutor object and calls PrepareResults() on it.

Note: If you override this method and your DSII uses the ETree (Uses the SQLEngine for query execution), then you must call DSIExtQueryExecutor::PrepareResults() on it immediately after it is constructed.

Parameters:
in_aeStatements The current batch of SQL statements in the form of an AETree.
Exceptions:
DSIException when an error occurs.
Returns:
The new query executor. (OWN)
virtual void CreateTable ( const SharedPtr< TableSpecification in_specification  )  [virtual]

Create a table based on the given TableSpecification.

The table name described in in_tableSpecification will already have been verified to not exist in the data source by calling DoesTableExist(). The columns described in in_tableSpecification are generated using the IColumnFactory retrieved from a DSIExtCustomBehaviorProvider generated by calling CreateCustomBehaviorProvider(). No validation is performed on the table constraints described in in_tableSpecification.

Parameters:
in_specification The specification for the table.
virtual bool DoesTableExist ( const simba_wstring in_catalogName,
const simba_wstring in_schemaName,
const simba_wstring in_tableName 
) [virtual]

Determine if the given table exists.

The base class provides a default implementation that uses OpenTable to determine if a table exists. Customers can override this method if they have a more efficient way of determining this. Customers should not call this method within the implementation of OpenTable unless they have provided an implementation.

Parameters:
in_catalogName The name of the catalog in which the table resides.
in_schemaName The name of the schema in which the table resides.
in_tableName The name of the table.
Returns:
True if the table exists in the data source.
virtual void DropTable ( const simba_wstring in_catalogName,
const simba_wstring in_schemaName,
const simba_wstring in_tableName,
Simba::SQLEngine::DSIExtTableDropOption  in_dropOption 
) [virtual]

Drop the given table.

The existence of the table will be verified by calling DoesTableExist() before this method is called.

Parameters:
in_catalogName The name of the catalog in which the table resides.
in_schemaName The name of the schema in which the table resides.
in_tableName The name of the table.
in_dropOption An enum of how the table should be dropped.

Note: Currently, in_dropOption will always be TABLE_DROP_UNSPECIFIED

Get a pointer reference to the data engine context.

Returns:
A pointer reference to the data engine context. (NOT OWN)
virtual Simba::DSI::IResult* GetMetadataResultImplementation ( Simba::DSI::DSIMetadataTableID  in_metadataTableID,
Simba::DSI::DSIMetadataRestrictions in_restrictions,
Simba::DSI::DSIMetadataSource in_metadataSource,
std::vector< Simba::DSI::DSIOutputMetadataColumn * > &  in_columnMetadata,
std::vector< Simba::DSI::DSIMetadataFilter * > &  in_filters 
) [protected, virtual]

Returns a concrete implementation of metadata result set.

This basic implementation return new instance of BasicFilteredMetadataResult().

MAINTENANCE NOTE: The DSIOutputMetadataColumn*s, and DSIMetadataFilter*s in in_columnMetadata and in_filters, respectively, are NOT OWNed by this function. When this function creates a new FilteredMetadataResult, the FilteredMetadataResult assumes ownership of these objects by calling vector::swap. The caller of this function is responsible for cleaning any objects in the case of an error.

Parameters:
in_metadataTableID Identifier to create the appropriate metadata table
in_restrictions Restrictions that may be applied to the metadata table.
in_metadataSource Metadata source that contains raw metadata.
in_columnMetadata List of columns based on the metadata table ID. (NOT OWN).
in_filters A list of metadata filters used to determine which rows are needed in retrieving data. (NOT OWN)
Returns:
IResult reference that has concrete implementation of metadata result set. (OWN)
virtual const AttributeData* GetProperty ( DSIExtDataEnginePropertyKey  in_key  )  [virtual]

Returns a date engine property corresponding to the in_key.

A customer is not recommended to override this method.

Refer to the DSIExtDataEngineProperties for detailed information on the supported properties.

Parameters:
in_key Data Engine property key supported by SimbaEngine.
Returns:
The data engine property corresponding to the in_key. (NOT OWN)
virtual DSIExtDataEnginePropertyKeyValueMap* GetPropertyMap (  )  [virtual]

Gets the property map for this data engine.

A customer is not recommended to override this method.

Returns:
The data engine properties map. (NOT OWN)
virtual Simba::DSI::DSIMetadataSource* MakeNewMetadataTable ( Simba::DSI::DSIMetadataTableID  in_metadataTableID,
Simba::DSI::DSIMetadataRestrictions in_restrictions,
const simba_wstring in_escapeChar,
const simba_wstring in_identifierQuoteChar,
bool  in_filterAsIdentifier 
) [pure virtual]

Makes a new metadata source that contains raw metadata.

A map of column tags to literal string restrictions will be passed into the metadata source, which enables the metadata source cut down on the size or the raw table.

If SDK metadata filtering is enabled (via the DSI_FILTER_METADATA_SOURCE driver property), then the passed in restrictions are only a suggestion for the metadata source, in order to allow it to restrict what it returns before SDK filtering is performed.

Note: If GetMetadataHelper() is implemented and this method returns NULL, the returned metadata helper will be used to produced results for the following metadata table IDs:

  • DSI_COLUMNS_METADATA
  • DSI_TABLES_METADATA
  • DSI_CATALOGSCHEMAONLY_METADATA
  • DSI_CATALOGONLY_METADATA
  • DSI_SCHEMAONLY_METADATA
  • DSI_PROCEDURES_METADATA
  • DSI_PROCEDURES_COLUMNS_METADATA

The SQLEngine also provides default implementations of the following metadata table IDs if this method returns NULL:

  • DSI_TABLETYPEONLY_METADATA
  • DSI_PRIMARY_KEYS_METADATA
  • DSI_STATISTICS_METADATA

Returning NULL for any other metadata table ID will produce an empty metadata resultset.

Parameters:
in_metadataTableID Identifier to create the appropriate metadata table
in_restrictions Restrictions that may be applied to the metadata table. Some restrictions may not be passed to the DSII if there are wildcards. The wildcards are '_' for a single character and '' for multiple characters. These are not passed down to avoid problems with filtering the wildcards literally, and are instead handled by the SDK. Note that if you wish to have full filtering, please refer to DSI_FILTER_METADATA_SOURCE.
in_escapeChar Escape character used in filtering.
in_identifierQuoteChar Quote identifier, which is the quotation mark that this filter recognizes.
in_filterAsIdentifier Indicates if string filters are treated as identifiers. If in_filterAsIdentifier is true, string filters are treated as identifiers. Otherwise, filters are not treated as identifiers.
Returns:
New metadata source that contains raw metadata, or NULL to use the SQLEngine implementation. (OWN)

Implements DSIDataEngine.

virtual SharedPtr<Simba::SQLEngine::DSIExtAggregateFunction> OpenAggregateFunction ( const simba_wstring in_aggrName,
Simba::SQLEngine::SESetQuantifier  in_setQuantifier,
simba_size_t  in_numArguments 
) [virtual]

Open a custom aggregate function.

This method will be called during the preparation of a SQL statement.

Note that execution of custom aggregates is currently unsupported, CQE must be used to execute the aggregate function. Note also that only 1 argument is currently accepted for custom aggregates.

Parameters:
in_aggrName The name of the aggregate function to open.
in_setQuantifier The type of set quantifier, distinct or all.
in_numArguments The number of arguments for the aggregate function. Note that this will only ever be set to 1 for the current implementation.
Returns:
The opened aggregate function, NULL if the function does not exist.
virtual SharedPtr<Simba::SQLEngine::DSIExtProcedure> OpenProcedure ( const simba_wstring in_catalogName,
const simba_wstring in_schemaName,
const simba_wstring in_procName 
) [virtual]

Open a stored procedure.

This method will be called during the preparation of a SQL statement.

Once the stored procedure is opened, it should allow retrieval of metadata. That is, calling GetResults() on the returned procedure should return results that provide column metadata, if any, and calling GetParameters() on the returned procedure should return parameter metadata, if any.

If a result set is returned, before data can be retrieved from the table SetCursorType() will have to called. Since this is done at the execution time, the DSII should _NOT_ try to make the data ready for retrieval until Execute() is called.

The DSII decides how catalog and schema are interpreted or supported.

Parameters:
in_catalogName The name of the catalog in which the stored procedure resides.
in_schemaName The name of the schema in which the stored procedure resides.
in_procName The name of the stored procedure to open.
Exceptions:
InvalidCatalogException if in_catalogName is an invalid catalog. Note that returning NULL will also work; throwing the exception will be more explicit.
InvalidSchemaException if in_schemaName is an invalid catalog. Note that returning NULL will also work; throwing the exception will be more explicit.
Returns:
the opened procedure, NULL if the procedure does not exist.
virtual SharedPtr<Simba::SQLEngine::DSIExtScalarFunction> OpenScalarFunction ( const simba_wstring in_scalarName,
simba_size_t  in_numArguments 
) [virtual]

Open a custom scalar function.

This method will be called during the preparation of a SQL statement.

Parameters:
in_scalarName The name of the scalar function to open.
in_numArguments The number of arguments for the scalar function.
Exceptions:
ErrorException if the number of arguments for the specified scalar function is incorrect. Note that this is for informational purposes, returning NULL will work correctly with a less informative message.
Returns:
The opened scalar function, NULL if the function does not exist.
virtual SharedPtr<Simba::SQLEngine::DSIExtResultSet> OpenTable ( const simba_wstring in_catalogName,
const simba_wstring in_schemaName,
const simba_wstring in_tableName,
Simba::SQLEngine::DSIExtTableOpenType  in_openType 
) [pure virtual]

Open a physical table/view.

This method will be called during the preparation of a SQL statement.

Once the table is opened, it should allow retrieval of metadata. That is, calling GetSelectColumns() on the returned table should return column metadata. SimbaEngine needs the table metadata to infer the column metadata of the result set if the SQL statement is a query.

Before data can be retrieved from the table, SetCursorType() will have to called. Since this is done at the execution time, the DSII should _NOT_ try to make the data ready for retrieval until SetCursorType() is called.

The DSII decides how catalog and schema are interpreted or supported. If the same table is asked to open twice (that is, OpenTable() is called twice), the DSII _MUST_ return two separate DSIExtResultSet instances since two cursors will be needed.

SimbaEngine will ensure this method is called only once if the table is referenced only once in a SQL statement.

Parameters:
in_catalogName The name of the catalog in which the table resides.
in_schemaName The name of the schema in which the table resides.
in_tableName The name of the table to open.
in_openType An enum indicating how the table should be opened.
Exceptions:
InvalidCatalogException if in_catalogName is an invalid catalog. Note that returning NULL will also work; throwing the exception will be more explicit.
InvalidSchemaException if in_schemaName is an invalid catalog. Note that returning NULL will also work; throwing the exception will be more explicit.
Returns:
the opened table, NULL if the table does not exist.
Simba::DSI::IQueryExecutor* Prepare ( const simba_wstring in_sqlStatement  )  [virtual]

Prepare the given SQL statement(s).

A customer is not recommended to override this method.

Within this method, the following calls are made, 1. Calls CreateQueryExecutor() to create an executor that can be customized by overriding that method. 2. Calls CreateMaterializer() to create a Materializer to translate an AET to an ET. Both represent the same SQL statement.

The caller of this method owns the returned object.

Parameters:
in_sqlStatement The SQL statement to be prepared.
Returns:
an IQueryExecutor object for statement execution. (OWN)

Implements IDataEngine.

virtual void SetProperty ( DSIExtDataEnginePropertyKey  in_key,
AttributeData in_value 
) [virtual]

Sets the data engine property with the given key to the given value.

A customer is not recommended to override this method.

This method should post an OPT_VAL_CHANGE warning if a value is substituted with another value before storage (like substituting a timeout value for the maximum if it's too high). For properties which accept more than just a discrete set of values, this method should throw an INVALID_ATTR_VAL error if an illegal value is given which can't be substituted with another value.

Parameters:
in_key Data Engine property key supported by SimbaEngine.
in_value Data Engine property value to be set for in_key. (OWN)

Member Data Documentation

The context for the current batch of SQL statements.

Stores values for data engine properties. The AttributeData*s in this map are OWNed by the DSIExtSqlDataEngine and are cleaned up in ~DSIExtSqlDataEngine().


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

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