com.simba.dsi.dataengine.interfaces
Interface IQueryExecutor

All Known Subinterfaces:
IStreamQueryExecutor

public interface IQueryExecutor

An IQueryExecutor is used to perform query execution. An IQueryExecutor handles input and output parameters, and may be used to push down input parameter values before execution begins.

A new IQueryExecutor generated through IDataEngine.prepare() must provide information about parameters and results associated with the query. If a call to getResults() is made before execution, the resulting ExecutionResults is only used to see how many results there are and to access column metadata for any IResultSet results using IResultSet.getSelectColumns(). Any other methods on the contained IResultSet and IRowCountResult objects may throw exceptions.


Method Summary
 void cancelExecute()
          Cancels any currently executing query.
 void clearCancel()
          Clears any cancellation flags set if CancelExecute was called.
 void clearPushedParamData()
          Clears any parameter data that has been pushed down using pushParamData().
 void close()
          Closes the QueryExecutor and releases any resources held by it.
 void execute(ExecutionContexts contexts, com.simba.support.IWarningListener warningListener)
          Executes the prepared statement in the context of the ExecutionContext objects provided by the ExecutionContexts object.
 void finalizePushedParamData()
          Informs the IQueryExecutor that all parameter values which will be pushed have been pushed prior to query execution.
 java.util.ArrayList<ParameterMetadata> getMetadataForParameters()
          This method provides an ArrayList of ParameterMetadatas which describes all of the parameters in the query.
 int getNumParams()
          Returns the number of parameters in the query.
 IResults getResults()
          Returns an IResults holding all of the results of the query's execution, in order.
 void pushMappedParamTypes(java.util.Map<java.lang.Integer,TypeMetadata> setParameterMetadata)
          This method is called in JDBC drivers only.
 void pushParamData(int parameterSet, ParameterInputValue value)
          Pushes part of an input parameter value down before execution.
 

Method Detail

cancelExecute

void cancelExecute()
                   throws com.simba.support.exceptions.ErrorException
Cancels any currently executing query.

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

clearCancel

void clearCancel()
Clears any cancellation flags set if CancelExecute was called.


clearPushedParamData

void clearPushedParamData()
                          throws com.simba.support.exceptions.ErrorException
Clears any parameter data that has been pushed down using pushParamData(). The IQueryExecutor may be re-used for execution following this call.

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

close

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

An IQueryExecutor is closed: - during a call to SQLCancel(), SQLCloseCursor() or SQLFreeStmt(SQL_CLOSE) while dealing with results from a query that was executed in ODBC using SQLExecDirect() - when a new query is prepared using SQLPrepare() or executed using SQLExecDirect() or a new metadata result is generated using the parent statement - just before the parent statement is closed


execute

void execute(ExecutionContexts contexts,
             com.simba.support.IWarningListener warningListener)
             throws BadDefaultParamException,
                    ParsingException,
                    ExecutingException,
                    OperationCanceledException,
                    com.simba.support.exceptions.ErrorException
Executes the prepared statement in the context of the ExecutionContext objects provided by the ExecutionContexts object.

Parameters:
contexts - Provides ExecutionContext objects, one for each parameter set for which the SQL statement is to be executed.
warningListener - Used for posting warnings about the execution.
Throws:
BadDefaultParamException - If a parameter is used as a "default" parameter where "default" has no meaning.
ParsingException - If an error corresponding to a ParsingErrorKey occurs.
ExecutingException - If an error corresponding to an ExecutingErrorKey occurs.
OperationCanceledException - If the execution is cancelled.
com.simba.support.exceptions.ErrorException - If any other error occurs.

finalizePushedParamData

void finalizePushedParamData()
                             throws com.simba.support.exceptions.ErrorException
Informs the IQueryExecutor that all parameter values which will be pushed have been pushed prior to query execution. After the next execute() call has finished, this pushed parameter data may be cleared from memory, even if the execute() call results in an exception being thrown.

The first subsequent call to pushParamData() should behave as if the executor has a clear cache of pushed parameter values.

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

getMetadataForParameters

java.util.ArrayList<ParameterMetadata> getMetadataForParameters()
                                                                throws com.simba.support.exceptions.ErrorException
This method provides an ArrayList of ParameterMetadatas which describes all of the parameters in the query.

For a JDBC driver, it will be called once after prepare to provide the metadata that is returned from PreparedStatement.getParameterMetaData(). It will then be called a second time after pushMappedParamTypes(Map) is called. The results from the second call will be used by the JDBC layer to convert the parameter input values to the Java types associated with the SQL type provided in ParameterMetadata. The number of parameters and all fixed parameter data must remain constant between calls to this method.

The position of ParameterMetadatas in the ArrayList should match their positions in the query. For example, parameter 1 should be at position 0 and parameter 2 at position 1. Even if the parameters are named instead of numbered, this positioning should be maintained. Positions should correlate with "parameter numbers" retrieved using ParameterMetadata.getParameterNumber().

Returns:
An ArrayList of ParameterMetadata describing each parameter in the query.
Throws:
com.simba.support.exceptions.ErrorException - If an error occurs.

getNumParams

int getNumParams()
                 throws com.simba.support.exceptions.ErrorException
Returns the number of parameters in the query.

The value returned by this function must fit into an unsigned 16-bit integer.

Returns:
Number of parameters in the query.
Throws:
com.simba.support.exceptions.ErrorException - If an error occurs.

getResults

IResults getResults()
                    throws com.simba.support.exceptions.ErrorException
Returns an IResults holding all of the results of the query's execution, in order. This method may be called before execute() is called, and if so it is expected that the returned ExecutionResults contain preliminary result objects, even if the column metadata for result set result objects is invalid or incomplete. Finalized column metadata can be generated after execution, although it is preferable that column metadata be available at prepare time as some applications will attempt to use it then. For example, if column metadata is not available before execution when a SELECT query is prepared, an empty result set object could be returned. After execution, the correct column metadata would be inserted into the result set object.

Returns:
An IResults holding the results of the query.
Throws:
com.simba.support.exceptions.ErrorException - If an error occurs.

pushParamData

void pushParamData(int parameterSet,
                   ParameterInputValue value)
                   throws BadDefaultParamException,
                          com.simba.support.exceptions.ErrorException
Pushes part of an input parameter value down before execution. This value should be stored for use later during execution.

This method will can only be called once for any parameter set/parameter combination (a "parameter cell") where the parameter has a non-character/binary data type.

For parameters with character or binary data types, this method may be called multiple times for the same parameter set/parameter combination. The multiple parts should be concatenated together in order to get the complete value. For character data, the byte array passed down for one chunk may NOT necessarily be a complete UTF-8 string representation. There may be bytes provided in the previous or subsequent chunk to complete codepoints at the start and/or end.

The metadata passed in should be taken notice of because it may not match metadata supplied by a possible call to getMetadataForParameters(), as the ODBC consumer is able to change parameter metadata themselves.

Parameters:
parameterSet - The 1-based parameter set for which data provides part of the input parameter value.
value - The input parameter value. Includes metadata for identifying the parameter.
Throws:
BadDefaultParamException - If a "default" parameter is passed in for a parameter where "default" has no meaning.
com.simba.support.exceptions.ErrorException - If any other error occurs.

pushMappedParamTypes

void pushMappedParamTypes(java.util.Map<java.lang.Integer,TypeMetadata> setParameterMetadata)
                          throws com.simba.support.exceptions.ErrorException
This method is called in JDBC drivers only. It is called once before execute(ExecutionContexts, IWarningListener) is called. It provides the TypeMetadata for parameters as set through the JDBC API in the PreparedStatement.set...(...) methods. Each TypeMetadata for a parameter is mapped to the 0-based parameter number.

A parameters TypeMetadata will not be present in in the Map if the JDBC layer could not determine the set type for the parameter. For example, calling PreparedStatement.setObject(1, null) will cause setParameterMetadata.get(0) to return null.

The return value of getMetadataForParameters() should be updated at this point to reflect the final ParameterMetadata that the JDBC layer should use to convert parameter input values.

If there are multiple calls to execute each subsequent execute call will cause a call to this method to be called with potentially different TypeMetadata for each parameter.

See the JDBC 3/4 specification Appendix B Table B-2 and B-4 for standard Java Object types -> JDBC types.

Parameters:
setParameterMetadata - A copy of the TypeMetadata for the parameters as they were set through the JDBC API.
Throws:
com.simba.support.exceptions.ErrorException - If there was an error.


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