StatementWrapper (Tentackle Persistence 2.0.6 API)

java.lang.Object
- org.tentackle.persist.StatementWrapper

All Implemented Interfaces:

AutoCloseable

Direct Known Subclasses:

PreparedStatementWrapper
```
public class StatementWrapper
extends Object
implements AutoCloseable
```
A wrapper for sql statements.
Will catch and report SQLExceptions and keep track of being used only once after Db.createStatement().

Author:

harald

Field Summary

Fields
Modifier and Type	Field and Description
`protected boolean`	`cancelled` flag if statement has been cancelled.
`protected ManagedConnection`	`con` the managed connection.
`protected WeakReference<ResultSetWrapper>`	`openResultSet` pending open result set.
`protected boolean`	`ready` flag if statement is marked ready for being consumed.
`protected boolean`	`running` flag if statement is currently running.
`protected String`	`sql` the SQL string.
`protected Statement`	`stmt` the sql statement, null if closed.

Constructor Summary

Constructors
Constructor and Description

StatementWrapper(ManagedConnection con, Statement stmt)
Creates a wrapper for an sql statement.

Constructors
Constructor and Description
`StatementWrapper(ManagedConnection con, Statement stmt)` Creates a wrapper for an sql statement.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`protected void`	`assertNotReadOnly()` Asserts db is writable.
`protected void`	`assertOpen()` Asserts the statement is open.
`void`	`cancel()` Cancels a statement.
`void`	`close()` Closes this statement.
`void`	`consume()` Consume a statement without executing it. The method is invoked if a rollback is performed prior to consuming the statement.
`protected void`	`detachSession()` Detach the db from the connection. Statements detach the db on executeUpdate or on close() in the resultsetwrapper after executeQuery.
`ResultSetWrapper`	`executeQuery(String sql)` Executes a query.
`ResultSetWrapper`	`executeQuery(String sql, boolean withinTx)` Executes a query.
`protected ResultSet`	`executeQueryImpl(String sql)` Implementation of executeQuery.
`int`	`executeUpdate(String sql)` Executes the given SQL statement.
`protected int`	`executeUpdateImpl(String sql)` Implementation of executeUpdate.
`protected void`	`forceDetached()` Detaches the Db after a severe error.
`ManagedConnection`	`getConnection()` Gets the connection.
`int`	`getFetchDirection()` Retrieves the direction for fetching rows from database tables that is the default for result sets generated from this `Statement` object.
`int`	`getFetchSize()` Retrieves the number of result set rows that is the default fetch size for `ResultSet` objects generated from this `Statement` object.
`int`	`getMaxRows()` Retrieves the maximum number of rows that a `ResultSet` object produced by this `Statement` object can contain.
`Db`	`getSession()` Gets the currently attached session.
`String`	`getSql()` Gets the sql string.
`Statement`	`getStatement()` Gets the wrapped statement.
`boolean`	`isCancelled()` Returns whether this statement has been cancelled. May be invoked from any thread.
`boolean`	`isClosed()` Determines whether this statement is closed.
`boolean`	`isMarkedReady()` Returns whether this statement is marked ready. Used to determine unused pending statements in servers when closing dead sessions.
`boolean`	`isRunning()` Returns whether the statement is being executed. May be invoked from any thread.
`void`	`markReady()` Marks the statement to be ready for being consumed by a `Db` attached to a `ConnectionManager`. This is an additional measure to enforce the programming rule that a statement is being used only once after `Db.createStatement()` (for non-prepared statements) or after `Db.getPreparedStatement(org.tentackle.persist.StatementKey, boolean, int, int, java.util.function.Supplier<java.lang.String>)` for prepared statements.
`void`	`setFetchDirection(int direction)` Gives the driver a hint as to the direction in which rows will be processed in `ResultSet` objects created using this `Statement` object.
`void`	`setFetchSize(int rows)` Gives the JDBC driver a hint as to the number of rows that should be fetched from the database when more rows are needed for `ResultSet` objects genrated by this `Statement`.
`void`	`setMaxRows(int max)` Sets the limit for the maximum number of rows that any `ResultSet` object generated by this `Statement` object can contain to the given number.
`protected void`	`setRunning(boolean running)` Sets the running flag of this statements. Updates the running statements in `ManagedConnection`.
`String`	`toString()`
`void`	`unmarkReady()` Unmarks (consumes) this statement previously marked ready.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Field Detail
  - con
```
protected final ManagedConnection con
```
    the managed connection.
  - stmt
```
protected Statement stmt
```
    the sql statement, null if closed.
  - sql
```
protected String sql
```
    the SQL string.
  - ready
```
protected boolean ready
```
    flag if statement is marked ready for being consumed.
  - running
```
protected boolean running
```
    flag if statement is currently running.
  - cancelled
```
protected boolean cancelled
```
    flag if statement has been cancelled.
  - openResultSet
```
protected WeakReference<ResultSetWrapper> openResultSet
```
    pending open result set.
- Constructor Detail
  - StatementWrapper
```
public StatementWrapper(ManagedConnection con,
                        Statement stmt)
```
    Creates a wrapper for an sql statement.
    
    Parameters:
    
    con - the connection
    
    stmt - the sql statement
- Method Detail
  - getConnection
```
public ManagedConnection getConnection()
```
    Gets the connection.
    
    Returns:
    
    the connection
  - getStatement
```
public Statement getStatement()
```
    Gets the wrapped statement.
    
    Returns:
    
    the statement, null if closed
  - getSession
```
public Db getSession()
```
    Gets the currently attached session.
    
    Returns:
    
    the db
  - markReady
```
public void markReady()
```
    Marks the statement to be ready for being consumed by a Db attached to a ConnectionManager.
    This is an additional measure to enforce the programming rule that a statement is being used only once after Db.createStatement() (for non-prepared statements) or after Db.getPreparedStatement(org.tentackle.persist.StatementKey, boolean, int, int, java.util.function.Supplier<java.lang.String>) for prepared statements.
    If a statement is marked ready more than once, i.e. an open result exists (which would be closed according to the JDBC specs), a PersistenceException is thrown. The specs in Statement say:
```
 By default, only one ResultSet object per Statement object can be open at the same time.
 Therefore, if the reading of one ResultSet object is interleaved with the reading of another,
 each must have been generated by different Statement objects.
 All execution methods in the Statement interface implicitly close a statment's current
 ResultSet object if an open one exists.
 
```
    Without this additional measure a "ResultSet closed" exception will be thrown by the JDBC-driver on the next usage of the first resultset and you wouldn't have any clue which resultset forced the closing.
  - unmarkReady
```
public void unmarkReady()
```
    Unmarks (consumes) this statement previously marked ready.
  - isMarkedReady
```
public boolean isMarkedReady()
```
    Returns whether this statement is marked ready.
    Used to determine unused pending statements in servers when closing dead sessions.
    
    Returns:
    
    true if pending
  - consume
```
public void consume()
```
    Consume a statement without executing it.
    The method is invoked if a rollback is performed prior to consuming the statement.
  - getSql
```
public String getSql()
```
    Gets the sql string.
    
    Returns:
    
    the sql string
  - toString
```
public String toString()
```
    Overrides:
    
    toString in class Object
  - detachSession
```
protected void detachSession()
```
    Detach the db from the connection.
    Statements detach the db on executeUpdate or on close() in the resultsetwrapper after executeQuery.
  - executeUpdateImpl
```
protected int executeUpdateImpl(String sql)
                         throws SQLException
```
    Implementation of executeUpdate.
    
    Parameters:
    
    sql - the sql string
    
    Returns:
    
    the number of affected rows
    
    Throws:
    
    SQLException - if update failes
  - executeUpdate
```
public int executeUpdate(String sql)
```
    Executes the given SQL statement.
    
    Parameters:
    
    sql - an sql-statement
    
    Returns:
    
    the row count
  - executeQueryImpl
```
protected ResultSet executeQueryImpl(String sql)
                              throws SQLException
```
    Implementation of executeQuery.
    
    Parameters:
    
    sql - the sql string
    
    Returns:
    
    the result set
    
    Throws:
    
    SQLException - if query failed
  - executeQuery
```
public ResultSetWrapper executeQuery(String sql,
                                     boolean withinTx)
```
    Executes a query.
    
    Parameters:
    
    sql - is the query sql string
    
    withinTx - is true if start a transaction for this query.
    
    Returns:
    
    the result set as a ResultSetWrapper
  - executeQuery
```
public ResultSetWrapper executeQuery(String sql)
```
    Executes a query.
    
    Parameters:
    
    sql - is the query sql string
    
    Returns:
    
    the result set as a ResultSetWrapper
  - setRunning
```
protected void setRunning(boolean running)
```
    Sets the running flag of this statements.
    Updates the running statements in ManagedConnection.
    
    Parameters:
    
    running - true if running, false if finished
  - isRunning
```
public boolean isRunning()
```
    Returns whether the statement is being executed.
    May be invoked from any thread.
    
    Returns:
    
    true if statement is running
  - cancel
```
public void cancel()
```
    Cancels a statement.
  - isCancelled
```
public boolean isCancelled()
```
    Returns whether this statement has been cancelled.
    May be invoked from any thread.
    
    Returns:
    
    true if cancelled
  - close
```
public void close()
```
    Closes this statement.
    
    Specified by:
    
    close in interface AutoCloseable
  - isClosed
```
public boolean isClosed()
```
    Determines whether this statement is closed.
    
    Returns:
    
    true if statement closed
  - setFetchSize
```
public void setFetchSize(int rows)
```
    Gives the JDBC driver a hint as to the number of rows that should be fetched from the database when more rows are needed for ResultSet objects genrated by this Statement. If the value specified is zero, then the hint is ignored. The default value is zero.
    
    Parameters:
    
    rows - the number of rows to fetch
    
    See Also:
    
    getFetchSize()
  - getFetchSize
```
public int getFetchSize()
```
    Retrieves the number of result set rows that is the default fetch size for ResultSet objects generated from this Statement object. If this Statement object has not set a fetch size by calling the method setFetchSize, the return value is implementation-specific.
    
    Returns:
    
    the default fetch size for result sets generated from this Statement object
    
    See Also:
    
    setFetchSize(int)
  - setMaxRows
```
public void setMaxRows(int max)
```
    Sets the limit for the maximum number of rows that any ResultSet object generated by this Statement object can contain to the given number. If the limit is exceeded, the excess rows are silently dropped.
    
    Parameters:
    
    max - the new max rows limit; zero means there is no limit
    
    See Also:
    
    getMaxRows()
  - getMaxRows
```
public int getMaxRows()
```
    Retrieves the maximum number of rows that a ResultSet object produced by this Statement object can contain. If this limit is exceeded, the excess rows are silently dropped.
    
    Returns:
    
    the current maximum number of rows for a ResultSet object produced by this Statement object; zero means there is no limit
    
    See Also:
    
    setMaxRows(int)
  - setFetchDirection
```
public void setFetchDirection(int direction)
```
    Gives the driver a hint as to the direction in which rows will be processed in ResultSet objects created using this Statement object. The default value is ResultSet.FETCH_FORWARD.
    Note that this method sets the default fetch direction for result sets generated by this Statement object. Each result set has its own methods for getting and setting its own fetch direction.
    
    Parameters:
    
    direction - the initial direction for processing rows
    
    See Also:
    
    getFetchDirection()
  - getFetchDirection
```
public int getFetchDirection()
```
    Retrieves the direction for fetching rows from database tables that is the default for result sets generated from this Statement object. If this Statement object has not set a fetch direction by calling the method setFetchDirection, the return value is implementation-specific.
    
    Returns:
    
    the default fetch direction for result sets generated from this Statement object
    
    See Also:
    
    setFetchDirection(int)
  - assertOpen
```
protected void assertOpen()
```
    Asserts the statement is open.
  - assertNotReadOnly
```
protected void assertNotReadOnly()
```
    Asserts db is writable.
  - forceDetached
```
protected void forceDetached()
```
    Detaches the Db after a severe error.
    Invoked to clean up any pending statements, rollback the transaction (if any) and detach the db after a severe error. This is a cleanup measure in case the application does not handle exceptions properly.

Class StatementWrapper

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

con

stmt

sql

ready

running

cancelled

openResultSet

Constructor Detail

StatementWrapper

Method Detail

getConnection

getStatement

getSession

markReady

unmarkReady

isMarkedReady

consume

getSql

toString

detachSession

executeUpdateImpl

executeUpdate

executeQueryImpl

executeQuery

executeQuery

setRunning

isRunning

cancel

isCancelled

close

isClosed

setFetchSize

getFetchSize

setMaxRows

getMaxRows

setFetchDirection

getFetchDirection

assertOpen

assertNotReadOnly

forceDetached