Package org.datanucleus.store.rdbms

Class 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 Detail

      • 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.

    • Constructor Detail

      • SQLController

        public SQLController​(boolean supportsBatching,
                     int maxBatchSize,
                     int queryTimeout,
                     SQLController.StatementLoggingType stmtLoggingType)
        Constructor.
        Parameters:
        supportsBatching - Whether batching is to be supported.
        maxBatchSize - The maximum batch size
        queryTimeout - Timeout for queries (ms)
        stmtLoggingType - Setting for statement logging

    • 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

      • getStatementForUpdate

        public PreparedStatement getStatementForUpdate​(org.datanucleus.store.connection.ManagedConnection conn,
                                               String stmtText,
                                               boolean batchable,
                                               boolean getGeneratedKeysFlag,
                                               List<String> pkColumnNames)
                                        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
        getGeneratedKeysFlag - whether to request getGeneratedKeys for this statement
        pkColumnNames - list of auto-generated primary key names to return from an insert statement. May be empty.
        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.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:
        ec - ExecutionContext
        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 number of rows affected (as per PreparedStatement.executeUpdate)
        Throws:
        SQLException - Thrown if an error occurs

      • executeStatement

        public boolean executeStatement​(org.datanucleus.ExecutionContext ec,
                                org.datanucleus.store.connection.ManagedConnection conn,
                                String stmt,
                                PreparedStatement ps)
                         throws SQLException
        Method to execute a PreparedStatement (using PreparedStatement.execute()). Prints logging information about timings.
        Parameters:
        ec - Execution Context
        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 number of rows affected (as per PreparedStatement.execute)
        Throws:
        SQLException - Thrown if an error occurs

      • executeStatementQuery

        public ResultSet executeStatementQuery​(org.datanucleus.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:
        ec - ExecutionContext
        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