JDBC Driver - Statement

The Statement object in the Polypheny JDBC Driver is pivotal for executing SQL queries and retrieving their results. It provides mechanisms to define queries, batch multiple commands, specify query properties, and access the resultant data sets. Through this object, users can manage aspects like timeout, fetch direction, and batch processing. The Polypheny JDBC Driver’s Statement object is designed to seamlessly integrate with the broader JDBC ecosystem while optimizing for the specific features and nuances of Polypheny.

execute

public boolean execute(String sql)
            throws SQLException

The execute(String statement) method of the Statement object in the Polypheny JDBC Driver is a versatile method used to execute SQL statements that may produce either a result set or an update count, such as a query or an update. Unlike executeQuery or executeUpdate, which are designed specifically for queries or updates respectively, the execute method can handle both. After calling this method, one must retrieve either the result set or the update count, depending on the nature of the executed statement using getResult, getUpdateCount or getLargeUpdateCount. If getUpdateCount or getLargeUpdateCount is called after a executing a statement that returned a result set, the value -1 is returned. Calling getResultSet on an update returns null.

Parameters:

Return Values:

This method throws an SQLException if a database access error occurs, the method is called on a closed Statement, or the given SQL statement produces anything other than a single result or an update count.

Usage:

try (
        Connection connection = DriverManager.getConnection( "jdbc:polypheny://localhost:20590" );
        Statement statement = connection.createStatement();
) {
    boolean isResultSet = statement.execute( "SELECT * FROM emps" );

    if ( isResultSet ) {
        ResultSet resultSet = statement.getResultSet();

        while ( resultSet.next() ) {
            // Process the results...
        }

        resultSet.close();
    } else {
        int updateCount = statement.getUpdateCount();
        // Process the update count if needed...
    }
} catch ( SQLException e ) {
    e.printStackTrace();
}

getUpdateCount and getLargeUpdateCount

public int getUpdateCount()
            throws SQLException

public long getLargeUpdateCount()
            throws SQLException

The getUpdateCount() and getLargeUpdateCount() methods of the Statement object in the Polypheny JDBC Driver are used to retrieve the number of rows affected by the execution of SQL Data Manipulation Language (DML) commands, such as INSERT, UPDATE, or DELETE, or by the execution of a DDL command. These methods will return -1 if the statement executed was a DDL command, a SELECT statement, or if the statement was not executed.

getUpdateCount returns an int, whereas getLargeUpdateCount returns a long, which allows it to handle larger values.

Return Values:

These methods throw an SQLException if a database access error occurs or the method is called on a closed Statement.

Usage:

try (
        Connection connection = DriverManager.getConnection( "jdbc:polypheny://..." );
        Statement statement = connection.createStatement();
) {
    boolean hasResultSet = statement.execute( "UPDATE my_table SET column1 = value1" );

    if ( !hasResultSet ) {
        int updateCount = statement.getUpdateCount();
        // or
        long largeUpdateCount = statement.getLargeUpdateCount();

        System.out.println( "Number of updated rows: " + updateCount );
        // or
        System.out.println( "Number of updated rows: " + largeUpdateCount );
    }
} catch ( SQLException e ) {
    e.printStackTrace();
}

getResultSet

public ResultSet getResultSet()
            throws SQLException

The getResultSet() method of the Statement object in the Polypheny JDBC Driver retrieves the current result set held by the statement, which is typically a result of executing a query. This method should be called only once per result. If the statement does not have a result set this function returns null.

Return Values:

This method throws an SQLException if a database access error occurs or the method is called on a closed Statement.

Usage:

try (
        Connection connection = DriverManager.getConnection( "jdbc:polypheny://..." );
        Statement statement = connection.createStatement();
) {
    statement.executeQuery( "SELECT * FROM my_table" );
    ResultSet resultSet = statement.getResultSet();

    while ( resultSet.next() ) {
        // Access the results...
        String columnValue = resultSet.getString( "column_name" );
        // Process the result...
    }

    resultSet.close();  // Always good practice to close the ResultSet when done.
} catch ( SQLException e ) {
    e.printStackTrace();
}

getMoreResults

public boolean getMoreResults()
            throws SQLException

public boolean getMoreResults(int current)
            throws SQLException

The getMoreResults() method of the Statement object in the Polypheny JDBC Driver moves to the next result set from a multiple-results statement or ensures that all results have been processed. However, in the context of the Polypheny JDBC Driver, statements always return only a single result set. Thus, this method always returns false, indicating that there are no more results to process.

This method throws an SQLException if a database access error occurs or the method is called on a closed Statement.

Parameters:

For the overloaded method:

Return Values:

executeUpdate

public int executeUpdate(String sql)
            throws SQLException

public int executeUpdate(String sql, int autoGeneratedKeys)
            throws SQLException

public int executeUpdate(String sql, int[] columnIndexes)
            throws SQLException

public int executeUpdate(String sql, String[] columnNames)
            throws SQLException

The executeUpdate(String sql) method in the Statement object of the Polypheny JDBC Driver is used for executing SQL statements that modify the database in some way (e.g., INSERT, UPDATE, DELETE). It returns an integer indicating the number of rows affected by the statement.

Parameters:

This method throws an SQLException if a database access error occurs, the method is called on a closed Statement, the SQL statement returns a ResultSet object, or the method is called on a PreparedStatement or CallableStatement.

Return Value:

The method returns the row count for SQL Data Manipulation Language (DML) statements or 0 for SQL statements that return nothing.

Usage:

try (
    Connection connection = DriverManager.getConnection( "jdbc:polypheny://..." );
    Statement statement = connection.createStatement();
) {
    int rowsAffected = statement.executeUpdate( "UPDATE my_table SET column_name = 'new_value' WHERE condition_column = 'some_value'" );
    System.out.println( "Rows affected: " + rowsAffected );
} catch ( SQLException e ) {
    e.printStackTrace();
}

This example demonstrates how to use the executeUpdate method to perform an update operation on a hypothetical table and then print out the number of rows affected.

executeQuery

public ResultSet executeQuery(String sql)
            throws SQLException

The executeQuery( String sql ) method in the Statement object of the Polypheny JDBC Driver is designed to execute SQL queries that return a single ResultSet object, typically SELECT statements. The primary objective of this method is to run read-only operations on the database.

Parameters:

This method throws a SQLException if a database access error occurs, the method is called on a closed Statement, the SQL statement does not produce a ResultSet object, or the method is called on a PreparedStatement or CallableStatement.

Usage:

try (
    Connection connection = DriverManager.getConnection( "jdbc:polypheny://..." );
    Statement statement = connection.createStatement();
) {
    ResultSet rs = statement.executeQuery( "SELECT * FROM my_table" );
    while ( rs.next() ) {
        // Process the result set...
    }
} catch ( SQLException e ) {
    e.printStackTrace();
}

executeBatch and executeLargeBatch

public int[] executeBatch()
            throws SQLException

public long[] executeLargeBatch()
            throws SQLException

The methods executeBatch() and executeLargeBatch() of the Statement object in the Polypheny JDBC Driver allow for executing multiple SQL statements in a single batch, which can reduce the number of database round-trips, thus improving performance. The two methods differ in the type of return values they provide:

• executeBatch: Returns an array of int indicating the number of rows affected by each command in the batch.
• executeLargeBatch: Returns an array of long for situations where the number of rows affected by a command may exceed the range of int.

Both methods throw an SQLException if all commands do not execute successfully. In the case of a failed batch, the SQLException will provide information about the command that failed, the reason for the failure.

Usage:

try (
        Connection connection = DriverManager.getConnection( "jdbc:polypheny://..." );
        Statement statement = connection.createStatement();
) {
    // Add commands to the batch.
    statement.addBatch( "INSERT INTO my_table (id, name) VALUES (1, 'John')" );
    statement.addBatch( "INSERT INTO my_table (id, name) VALUES (2, 'Jane')" );

    // Execute the batch
    int[] updateCounts = statement.executeBatch();

    // Alternatively, for larger batches:
    // long[] largeUpdateCounts = statement.executeLargeBatch()
    for ( int count : updateCounts ) {
        System.out.println( "Rows affected: " + count );
    }

} catch ( BatchUpdateException e ) {
    // Handle failed batch commands
    e.printStackTrace();
}

addBatch

public void addBatch(String sql)
            throws SQLException

The addBatch(String sql) method of the Statement object in the Polypheny JDBC Driver is used to add an SQL statement to the current batch of commands for the Statement object. This functionality allows for multiple SQL statements to be executed together in a single batch, improving efficiency by reducing the number of separate round-trips to the database.

Parameters:

This method throws an SQLException the method is called on a closed Statement.

Usage:

try (
        Connection connection = DriverManager.getConnection( "jdbc:polypheny://..." );
        Statement statement = connection.createStatement();
) {
    // Add multiple SQL commands to the batch.
    statement.addBatch( "INSERT INTO my_table (id, name) VALUES (1, 'John')" );
    statement.addBatch( "INSERT INTO my_table (id, name) VALUES (2, 'Jane')" );

    // Execute the batch.
    int[] updateCounts = statement.executeBatch();

    // Handle the results.
    for ( int count : updateCounts ) {
        System.out.println( "Affected rows: " + count );
    }
} catch ( SQLException e ) {
    e.printStackTrace();
}

clearBatch

public void clearBatch()
            throws SQLException

The clearBatch() method of the Statement object in the Polypheny JDBC Driver allows you to clear previously added SQL commands from the current batch. This is useful if you need to discard a batch of commands before they are executed or if you want to reuse the same Statement object for a different batch of commands.

This method throws an SQLException if the method is called on a closed Statement.

Usage:

try (
        Connection connection = DriverManager.getConnection( "jdbc:polypheny://..." );
        Statement statement = connection.createStatement();
) {
    // Add commands to the batch.
    statement.addBatch( "INSERT INTO my_table (id, name) VALUES (1, 'John')" );
    statement.addBatch( "INSERT INTO my_table (id, name) VALUES (2, 'Jane')" );

    // Clear the batch.
    statement.clearBatch();

    // The batch is now empty, so the following line would have no effect.
    int[] updateCounts = statement.executeBatch();

} catch ( SQLException e ) {
    e.printStackTrace();
}

getWarnings

public SQLWarning getWarnings()
            throws SQLException

The method getWarnings() of the Statement object in the Polypheny JDBC Driver retrieves the first SQLWarning object for this statement if any. SQLWarning objects are a subclass of SQLException that deal with database access warnings. Warnings do not stop the execution of an application, as exceptions do; they simply alert the user that something did not happen as planned.

Return Value:

clearWarnings

public void clearWarnings()
            throws SQLException

The clearWarnings() method of the Statement object in the Polypheny JDBC Driver is used to clear all SQLWarning objects that have been reported for this connection. After calling this method, the getWarnings method will return null until a new warning is reported for the connection.

close

public void close()
            throws SQLException

The close() method of the Statement object in the Polypheny JDBC Driver is utilized to release the resources associated with the statement and to discard any pending results. Closing a statement will also close its associated ResultSet objects if they haven’t been closed already. To free up resources and prevent potential memory leaks, it’s advisable to close a Statement object once it’s no longer in use.

This method throws an SQLException if a database access error occurs or the method is called on a closed Statement.

isClosed

public boolean isClosed()
            throws SQLException

The isClosed() method of the Statement object in the Polypheny JDBC Driver checks whether the statement has been closed. A statement is closed if the method close has been called on it, or if it was automatically closed. Checking the state of a statement can help prevent unintended operations on a closed statement, which can lead to exceptions.

This method throws an SQLException if a database access error occurs.

Return Values:

closeOnCompletion

public void closeOnCompletion()
            throws SQLException

The closeOnCompletion() method of the Statement object in the Polypheny JDBC Driver sets the current Statement to be automatically closed when its associated ResultSet object(s) have been closed. This ensures that resources associated with the Statement are released without the need for an explicit close call once the ResultSet is no longer needed.

This method throws an SQLException if a database access error occurs or if the method is called on a closed Statement.

Usage:

try (
        Connection connection = DriverManager.getConnection( "jdbc:polypheny://..." );
        Statement statement = connection.createStatement();
) {
    statement.closeOnCompletion();  // Set the statement to close automatically when the ResultSet is closed.
    ResultSet resultSet = statement.executeQuery( "SELECT * FROM my_table" );
    // Process the result set...
    resultSet.close(); // The associated statement will be closed automatically after this.
} catch ( SQLException e ) {
    e.printStackTrace();
}

isCloseOnCompletion

public boolean isCloseOnCompletion()
            throws SQLException

The isCloseOnCompletion() method of the Statement object in the Polypheny JDBC Driver checks whether the current Statement has been configured to close automatically when its associated ResultSet object has been closed.

Return Value:

This method throws an SQLException if a database access error occurs or if the method is called on a closed Statement.

getConnection

public Connection getConnection()
            throws SQLException

The getConnection() method of the Statement object in the Polypheny JDBC Driver retrieves the current connection that produced this Statement object. This allows users to interact with the database connection that is associated with a particular statement. The retrieved Connection object is the same connection on which the statement was created.

This method throws an SQLException if a database access error occurs or the method is called on a closed Statement.

Return Values:

Usage:

try (
        Connection connection = DriverManager.getConnection( "jdbc:polypheny://..." );
        Statement statement = connection.createStatement();
) {
    Connection retrievedConnection = statement.getConnection();

    if ( connection == retrievedConnection ) {
        System.out.println( "The retrieved connection is the same as the original." );
    }

} catch ( SQLException e ) {
    e.printStackTrace();
}

setFetchDirection and getFetchDirection

public void setFetchDirection(int direction)
            throws SQLException

public int getFetchDirection()
            throws SQLException

The methods setFetchDirection(int direction) and getFetchDirection() of the Statement object in the Polypheny JDBC Driver are used to set or read the current fetch direction for the ResultSet objects produced by this Statement object. Polypheny only supports the direction ResultSet.FETCH_FORWARD. Thus getFetchDirection() throws an SQLExcpetion if a direction other than ResultSet.FETCH_FORWARD is passed as a parameter.

Both methods throw an SQLException if called on a closed Statement.

Parameters:

Return Value:

Usage:

try (
        Connection connection = DriverManager.getConnection( "jdbc:polypheny://..." );
        Statement statement = connection.createStatement();
) {
    statement.setFetchDirection( ResultSet.FETCH_FORWARD );
    int fetchDirection = statement.getFetchDirection();
} catch ( SQLException e ) {
    e.printStackTrace();
}

setFetchSize and getFetchSize

public void setFetchSize(int rows)
            throws SQLException

public int getFetchSize()
            throws SQLException

The setFetchSize(int rows) and getFetchSize() methods of the Statement object in the Polypheny JDBC Driver are used to set or read the the number of rows that should be fetched from the database when more rows are needed. The value set by this method can be overridden by the driver based on system or query specifics. While the JDBC standard allows for the fetch size to be set as a hint for potential optimization, it’s important to note that the Polypheny JDBC Driver might not always use the provided value, and in some cases, might ignore it altogether.

Parameters:

Both methods throw an SQLException if the given fetch size is negative or if it’s called on a closed Statement.

Return Value:

Usage:

try (
        Connection connection = DriverManager.getConnection( "jdbc:polypheny://..." );
        Statement statement = connection.createStatement();
) {
    statement.setFetchSize( 250 );
    int fetchSize = statement.getFetchSize();
} catch ( SQLException e ) {
    e.printStackTrace();
}

setMaxFieldSize and getMaxFieldSize

public void setMaxFieldSize(int max)
            throws SQLException

public int getMaxFieldSize()
            throws SQLException

The setMaxFieldSize(int max) and getMaxFieldSize() method of the Statement object of the Polypheny JDBC Driver are used to set or read the limit for the maximum number of bytes or characters that can be returned for any column value. Values larger than the set limit are truncated. A value of zero implies there’s no limit.

Those methods throw an SQLException if the size limit is a negative value, if a database access error occurs, or if the method is called on a closed Statement.

Parameters:

Return Value:

Usage:

try (
        Connection connection = DriverManager.getConnection( "jdbc:polypheny://..." );
        Statement statement = connection.createStatement();
) {
    statement.setMaxFieldSize( 255 );
    int maxFieldSize = statement.getMaxFieldSize();
} catch ( SQLException e ) {
    e.printStackTrace();
}

setMaxRows and getMaxRows

public void setMaxRows(int max)
            throws SQLException

public int getMaxRows()
            throws SQLException

The setMaxRows(int max) and getMaxRows() methods in the Statement object of the Polypheny JDBC Driver are used to set and retrieve, respectively, the limit for the maximum number of rows that any ResultSet object can contain, which is generated by the Statement. If the limit is exceeded, the excess rows are silently dropped.

Parameters:

Return Value:

Usage:

try (
        Connection connection = DriverManager.getConnection( "jdbc:polypheny://..." );
        Statement statement = connection.createStatement();
) {
    statement.setMaxRows( 10 ); // Sets a limit of 10 rows for any ResultSet object from this Statement
    ResultSet resultSet = statement.executeQuery( "SELECT * FROM my_table" );
    // Process the result set...
    int maxRows = statement.getMaxRows();
    System.out.println( "Max Rows: " + maxRows ); // It will print 10
} catch ( SQLException e ) {
    e.printStackTrace();
}

setLargeMaxRows and getLargeMaxRows

public void setLargeMaxRows(long max)
            throws SQLException

public long getLargeMaxRows()
            throws SQLException

The setLargeMaxRows(long max) and getLargeMaxRows() methods in the Statement object of the Polypheny JDBC Driver facilitate setting and retrieving the limit for the maximum number of rows any ResultSet object, generated by the Statement, can accommodate. When this specified limit is surpassed, the additional rows are unobtrusively discarded.

Parameters:

Return Value:

Usage:

try (
        Connection connection = DriverManager.getConnection( "jdbc:polypheny://..." );
        Statement statement = connection.createStatement();
) {
    statement.setLargeMaxRows( 1000L ); // Set a cap of 1000 rows for any ResultSet object from this Statement
    ResultSet resultSet = statement.executeQuery( "SELECT * FROM my_table" );
    // Go through the result set...
    long maxRows = statement.getLargeMaxRows();
    System.out.println( "Max Rows: " + maxRows ); // It will display 1000
} catch ( SQLException e ) {
    e.printStackTrace();
}

setQueryTimeout and getQueryTimeout

public void setQueryTimeout(int seconds)
            throws SQLException

public int getQueryTimeout()
            throws SQLException

The setQueryTimeout(int seconds) and getQueryTimeout() methods in the Statement object of the Polypheny JDBC Driver provide functionality to set and retrieve the maximum duration (in seconds) that the system will wait for a query to execute. If the given time is exceeded, an SQLTimeoutException is thrown.

Parameters:

For setQueryTimeout(int seconds):

Return Value:

For getQueryTimeout():

Usage:

try (
        Connection connection = DriverManager.getConnection( "jdbc:polypheny://..." );
        Statement statement = connection.createStatement();
) {
    statement.setQueryTimeout( 30 ); // Set a maximum execution time of 30 seconds for the query
    ResultSet resultSet = statement.executeQuery( "SELECT * FROM my_large_table" );
    // Process the result set...
    int timeout = statement.getQueryTimeout();
    System.out.println( "Current Query Timeout: " + timeout ); // It will print 30
} catch ( SQLTimeoutException e ) {
    System.out.println( "Query took too long!" );
} catch ( SQLException e ) {
    e.printStackTrace();
}

getResultSetConcurrency

public int getResultSetConcurrency()
            throws SQLException

The getResultSetConcurrency() method of the Statement object in the Polypheny JDBC Driver retrieves the result set concurrency for ResultSet objects generated by this Statement. The concurrency mode determines how the ResultSet can be navigated and whether its rows can be updated.

Return Value:

This method throws an SQLException if it’s called on a closed Statement.

getResultSetHoldability

public int getResultSetHoldability()
            throws SQLException

The getResultSetHoldability() method of the Statement object in the Polypheny JDBC Driver retrieves the current result set holdability for ResultSet objects generated from this Statement object. In the JDBC specification, the holdability of a result set indicates whether it will remain open after a commit. This method throws an SQLException if a database access error occurs or the method is called on a closed Statement.

Return Values:

getResultSetType

public int getResultSetType()
            throws SQLException

The getResultSetType() method of the Statement object in the Polypheny JDBC Driver retrieves the result set type for ResultSet objects generated by this Statement. The type determines how the ResultSet can be navigated.

Return Value:

This method throws an SQLException if it’s called on a closed Statement.

setPoolable and isPoolable

public void setPoolable(boolean poolable)
            throws SQLException

public boolean isPoolable()
            throws SQLException

The setPoolable(boolean poolable) and isPoolable() methods of the Statement object in the Polypheny JDBC Driver are used to set or retrieves the hint provided to the connection pool manager regarding whether the Statement object should be pooled. This value indicates the suggested pooling behavior of the Statement and does not necessarily reflect its actual status in a connection pool.

This method throws an SQLException if a database access error occurs or if the method is called on a closed Statement.

Parameters:

Return Value:

setCursorName

public void setCursorName(String name)
            throws SQLException

The setCursorName(String name) method of the Statement object in JDBC is intended to set a name for the statement’s cursor. Naming a cursor can be especially useful when multiple cursors are used in the same transaction or when the cursor’s name needs to be referenced in subsequent operations.

Parameters:

This method throws an SQLFeatureNotSupportedException due to it being unsupported in the Polypheny JDBC Driver.

isWrapperFor

public boolean isWrapperFor(Class<?> iface)
            throws SQLException

The isWrapperFor(Class<?> iface) method of the Statement object in the Polypheny JDBC Driver is a part of the JDBC API designed to determine if the current object (in this context, the Statement instance) wraps or implements a specific interface. This method is typically used in conjunction with the unwrap method, allowing applications to verify if an object can be unwrapped to a specific type before actually attempting the unwrap.

For the Polypheny JDBC Driver, this method can be utilized to check if the Statement provides any Polypheny-specific features or interfaces before unwrapping it.

Parameters:

This method throws an SQLException if a database access error occurs or the method is called on a closed Statement.

Usage:

try (
        Connection connection = DriverManager.getConnection( "jdbc:polypheny://..." );
        Statement statement = connection.createStatement();
) {
    if ( statement.isWrapperFor( PolyphenyStatement.class ) ) {
        // The statement can be safely unwrapped to PolyphenyStatement
        PolyphenyStatement polyphenyStatement = statement.unwrap( PolyphenyStatement.class );
        // Use polyphenyStatement for specific operations...
    }
} catch ( SQLException e ) {
    e.printStackTrace();
}

unwrap

public <T> T unwrap(Class<T> iface)
            throws SQLException

The unwrap(Class<T> iface) method of the Statement object in the Polypheny JDBC Driver is a standard method provided in the JDBC API. It allows the caller to retrieve an object of a specific interface type that may be wrapped by the current instance. This is particularly useful for applications that need to use extensions or features of the underlying database driver that aren’t part of the standard JDBC API.

In the context of the Polypheny JDBC Driver, this method can be employed to access Polypheny-specific features or properties that are not encapsulated by standard JDBC interfaces.

Parameters:

This method throws an SQLException if the Statement does not implement the given interface or if there’s a database access error.

Usage:

Here’s an illustrative example to demonstrate the usage of unwrap:

try (
        Connection connection = DriverManager.getConnection( "jdbc:polypheny://..." );
        Statement statement = connection.createStatement();
) {
    if ( statement.isWrapperFor( PolyphenyStatement.class ) ) {
        PolyphenyStatement polyphenyStatement = statement.unwrap( PolyphenyStatement.class );
        // Utilize the polyphenyStatement to call Polypheny-specific methods...
    }
} catch ( SQLException e ) {
    e.printStackTrace();
}

setEscapeProcessing

public void setEscapeProcessing(boolean enable)
            throws SQLException

The setEscapeProcessing(boolean enable) method in the Statement object of the Polypheny JDBC Driver is meant to provide the ability to enable or disable the JDBC driver’s escape processing mechanism. In typical JDBC drivers, when escape processing is enabled, it means that the JDBC driver will scan for and expand any escape codes present in the SQL statement before sending it to the database.

However, in Polypheny, this functionality is not yet supported. Regardless of the value set using this method, escape processing will not be performed by the Polypheny JDBC driver.

Parameters:

Previous

Connection

Next

Overview