org.datanucleus.store.rdbms
Class SQLController

java.lang.Object
  org.datanucleus.store.rdbms.SQLController

public class SQLController
extends Object

Controller for execution of SQL statements to the underlying RDBMS datastore. Currently provides access to PreparedStatements and Connections.

Separates statements into 2 categories.

• Updates : INSERT/UPDATE/DELETE statements that can potentially (depending on the JDBC driver capabilities) be batched and hence give much speed benefit.
• Queries : SELECT statements that can provide flexibility in the capabilities of ResultSet.

An "update" statement can be batched. When getting the PreparedStatement the calling method passes in an argument to signify if it can be batched (whether it will use the statement before any other statement can execute), and if so will be cached against the Connection in use. When the statement is to be processed by the calling method it would pass in the "processNow" argument as false. This will leave the statement in the cache as "ready-to-be-processed" in case anything else comes in in the meantime. If the next statement to be requested has the same text and can also be batched then it will be returned the current statement so that it can populate it with its values. When the statement is ready for processing since it is in the cache the new values are added to the batch. Again the statement could be executed at that point or could continue batching.

Typical (unbatched) invocation would be as follows :-

 SQLController sql = rdbmsMgr.getSQLController();
 PreparedStatement ps = sql.getStatementForUpdate(conn, myStmt, false); // No batching
 sql.executeStatementUpdate(myStmt, ps, true); // Execute now, dont wait
 sql.closeStatement(ps);
 

Typical (batched) invocation would be as follows :-

 SQLController sql = rdbmsMgr.getSQLController();
 PreparedStatement ps = sql.getStatementForUpdate(conn, myStmt, true); // Batching
 sql.executeStatementUpdate(myStmt, ps, false); // Execute later
 sql.closeStatement(ps);
 ...
 PreparedStatement ps = sql.getStatementForUpdate(conn, myStmt, true); // Batching (same statement as first)
 sql.executeStatementUpdate(myStmt, ps, false); // Execute later
 sql.closeStatement(ps);
 

Things to note :-

• Batching only takes place if the underlying datastore supports it, and if the maximum batch size is not reached.
• When ExecutionContext.flush() is called the RDBMSManager will call "processStatementsForConnection" so that any batched statement is pushed to the datastore.

Field Summary

protected static org.datanucleus.util.Localiser	LOCALISER Localiser for messages.
protected int	maxBatchSize Maximum batch size (-1 implies no limit).
protected boolean	paramValuesInBrackets
protected int	queryTimeout Timeout to apply to queries (where required) in milliseconds.
protected boolean	supportsBatching Whether batching is supported for this controller (datastore).

Constructor Summary

SQLController(boolean supportsBatching, int maxBatchSize, int queryTimeout, boolean paramValuesInBrackets)
Constructor.

Method Summary

void	abortStatementForConnection(org.datanucleus.store.connection.ManagedConnection conn, PreparedStatement ps) Method to call to remove the current batched statement for this connection and close it due to an error preventing continuation.
void	closeStatement(org.datanucleus.store.connection.ManagedConnection conn, PreparedStatement ps) Convenience method to close a PreparedStatement.
ResultSet	executeStatementQuery(org.datanucleus.store.ExecutionContext ec, org.datanucleus.store.connection.ManagedConnection conn, String stmt, PreparedStatement ps) Method to execute a PreparedStatement query, and return the ResultSet.
int[]	executeStatementUpdate(org.datanucleus.store.ExecutionContext ec, org.datanucleus.store.connection.ManagedConnection conn, String stmt, PreparedStatement ps, boolean processNow) Method to execute a PreparedStatement update.
protected org.datanucleus.store.rdbms.SQLController.ConnectionStatementState	getConnectionStatementState(org.datanucleus.store.connection.ManagedConnection conn) Convenience method to get the state for this connection.
PreparedStatement	getStatementForQuery(org.datanucleus.store.connection.ManagedConnection conn, String stmtText) Convenience method to create a new PreparedStatement for a query.
PreparedStatement	getStatementForQuery(org.datanucleus.store.connection.ManagedConnection conn, String stmtText, String resultSetType, String resultSetConcurrency) Convenience method to create a new PreparedStatement for a query.
PreparedStatement	getStatementForUpdate(org.datanucleus.store.connection.ManagedConnection conn, String stmtText, boolean batchable) Convenience method to create a new PreparedStatement for an update.
protected int[]	processConnectionStatement(org.datanucleus.store.connection.ManagedConnection conn) Convenience method to process the currently waiting statement for the passed Connection.
void	processStatementsForConnection(org.datanucleus.store.connection.ManagedConnection conn) Convenience method to process any batched statement for the specified connection.
protected void	removeConnectionStatementState(org.datanucleus.store.connection.ManagedConnection conn) Convenience method to remove the state for this connection.
protected void	setConnectionStatementState(org.datanucleus.store.connection.ManagedConnection conn, org.datanucleus.store.rdbms.SQLController.ConnectionStatementState state) Convenience method to set the state for this connection.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

LOCALISER

protected static final org.datanucleus.util.Localiser LOCALISER

Localiser for messages.

supportsBatching

protected boolean supportsBatching

Whether batching is supported for this controller (datastore).

maxBatchSize

protected int maxBatchSize

Maximum batch size (-1 implies no limit).

queryTimeout

protected int queryTimeout

Timeout to apply to queries (where required) in milliseconds.

paramValuesInBrackets

protected boolean paramValuesInBrackets

Constructor Detail

SQLController

public SQLController(boolean supportsBatching,
                     int maxBatchSize,
                     int queryTimeout,
                     boolean paramValuesInBrackets)

Constructor.

Parameters:

supportsBatching - Whether batching is to be supported.

maxBatchSize - The maximum batch size

queryTimeout - Timeout for queries (ms)

paramValuesInBrackets - Whether param values are put in the log in brackets or not

Method Detail

getStatementForUpdate

public PreparedStatement getStatementForUpdate(org.datanucleus.store.connection.ManagedConnection conn,
                                               String stmtText,
                                               boolean batchable)
                                        throws SQLException

Convenience method to create a new PreparedStatement for an update.

Parameters:

conn - The Connection to use for the statement

stmtText - Statement text

batchable - Whether this statement is batchable. Whether we will process the statement before any other statement

Returns:

The PreparedStatement

Throws:

SQLException - thrown if an error occurs creating the statement

getStatementForQuery

public PreparedStatement getStatementForQuery(org.datanucleus.store.connection.ManagedConnection conn,
                                              String stmtText)
                                       throws SQLException

Convenience method to create a new PreparedStatement for a query.

Parameters:

conn - The Connection to use for the statement

stmtText - Statement text

Returns:

The PreparedStatement

Throws:

SQLException - thrown if an error occurs creating the statement

getStatementForQuery

public PreparedStatement getStatementForQuery(org.datanucleus.store.connection.ManagedConnection conn,
                                              String stmtText,
                                              String resultSetType,
                                              String resultSetConcurrency)
                                       throws SQLException

Convenience method to create a new PreparedStatement for a query.

Parameters:

conn - The Connection to use for the statement

stmtText - Statement text

resultSetType - Type of result set

resultSetConcurrency - Concurrency for the result set

Returns:

The PreparedStatement

Throws:

SQLException - thrown if an error occurs creating the statement

executeStatementUpdate

public int[] executeStatementUpdate(org.datanucleus.store.ExecutionContext ec,
                                    org.datanucleus.store.connection.ManagedConnection conn,
                                    String stmt,
                                    PreparedStatement ps,
                                    boolean processNow)
                             throws SQLException

Method to execute a PreparedStatement update. Prints logging information about timings.

Parameters:

conn - The connection (required since the one on PreparedStatement is not always the same so we cant use it)

stmt - The statement text

ps - The Prepared Statement

processNow - Whether to process this statement now (only applies if is batched)

Returns:

The numer of rows affected (as per PreparedStatement.executeUpdate)

Throws:

SQLException - Thrown if an error occurs

executeStatementQuery

public ResultSet executeStatementQuery(org.datanucleus.store.ExecutionContext ec,
                                       org.datanucleus.store.connection.ManagedConnection conn,
                                       String stmt,
                                       PreparedStatement ps)
                                throws SQLException

Method to execute a PreparedStatement query, and return the ResultSet. Prints logging information about timings.

Parameters:

conn - The connection (required since the one on PreparedStatement is not always the same so we can't use it)

stmt - The statement text

ps - The Prepared Statement

Returns:

The ResultSet from the query

Throws:

SQLException - Thrown if an error occurs

abortStatementForConnection

public void abortStatementForConnection(org.datanucleus.store.connection.ManagedConnection conn,
                                        PreparedStatement ps)

Method to call to remove the current batched statement for this connection and close it due to an error preventing continuation.

Parameters:

conn - The connection

ps - The statement

closeStatement

public void closeStatement(org.datanucleus.store.connection.ManagedConnection conn,
                           PreparedStatement ps)
                    throws SQLException

Convenience method to close a PreparedStatement. If the statement is currently being used as a batch, will register it for closing when executing the batch

Parameters:

conn - The Connection

ps - The PreparedStatement

Throws:

SQLException - if an error occurs closing the statement

processStatementsForConnection

public void processStatementsForConnection(org.datanucleus.store.connection.ManagedConnection conn)
                                    throws SQLException

Convenience method to process any batched statement for the specified connection. Typically called when flush() or commit() are called.

Parameters:

conn - The connection

Throws:

SQLException - Thrown if an error occurs on processing of the batch

processConnectionStatement

protected int[] processConnectionStatement(org.datanucleus.store.connection.ManagedConnection conn)
                                    throws SQLException

Convenience method to process the currently waiting statement for the passed Connection. Only processes the statement if it is in processable state.

Parameters:

conn - The connection

Returns:

The return codes from the statement batch

Throws:

SQLException - if an error occurs processing the batch

removeConnectionStatementState

protected void removeConnectionStatementState(org.datanucleus.store.connection.ManagedConnection conn)

Convenience method to remove the state for this connection. This is typically called when a Connection is closed.

Parameters:

conn - The Connection

getConnectionStatementState

protected org.datanucleus.store.rdbms.SQLController.ConnectionStatementState getConnectionStatementState(org.datanucleus.store.connection.ManagedConnection conn)

Convenience method to get the state for this connection.

Parameters:

conn - The Connection

Returns:

The state (if any)

setConnectionStatementState

protected void setConnectionStatementState(org.datanucleus.store.connection.ManagedConnection conn,
                                           org.datanucleus.store.rdbms.SQLController.ConnectionStatementState state)

Convenience method to set the state for this connection.

Parameters:

conn - The Connection

state - The state