com.simba.dsi.ext
Class SqlDataEngine

java.lang.Object
  extended by com.simba.dsi.ext.SqlDataEngine
All Implemented Interfaces:
IDataEngine

public abstract class SqlDataEngine
extends java.lang.Object
implements IDataEngine

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 employ Simba's SQLEngine should extend this class.


Constructor Summary
protected SqlDataEngine()
          Constructs a DSIExtSqlDataEngine with default properties.
 
Method Summary
 IMetadataHelper createMetadataHelper()
          Create a helper object to retrieve basic metadata that can be used to provide default implementations of catalog metadata sources.
 OperationHandlerFactory createOperationHandlerFactory()
          Create a factory for creating "handler" objects to pass down operations such as AGGREGATION, FILTER, and JOIN.
 Variant getProperty(int propKey)
          Retrieves the data engine property as identified by the given property key.
 AttributeDataMap getPropertyMap()
          Gets the property map for this data engine.
 IResultSet makeNewMetadataResult(MetadataSourceID metadataSourceId, java.util.ArrayList<java.lang.String> filterValues, java.lang.String escapeChar, java.lang.String identifierQuoteChar, boolean filterAsIdentifier)
          Produces an IResultSet filled with metadata.
 IResultSet makeNewMetadataResult(MetadataSourceID metadataSourceId, java.util.ArrayList<java.lang.String> filterValues, java.lang.String escapeChar, java.lang.String identifierQuoteChar, boolean filterAsIdentifier, OrderType orderType)
          Produces an IResultSet filled with metadata.
abstract  IMetadataSource makeNewMetadataTable(MetadataSourceID metadataTableID, java.util.ArrayList<java.lang.String> filterValues, java.lang.String escapeChar, java.lang.String identifierQuoteChar, boolean filterAsIdentifier)
          Makes a new metadata source that contains unordered raw metadata.
abstract  StoredProcedure openProcedure(java.lang.String catalogName, java.lang.String schemaName, java.lang.String procName)
          Open a stored procedure.
abstract  DSIExtResultSet openTable(java.lang.String catalogName, java.lang.String schemaName, java.lang.String tableName, TableOpenType openType)
          Open a physical table/view.
 IQueryExecutor prepare(java.lang.String query)
          Produces an IQueryExecutor which can be used to execute the given query.
 IQueryExecutor prepareBatch(java.util.List<java.lang.String> queries)
          Produces an IQueryExecutor which can be used to execute the given batch of queries.
 void setDirectExecute()
          Indicate that any queries prepared by this data engine will be executed immediately, and only once.
 void setMetadataNeeded(boolean isNeeded)
          Indicate whether this data engine will need to create an IQueryExecutor that can return metadata before the execute call.
 void setProperty(int propKey, Variant propValue)
          Sets a data engine property, as identified by the given property key, with the given property value.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface com.simba.dsi.dataengine.interfaces.IDataEngine
close
 

Constructor Detail

SqlDataEngine

protected SqlDataEngine()
                 throws com.simba.support.exceptions.ErrorException
Constructs a DSIExtSqlDataEngine with default properties.

Throws:
com.simba.support.exceptions.ErrorException - if an error occurs while setting up default property values.
Method Detail

createMetadataHelper

public IMetadataHelper createMetadataHelper()
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.

createOperationHandlerFactory

public OperationHandlerFactory createOperationHandlerFactory()
Create a factory for creating "handler" objects to pass down operations such as AGGREGATION, FILTER, and JOIN.

Return null if pass down operations are not supported.

Returns:
An OperationHandlerFactory object which creates "handler" objects for other operations if any of the operations is allowed to be passed down, null otherwise.

getProperty

public Variant getProperty(int propKey)
                    throws BadPropertyKeyException,
                           com.simba.support.exceptions.ErrorException
Retrieves the data engine property as identified by the given property key.

A customer is not recommended to override this method.

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

Parameters:
propKey - Property key associated with a data engine property
Returns:
Property value associated with the given date engine property key
Throws:
BadPropertyKeyException - if the input key is not valid.
com.simba.support.exceptions.ErrorException - if an error occurs.
See Also:
Variant

getPropertyMap

public AttributeDataMap getPropertyMap()
Gets the property map for this data engine.

A customer is not recommended to override this method.

Returns:
The data engine properties map.

makeNewMetadataResult

public IResultSet makeNewMetadataResult(MetadataSourceID metadataSourceId,
                                        java.util.ArrayList<java.lang.String> filterValues,
                                        java.lang.String escapeChar,
                                        java.lang.String identifierQuoteChar,
                                        boolean filterAsIdentifier)
                                 throws com.simba.support.exceptions.ErrorException
Produces an IResultSet filled with metadata. The result set's columns are determined by the metadata result indicator. The rest of the arguments specify how filtering is to be done for the results provided by the IResultSet.

There is no IQueryExecutor produced for metadata results, just an IResultSet. Internally, the client may convert the metadata request into a SQL query and use an IQueryExecutor to execute, but externally all that's provided is the results.

The IResultSet returned by this call must be non-null. Even if there are no rows, column metadata is still needed.

Specified by:
makeNewMetadataResult in interface IDataEngine
Parameters:
metadataSourceId - Identifies the type of metadata information to be produced.
filterValues - An ArrayList of String values used to filter the columns of the result set.
escapeChar - Escape character used in filtering.
identifierQuoteChar - Character used as a quote around identifiers.
filterAsIdentifier - Indicates if string filters are treated as identifiers.
Returns:
IMetadataSource holding the requested metadata results.
Throws:
com.simba.support.exceptions.ErrorException - If an error occurs.

makeNewMetadataResult

public IResultSet makeNewMetadataResult(MetadataSourceID metadataSourceId,
                                        java.util.ArrayList<java.lang.String> filterValues,
                                        java.lang.String escapeChar,
                                        java.lang.String identifierQuoteChar,
                                        boolean filterAsIdentifier,
                                        OrderType orderType)
                                 throws com.simba.support.exceptions.ErrorException
Produces an IResultSet filled with metadata. The result set's columns are determined by the metadata result indicator. The rest of the arguments specify how filtering is to be done for the results provided by the IResultSet.

There is no IQueryExecutor produced for metadata results, just an IResultSet. Internally, the client may convert the metadata request into a SQL query and use an IQueryExecutor to execute, but externally all that's provided is the results.

The IResultSet returned by this call must be non-null. Even if there are no rows, column metadata is still needed.

Specified by:
makeNewMetadataResult in interface IDataEngine
Parameters:
metadataSourceId - Identifies the type of metadata information to be produced.
filterValues - An ArrayList of String values used to filter the columns of the result set.
escapeChar - Escape character used in filtering.
identifierQuoteChar - Character used as a quote around identifiers.
filterAsIdentifier - Indicates if string filters are treated as identifiers.
orderType - The order to apply.
Returns:
IMetadataSource holding the requested metadata results.
Throws:
com.simba.support.exceptions.ErrorException - If an error occurs.

makeNewMetadataTable

public abstract IMetadataSource makeNewMetadataTable(MetadataSourceID metadataTableID,
                                                     java.util.ArrayList<java.lang.String> filterValues,
                                                     java.lang.String escapeChar,
                                                     java.lang.String identifierQuoteChar,
                                                     boolean filterAsIdentifier)
                                              throws com.simba.support.exceptions.ErrorException
Makes a new metadata source that contains unordered 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. Although a map of restrictions is given to the metadata source, the restrictions are just a suggestion. Metadata source may choose to ignore the restrictions.

DSIMetadataSource is returned and ownership is passed on to the caller of this method.

Parameters:
metadataTableID - Identifier to create the appropriate metadata table.
filterValues - Filters to be applied to the metadata table.
escapeChar - Escape character used in filtering.
identifierQuoteChar - Quote identifier, which is the quotation mark that this filter recognizes.
filterAsIdentifier - Indicates if string filters are treated as identifiers. If metadataID is true, string filters are treated as identifiers. Otherwise, filters are not treated as identifiers.
Returns:
The metadata source, or NULL if the MetadataSourceID type is not supported.
Throws:
com.simba.support.exceptions.ErrorException - If an error occurs.

openProcedure

public abstract StoredProcedure openProcedure(java.lang.String catalogName,
                                              java.lang.String schemaName,
                                              java.lang.String procName)
                                       throws com.simba.support.exceptions.ErrorException
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:
catalogName - The name of the catalog in which the stored procedure resides.
schemaName - The name of the schema in which the stored procedure resides.
procName - The name of the stored procedure to open.
Returns:
the opened procedure, NULL if the procedure does not exist.
Throws:
com.simba.support.exceptions.ErrorException - If an error occurs.

openTable

public abstract DSIExtResultSet openTable(java.lang.String catalogName,
                                          java.lang.String schemaName,
                                          java.lang.String tableName,
                                          TableOpenType openType)
                                   throws com.simba.support.exceptions.ErrorException
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 retrieving 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() needs to be 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 IResultSet 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:
catalogName - The name of the catalog in which the table resides.
schemaName - The name of the schema in which the table resides.
tableName - The name of the table to open.
openType - An enum indicating how the table should be opened. Default is read-only.
Returns:
the opened table, NULL if the table does not exist.
Throws:
com.simba.support.exceptions.ErrorException - If any other error occurs.

prepare

public final IQueryExecutor prepare(java.lang.String query)
                             throws ParsingException,
                                    com.simba.support.exceptions.ErrorException
Produces an IQueryExecutor which can be used to execute the given query. The query string is guaranteed to have already been converted into "native SQL" using IConnection.toNativeSQL().

The resultant IQueryExecutor should expose IResult*s for each anticipated result set, including column metadata describing the results if possible.

Specified by:
prepare in interface IDataEngine
Parameters:
query - SQL query, in "native SQL" form.
Returns:
IQueryExecutor which can be used for executing query.
Throws:
ParsingException - If an error occurs in parsing the query.
com.simba.support.exceptions.ErrorException - If any other error occurs.

prepareBatch

public final IQueryExecutor prepareBatch(java.util.List<java.lang.String> queries)
                                  throws ParsingException,
                                         com.simba.support.exceptions.ErrorException
Produces an IQueryExecutor which can be used to execute the given batch of queries. The query strings are guaranteed to have already been converted into "native SQL" using IConnection.toNativeSQL().

The batch of queries must be queries that return row count results. Queries that return result sets are not allowed to be included in a batch because Statement.executeBatch() can only return an array of row counts and not result sets.

If errors are encountered during batch processing, the IQueryExecutor should create and add IErrorResult objects to the IQueryExecutor's list of results so that they can be used to properly report errors after batch processing.

Specified by:
prepareBatch in interface IDataEngine
Parameters:
queries - SQL queries, in "native SQL" form.
Returns:
IQueryExecutor which can be used for executing the batch of queries.
Throws:
ParsingException - If an error occurs in parsing the queries.
com.simba.support.exceptions.ErrorException - If any other error occurs.

setDirectExecute

public void setDirectExecute()
Indicate that any queries prepared by this data engine will be executed immediately, and only once.

If this function is not called, then the prepared query may be executed multiple times.

If not needed, this hint can be safely ignored.

Specified by:
setDirectExecute in interface IDataEngine

setMetadataNeeded

public void setMetadataNeeded(boolean isNeeded)
Indicate whether this data engine will need to create an IQueryExecutor that can return metadata before the execute call.

If this method is not called or called with a true value, the data engine must create an IQueryExecutor that can return metadata at any time after the prepare call. If this method is called with a false value, the data engine can create an IQueryExecutor that only needs to return metadata after the execute call.

If not needed, this hint can be safely ignored.

Specified by:
setMetadataNeeded in interface IDataEngine
Parameters:
isNeeded - Indicates whether this data engine will need to create an IQueryExecutor that can return metadata before the execute call.

setProperty

public void setProperty(int propKey,
                        Variant propValue)
                 throws BadAttrValException,
                        com.simba.support.exceptions.ErrorException
Sets a data engine property, as identified by the given property key, with the given property value.

A customer is not recommended to override this method.

If the value is substituted with another value before storage, an OPT_VAL_CHANGED_WARNING warning should be posted in the warnings holder. For properties which accept more than just a discrete set of values, this method should throw a BadAttrValException if an illegal value is given which can't be substituted with another value.

Parameters:
propKey - Data Engine property key supported by SimbaEngine
propValue - Data Engine property value to be set for propKey.
Throws:
BadAttrValException - if the input value is not valid for the key.
com.simba.support.exceptions.ErrorException - if an unspecified error occurs.
See Also:
Variant


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