Package org.apache.derby.iapi.sql
Interface PreparedStatement
-
- All Superinterfaces:
Dependable
,Dependent
- All Known Subinterfaces:
ExecPreparedStatement
,StorablePreparedStatement
- All Known Implementing Classes:
GenericPreparedStatement
,GenericStorablePreparedStatement
public interface PreparedStatement extends Dependent
The PreparedStatement interface provides methods to execute prepared statements, store them, and get metadata about them.
-
-
Field Summary
-
Fields inherited from interface org.apache.derby.catalog.Dependable
ACTIVATION, ALIAS, COLUMNS_IN_TABLE, COLUMNS_PERMISSION, CONGLOMERATE, CONSTRAINT, DEFAULT, FILE, HEAP, INDEX, PERM, PREPARED_STATEMENT, ROLE_GRANT, ROUTINE_PERMISSION, SCHEMA, SEQUENCE, STORED_PREPARED_STATEMENT, TABLE, TABLE_PERMISSION, TRIGGER, VIEW
-
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description ResultSet
execute(Activation activation, boolean forMetaData, long timeoutMillis)
Execute the PreparedStatement and return results, used for top level statements (not substatements) in a connection.ResultSet
executeSubStatement(Activation parent, Activation activation, boolean rollbackParentContext, long timeoutMillis)
Execute a statement as part of another statement (ithout a nested connection) and return results.ResultSet
executeSubStatement(LanguageConnectionContext lcc, boolean rollbackParentContext, long timeoutMillis)
Execute a statement as part of another statement (without a nested connection) and return results.Activation
getActivation(LanguageConnectionContext lcc, boolean scrollable)
PreparedStatements are re-entrant - that is, more than one execution can be active at a time for a single prepared statement.java.sql.Timestamp
getBeginCompileTimestamp()
Get the timestamp for the beginning of compilationlong
getBindTimeInMillis()
Get the bind time for the associated query in milliseconds.long
getCompileTimeInMillis()
Get the total compile time for the associated query in milliseconds.java.sql.SQLWarning
getCompileTimeWarnings()
Return any compile time warnings.java.sql.Timestamp
getEndCompileTimestamp()
Get the timestamp for the end of compilationlong
getGenerateTimeInMillis()
Get the generate time for the associated query in milliseconds.long
getOptimizeTimeInMillis()
Get the optimize time for the associated query in milliseconds.DataTypeDescriptor
getParameterType(int idx)
Get the type of the parameter at the given (0-based) index.DataTypeDescriptor[]
getParameterTypes()
Get an array of DataTypeDescriptors describing the types of the parameters of this PreparedStatement.long
getParseTimeInMillis()
Get the parse time for the associated query in milliseconds.ResultDescription
getResultDescription()
Get the ResultDescription for the statement.java.lang.String
getSource()
Return the SQL string that this statement is for.java.lang.String
getSPSName()
Return the SPS Name for this statement.long
getVersionCounter()
Get the version counter.boolean
isAtomic()
Returns whether or not this Statement requires should behave atomically -- i.e. whether a user is permitted to do a commit/rollback during the execution of this statement.boolean
referencesSessionSchema()
Return true if the query node for this statement references SESSION schema tables.void
rePrepare(LanguageConnectionContext lcc)
Re-prepare the statement if it is not up to date or, if requested, simply not optimal.boolean
upToDate()
Checks whether this PreparedStatement is up to date.-
Methods inherited from interface org.apache.derby.catalog.Dependable
getClassType, getDependableFinder, getObjectID, getObjectName, isPersistent
-
Methods inherited from interface org.apache.derby.iapi.sql.depend.Dependent
isValid, makeInvalid, prepareToInvalidate
-
-
-
-
Method Detail
-
upToDate
boolean upToDate() throws StandardException
Checks whether this PreparedStatement is up to date. A PreparedStatement can become out of date if any of several things happen: A schema used by the statement is dropped A table used by the statement is dropped A table used by the statement, or a column in such a table, is altered in one of several ways: a column is dropped, a privilege is dropped, a constraint is added or dropped, an index is dropped. A view used by the statement is dropped. In general, anything that happened since the plan was generated that might cause the plan to fail, or to generate incorrect results, will cause this method to return FALSE.- Returns:
- TRUE if the PreparedStatement is up to date, FALSE if it is not up to date
- Throws:
StandardException
-
rePrepare
void rePrepare(LanguageConnectionContext lcc) throws StandardException
Re-prepare the statement if it is not up to date or, if requested, simply not optimal. If there are open cursors using this prepared statement, then we will not be able to recompile the statement.- Parameters:
lcc
- The LanguageConnectionContext.- Throws:
StandardException
- thrown if unable to perform
-
getActivation
Activation getActivation(LanguageConnectionContext lcc, boolean scrollable) throws StandardException
PreparedStatements are re-entrant - that is, more than one execution can be active at a time for a single prepared statement. An Activation contains all the local state information to execute a prepared statement (as opposed to the constant information, such as literal values and code). Each Activation class contains the code specific to the prepared statement represented by an instance of this class (PreparedStatement).- Parameters:
lcc
- The LanguageConnectionContext.- Returns:
- The new activation.
- Throws:
StandardException
- Thrown on failure
-
execute
ResultSet execute(Activation activation, boolean forMetaData, long timeoutMillis) throws StandardException
Execute the PreparedStatement and return results, used for top level statements (not substatements) in a connection.There is no executeQuery() or executeUpdate(); a method is provided in ResultSet to tell whether to expect rows to be returned.
- Parameters:
activation
- The activation containing all the local state to execute the plan.forMetaData
- true if this is a meta-data querytimeoutMillis
- timeout value in milliseconds.- Returns:
- A ResultSet for a statement. A ResultSet represents the results returned from the statement, if any. Will return NULL if the plan for the PreparedStatement has aged out of cache, or the plan is out of date.
- Throws:
StandardException
- Thrown on failure
-
executeSubStatement
ResultSet executeSubStatement(Activation parent, Activation activation, boolean rollbackParentContext, long timeoutMillis) throws StandardException
Execute a statement as part of another statement (ithout a nested connection) and return results.There is no executeQuery() or executeUpdate(); a method is provided in ResultSet to tell whether to expect rows to be returned.
- Parameters:
parent
- The activation of the superstatementactivation
- The activation containing all the local state to execute the plan for substatementrollbackParentContext
- True if in the event of a statement-level exception, the parent context needs to be rolled back, too.timeoutMillis
- timeout value in milliseconds.- Returns:
- A ResultSet for a statement. A ResultSet represents the results returned from the statement, if any. Will return NULL if the plan for the PreparedStatement has aged out of cache, or the plan is out of date.
- Throws:
StandardException
- Thrown on failure
-
executeSubStatement
ResultSet executeSubStatement(LanguageConnectionContext lcc, boolean rollbackParentContext, long timeoutMillis) throws StandardException
Execute a statement as part of another statement (without a nested connection) and return results.Creates a new single use activation and executes it, but also passes rollbackParentContext parameter.
- Parameters:
lcc
- language connection contextrollbackParentContext
- True if in the event of a statement-level exception, the parent context needs to be rolled back, too.timeoutMillis
- timeout value in milliseconds.- Throws:
StandardException
- See Also:
executeSubStatement(Activation, Activation, boolean, long)
-
getResultDescription
ResultDescription getResultDescription()
Get the ResultDescription for the statement. The ResultDescription describes what the results look like: what are the rows and columns?This is available here and on the ResultSet so that users can see the shape of the result before they execute.
- Returns:
- A ResultDescription describing the results.
-
referencesSessionSchema
boolean referencesSessionSchema()
Return true if the query node for this statement references SESSION schema tables.- Returns:
- true if references SESSION schema tables, else false
-
getParameterTypes
DataTypeDescriptor[] getParameterTypes()
Get an array of DataTypeDescriptors describing the types of the parameters of this PreparedStatement. The Nth element of the array describes the Nth parameter.- Returns:
- An array of DataTypeDescriptors telling the type, length, precision, scale, etc. of each parameter of this PreparedStatement.
-
getParameterType
DataTypeDescriptor getParameterType(int idx) throws StandardException
Get the type of the parameter at the given (0-based) index. Raises an exception if the index is out of range.- Throws:
StandardException
-
getSource
java.lang.String getSource()
Return the SQL string that this statement is for.- Returns:
- the SQL string this statement is for.
-
getSPSName
java.lang.String getSPSName()
Return the SPS Name for this statement.- Returns:
- the SPS Name for this statement
-
getCompileTimeInMillis
long getCompileTimeInMillis()
Get the total compile time for the associated query in milliseconds. Compile time can be divided into parse, bind, optimize and generate times.- Returns:
- long The total compile time for the associated query in milliseconds.
-
getParseTimeInMillis
long getParseTimeInMillis()
Get the parse time for the associated query in milliseconds.- Returns:
- long The parse time for the associated query in milliseconds.
-
getBindTimeInMillis
long getBindTimeInMillis()
Get the bind time for the associated query in milliseconds.- Returns:
- long The bind time for the associated query in milliseconds.
-
getOptimizeTimeInMillis
long getOptimizeTimeInMillis()
Get the optimize time for the associated query in milliseconds.- Returns:
- long The optimize time for the associated query in milliseconds.
-
getGenerateTimeInMillis
long getGenerateTimeInMillis()
Get the generate time for the associated query in milliseconds.- Returns:
- long The generate time for the associated query in milliseconds.
-
getBeginCompileTimestamp
java.sql.Timestamp getBeginCompileTimestamp()
Get the timestamp for the beginning of compilation- Returns:
- Timestamp The timestamp for the beginning of compilation.
-
getEndCompileTimestamp
java.sql.Timestamp getEndCompileTimestamp()
Get the timestamp for the end of compilation- Returns:
- Timestamp The timestamp for the end of compilation.
-
isAtomic
boolean isAtomic()
Returns whether or not this Statement requires should behave atomically -- i.e. whether a user is permitted to do a commit/rollback during the execution of this statement.- Returns:
- boolean Whether or not this Statement is atomic
-
getCompileTimeWarnings
java.sql.SQLWarning getCompileTimeWarnings()
Return any compile time warnings. Null if no warnings exist.
-
getVersionCounter
long getVersionCounter()
Get the version counter. A change in the value indicates a recompile has happened.- Returns:
- version counter
-
-