JDBC Driver - Connection

The Connection object in the Polypheny JDBC Driver serves as the entry point ofr the interaction with a Polypheny database. It represents a single database connection session and facilitates sending SQL statements to the database, managing transactions, and obtaining metadata about the database structure and capabilities. Designed with adherence to JDBC standards, this object offers developers a consistent and familiar interface for database operations.

createStatement

public Statement createStatement()
            throws SQLException
public Statement createStatement(int resultSetType, int resultSetConcurrency)
            throws SQLException
public Statement createStatement(int resultSetType, int resultSetConcurrency, int resultSetHoldability)
            throws SQLException

The createStatement method in the Polypheny JDBC Driver is used to create a Statement object, which is used to execute SQL queries on the connected database. This method is overloaded, allowing to specify different configurations of how ResultSets, produced by executing SQL statements, should behave.

This method throws a SQLException if a database access error occurs, an unsupported value is set for any of the parameters or if the method is invoked on a closed connection.

There are three primary aspects you can control when creating a Statement:

  1. ResultSet Type: Determines how the cursor behaves. For instance, whether you can only move forward or if you can scroll through the results in both directions.

  2. ResultSet Concurrency: Dictates if the ResultSet can be updated or is read-only.

  3. ResultSet Holdability (in some overloads): Specifies the behavior of the ResultSet’s cursor after a commit operation.

The basic createStatement method, with no arguments, provides default values for these settings. The other overloaded versions allow you to specify one or more of these aspects according to your needs. The values ResultSet.TYPE_FORWARD_ONLY and ResultSet.CONCUR_READ_ONLY are used as defaults.

Method Signature Description
createStatement() Produces a default Statement object for executing SQL statements without parameters.
createStatement(int resultSetType, int resultSetConcurrency) Produces a Statement object that generates ResultSet objects with the specified type and concurrency.
createStatement(int resultSetType, int resultSetConcurrency, int resultSetHoldability) Produces a Statement object that generates ResultSet objects with the specified type, concurrency, and holdability.

Available ResuSetTypes:

Constant Integer Value Description
ResultSet.TYPE_FORWARD_ONLY 1003 Only move forward in ResultSet
ResultSet.TYPE_SCROLL_INSENSITIVE 1004 Scrollable but not sensitive to changes made by others

Available Concurrency Modes:

Constant Integer Value Description
ResultSet.CONCUR_READ_ONLY 1007 ResultSet cannot be updated

Available Holdability Modes:

Constant Integer Value Description
ResultSet.CLOSE_CURSORS_AT_COMMIT 2 Close cursors after a commit operation

All values other then those listed above cause an SQLException to be thrown when passed to any of the createStatement methods.

Usage:

createStatement(): Default behavior with ResultSet.TYPE_FORWARD_ONLY and ResultSet.CONCUR_READ_ONLY.

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

createStatement(int resultSetType, int resultSetConcurrency) Specifies the type of ResultSet (e.g., scrollable) and its concurrency mode.

try (
        Connection connection = DriverManager.getConnection( "jdbc:polypheny://localhost:20590" );
        Statement statement = connection.createStatement( ResultSet.TYPE_SCROLL_INSENSITIVE, ResultSet.CONCUR_READ_ONLY );
        ResultSet resultSet = statement.executeQuery( "SELECT * FROM tableName" );
) {
    resultSet.last();  // Move to the last row
    while ( resultSet.previous() ) {
        // Process the result set in reverse order...
    }
} catch ( SQLException e ) {
    e.printStackTrace();
}

createStatement(int resultSetType, int resultSetConcurrency, int resultSetHoldability): Specifies the holdability of the ResultSet cursor.

try (
        Connection connection = DriverManager.getConnection( "jdbc:polypheny://localhost:20590" );
        Statement statement = connection.createStatement( ResultSet.TYPE_SCROLL_INSENSITIVE, ResultSet.CONCUR_READ_ONLY, ResultSet.CLOSE_CURSORS_AT_COMMIT );
        ResultSet resultSet = statement.executeQuery( "SELECT * FROM tableName" );
) {
    // Update the result
} catch ( SQLException e ) {
    e.printStackTrace();
}

prepareStatement

public PreparedStatement prepareStatement(String sql)
            throws SQLException
public PreparedStatement prepareStatement(String sql, int autoGeneratedKeys)
            throws SQLException
public PreparedStatement prepareStatement(String sql, int[] columnIndexes)
            throws SQLException
public PreparedStatement prepareStatement(String sql, String[] columnNames)
            throws SQLException
public PreparedStatement prepareStatement(String sql, int resultSetType, int resultSetConcurrency)
            throws SQLException
public PreparedStatement prepareStatement(String sql, int resultSetType, int resultSetConcurrency, int resultSetHoldability)
            throws SQLException
All overloads including autoGeneratedKeys, column names and column indexes are not yet supported.

The prepareStatement method in the Polypheny JDBC Driver is utilized to create a PreparedStatement object, allowing for the execution of SQL queries with a predefined set of parameters. This enhances performance as a prepared statement can be executed on multiple sets of parameters. This also reduces the risk of SQL injection.

This method will throw a SQLException if a database access error occurs, an unsupported value is set for any of the parameters, or if the method is called on a closed connection.

There are three primary aspects you can control when creating a PreparedStatement:

  1. ResultSet Type: Determines the behavior of the cursor, such as forward-only or bidirectional navigation through results.

  2. ResultSet Concurrency: Specifies if the ResultSet is updatable or read-only.

  3. ResultSet Holdability: Sets the behavior of the ResultSet cursor post-commit.

The base prepareStatement method, using a single SQL string as an argument, assigns the default values to the parameters above. The other overloaded versions allow customization of these properties. The defaults are ResultSet.TYPE_FORWARD_ONLY and `ResultSet.CONCUR_READ_ONLY.

Method Signature Description
prepareStatement( String sql ) Generates a PreparedStatement object for executing parameterized SQL statements with defaults.
prepareStatement( String sql, int resultSetType, int resultSetConcurrency ) Produces a PreparedStatement tailored with the chosen type and concurrency for the ResultSet.
prepareStatement( String sql, int resultSetType, int resultSetConcurrency, int resultSetHoldability ) Configures a PreparedStatement with designated type, concurrency, and holdability for the ResultSet.

Available ResultSetTypes:

Constant Integer Value Description
ResultSet.TYPE_FORWARD_ONLY 1003 Only forward movement in ResultSet
ResultSet.TYPE_SCROLL_INSENSITIVE 1004 Scrollable, insensitive to external changes

Available Concurrency Modes:

Constant Integer Value Description
ResultSet.CONCUR_READ_ONLY 1007 ResultSet is immutable

Available Holdability Modes:

Constant Integer Value Description
ResultSet.CLOSE_CURSORS_AT_COMMIT 2 Closes cursors post-commit

All values other then those listed above caus an SQLException to be thrown when passed to any of the createStatement methods.

Usage:

prepareStatement( String sql ): Default usage with ResultSet.TYPE_FORWARD_ONLY and ResultSet.CONCUR_READ_ONLY.

try (
        Connection connection = DriverManager.getConnection( "jdbc:polypheny://localhost:20590" );
        PreparedStatement preparedStatement = connection.prepareStatement( "SELECT * FROM tableName WHERE id = ?" );
) {
    preparedStatement.setInt( 1, 123 );
    ResultSet resultSet = preparedStatement.executeQuery();
    while ( resultSet.next() ) {
        // Process the result set...
    }
} catch ( SQLException e ) {
    e.printStackTrace();
}

prepareStatement( String sql, int resultSetType, int resultSetConcurrency ):

Setting a specific ResultSet type and concurrency.

try (
        Connection connection = DriverManager.getConnection( "jdbc:polypheny://localhost:20590" );
        PreparedStatement preparedStatement = connection.prepareStatement( "SELECT * FROM tableName", ResultSet.TYPE_SCROLL_INSENSITIVE, ResultSet.CONCUR_READ_ONLY );
        ResultSet resultSet = preparedStatement.executeQuery() ) {
    resultSet.last();
    while ( resultSet.previous() ) {
        // Process the result set in reverse...
    }
} catch (
        SQLException e ) {
    e.printStackTrace();
}

prepareStatement( String sql, int resultSetType, int resultSetConcurrency, int resultSetHoldability )`:

Determining holdability of the ResultSet cursor.

try (
        Connection connection = DriverManager.getConnection( "jdbc:polypheny://localhost:20590" );
        PreparedStatement preparedStatement = connection.prepareStatement( "SELECT * FROM emps", ResultSet.TYPE_SCROLL_INSENSITIVE, ResultSet.CONCUR_READ_ONLY, ResultSet.CLOSE_CURSORS_AT_COMMIT );
        ResultSet resultSet = preparedStatement.executeQuery();
        // Manipulate or navigate the result...
) {
    // ...
} catch ( SQLException e ) {
    e.printStackTrace();
}

prepareCall

public CallableStatement prepareCall(String sql)
            throws SQLException
public CallableStatement prepareCall(String sql, int resultSetType, int resultSetConcurrency)
            throws SQLException
public CallableStatement prepareCall(String sql, int resultSetType, int resultSetConcurrency, int resultSetHoldability)
            throws SQLException
All overloads of the prepareCall method are not yet supported in Polypheny. Attempting to use this method will throw an SQLFeatureNotSupportedException.

The prepareCall method is typically used to create a CallableStatement object. This object enables the invocation of database stored procedures.

However, as of the current version, Polypheny does not yet support callable procedures. As a consequence, invoking the prepareCall method as well as any of its overloads will result in an SQLFeatureNotSupportedException.

commit

public void commit()
            throws SQLException

The commit() method of the Connection object in the Polypheny JDBC Driver is employed to explicitly commit all changes made since the previous commit or rollback, thus ending a transaction. It makes all changes made since the last commit/rollback permanent and releases any database locks currently held by the connection.

This method is typically used when the connection’s auto-commit mode has been disabled using the setAutoCommit(false) method. It’s imperative to note that if the connection is in auto-commit mode, invoking this method is redundant as every individual SQL statement is treated as a transaction and is automatically committed right after execution.

The commit() method throws an SQLException if a database access error occurs, the method is invoked on a closed connection, or the connection is in auto-commit mode.

Usage:

Here’s how the commit() method can be utilized within the context of managing transaction boundaries:

try ( Connection connection = DriverManager.getConnection( "jdbc:polypheny://localhost:20590" ) ) {
    connection.setAutoCommit( false ); // Start the transaction by setting auto-commit to false

    // Execute some SQL operations here...

    connection.commit();
} catch ( SQLException e ) {
    e.printStackTrace();
}
Explicitly managing transactions using commit() and rollback() provides developers with greater control over data integrity, especially in scenarios involving multiple, related operations. It ensures that all operations within the transaction either complete successfully or none of them do, maintaining the atomicity principle of transactions.

rollback

public void rollback()
            throws SQLException

The rollback() method of the Connection object in the Polypheny JDBC Driver is employed to undo all changes made in the current transaction (except of DDL statements). This is particularly useful in situations where an error occurs, and the changes made during the current transaction need to be discarded.

This method is typically used when the connection’s auto-commit mode has been disabled using the setAutoCommit(false) method. If the connection is in auto-commit mode, invoking the rollback() method will have no effect, since each SQL statement is treated as an individual transaction and is automatically committed immediately after its execution.

The rollback() method throws an SQLException if a database access error occurs, the method is invoked on a closed connection, or the connection is in auto-commit mode.

Usage:

Here’s how the rollback() method can be utilized within the context of managing transaction boundaries:

try ( Connection connection = DriverManager.getConnection( "jdbc:polypheny://localhost:20590" ) ) {
    connection.setAutoCommit( false );

    try {
        // Execute some SQL operations here...

        // Some logic that might fail...

                connection.commit(); // Commit the transaction only if everything is successful
    } catch ( Exception e ) {
        connection.rollback(); // If an error occurs, rollback the transaction
        e.printStackTrace();
    }
} catch ( SQLException e ) {
    e.printStackTrace();
}

abort

public void abort(Executor executor)
            throws SQLException
The abort( Executor executor ) method is not yet supported in the Polypheny JDBC Driver. Invoking this method will result in an exception.

The abort( Executor executor ) method of the Connection object in standard JDBC is designed to terminate long-running operations and to release any database and JDBC resources currently held by the Connection object immediately. It does so using the provided Executor to concurrently close the connection.

However, in the Polypheny JDBC Driver, this method is not yet supported. If invoked, it will throw a SQLFeatureNotSupportedException.

close

public void close()
            throws SQLException

The close() method of the Connection object in the Polypheny JDBC Driver is used to immediately release the database connection and its resources. Closing a connection is crucial for managing database resources.

Once a connection is closed using this method, it can no longer be used to execute any operations. Attempting to use a closed connection will result in an SQLException.

The close() method also ensures that any pending transactions are rolled back. Therefore, it’s a best practice to always ensure that transactions are either explicitly committed using the commit() method or rolled back using the rollback() method before invoking close().

isClosed

public boolean isClosed()
            throws SQLException

The isClosed() method of the Connection object in the Polypheny JDBC Driver provides a way to determine if a connection to the database is still active or if it has been closed. The method returns true if the connection has been closed and false if it’s still active.

It is often used as a preliminary check before performing operations on the connection, especially in scenarios where it’s uncertain if the connection might have been closed due to external factors or previous operations.

isValid

public boolean isValid(int timeout)
            throws SQLException

The isValid( int timeout ) method of the Connection object in the Polypheny JDBC Driver is designed to check whether the connection to the database is still valid and thus alive or not.

Parameters:

Parameter Name Type Description
timeout int Specifies the number of seconds the driver should wait for a response from the database. If the timeout is exceeded, the conneciton is declared invalid.

Returns:

Type Description
boolean Returns true if the connection is valid. Returns false if the connection is not valid or if there’s no response within the specified timeout.

Usage:

Here’s a basic example illustrating the use of the isValid() method:

try (
        Connection connection = DriverManager.getConnection( "jdbc:polypheny://localhost:20590" )
) {
    boolean connectionStatus = connection.isValid( 5 );
    if ( connectionStatus ) {
        System.out.println( "The connection is valid." );
    } else {
        System.out.println( "The connection is not valid." );
    }
} catch ( SQLException e ) {
    e.printStackTrace();
}

clearWarnings

public void clearWarnings()
            throws SQLException
Polypheny does not yet support the concept of SQL warnings. Even though this method is provided for JDBC consistency, there are no warnings to clear. Thus, the getWarnings method always returns null, irrespective of whether clearWarnings has been called.

The clearWarnings() method of the Connection 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.

getWarnings

public SQLWarning getWarnings()
            throws SQLException
Polypheny does not yet support the concept of SQL warnings. Consequently, the getWarnings method always returns null, which is the JDBC standard-conform value to express that no warnings occurred.

The method getWarnings() of the Connection object in the Polypheny JDBC Driver retrieves the first SQLWarning object for this connection 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:

Type Description
SQLWarning The first SQLWarning object or null if there are no warnings.

setSavepoint, releaseSavepoint and rollback

public Savepoint setSavepoint()
            throws SQLException
public Savepoint setSavepoint(String name)
            throws SQLException
public void releaseSavepoint(Savepoint savepoint)
            throws SQLException
public void rollback(Savepoint savepoint)
            throws SQLException
setSavepoint, setSavepoint, releaseSavepoint and rollbackSavepoint are not yet supported in Polypheny. Any attempt to use these methods will result in a SQLFeatureNotSupportedException.

The methods setSavepoint(), setSavepoint( String name ), releaseSavepoint( Savepoint savepoint ) and rollback( Savepoint savepoint ) of the Connection object in the Polypheny JDBC Driver are associated with transaction control mechanisms that allow operations within a transaction to be explicitly saved, released, or rolled back to a specific state.

However, in Polypheny, these advanced transaction control features are currently not yet supported. Invoking any of these methods will result in a SQLFeatureNotSupportedException.

setAutoCommit and getAutoCommit

public void setAutoCommit(boolean autoCommit)
            throws SQLException
public boolean getAutoCommit()
            throws SQLException

The setAutoCommit( boolean autoCommit ) and getAutoCommit() methods of the Connection object in the Polypheny JDBC Driver deal with transaction boundaries.

The setAutoCommit() method allows the user to enable or disable the default auto-commit behavior for the connection. When auto-commit mode is enabled (the default), every individual SQL statement is treated as a single transaction, and it’s automatically committed after execution. When disabled, the application must manually manage transaction boundaries using the commit() or rollback() methods.

When auto-commit mode is enabled and an executed statement produces a result set, the transaction is not committed until all result rows have been fetched or the statement has been closed. This behavior can have implications on database locks and resource utilization.

The getAutoCommit() method retrieves the current state of the auto-commit mode for this Connection object.

Return Value (for getAutoCommit):

Return Type Description
boolean Indicates the current state of auto-commit mode for this Connection object. true if auto-commit mode is enabled, false otherwise.

Usage:

try (
        Connection connection = DriverManager.getConnection( "jdbc:polypheny://localhost:20590" );
) {
    // Disable auto-commit mode
    connection.setAutoCommit( false );

    // Execute some SQL statements...
    // ...

    // Manually commit the transaction
    connection.commit();

    // Check the auto-commit mode
    boolean isAutoCommit = connection.getAutoCommit();
    System.out.println( "Auto-commit mode is: " + (isAutoCommit ? "enabled" : "disabled") );
} catch ( SQLException e ) {
    e.printStackTrace();
}

setReadOnly and isReadOnly

public void setReadOnly(boolean readOnly)
            throws SQLException
public boolean isReadOnly()
            throws SQLException

The setReadOnly( boolean readOnly ) and isReadOnly() methods of the Connection object in the Polypheny JDBC Driver pertain to the transaction’s read-only status.

The setReadOnly() method allows the user to enable or disable the read-only mode for the connection. When a connection is in read-only mode, attempting to execute a modification to any of the database’s tables will result in an SQL exception.

Currently this parameter is ignored by both the Polyheny JDBC driver as well as Polypheny.

The isReadOnly() method retrieves the current state of the read-only mode for this Connection object.

Return Value:

Return Type Description
boolean Indicates the current state of read-only mode for this Connection object. true if read-only mode is enabled, false otherwise.

Usage:

try (
        Connection connection = DriverManager.getConnection( "jdbc:polypheny://localhost:20590" );
) {
    // Enable read-only mode
    connection.setReadOnly( true );

    // Check the read-only mode
    boolean isReadOnlyMode = connection.isReadOnly();
    System.out.println( "Read-only mode is: " + (isReadOnlyMode ? "enabled" : "disabled") );
} catch ( SQLException e ) {
    e.printStackTrace();
}

setClientInfo

public void setClientInfo(Properties properties)
            throws SQLClientInfoException
public void setClientInfo(String name, String value)
            throws SQLClientInfoException

The setClientInfo(...) methods of the Connection object in the Polypheny JDBC Driver allow users to set client-specific metadata properties on the connection. These properties provide valuable context about the application using the connection. For instance, details about its name, version, hostname of the client machine, and the username can be beneficial for tracking, debugging, or performance tuning from the database side.

Default Client Info Properties:

Polypheny provides a set of default client info properties that can be set using the setClientInfo methods. Here is a list of these default properties:

Property Name Default Value Max Length Description
ApplicationName "" 2,147,483,647 The name of the application currently utilizing the connection.
ApplicationVersionString "" 2,147,483,647 Version description of the application currently utilizing the connection.
ClientHostname "" 2,147,483,647 The hostname of the computer the application using the connection is running on.
ClientUser "" 2,147,483,647 The name of the user that the application using the connection is performing work for. This may not be the same as the user name that was used in establishing the connection..
These properties are provided by default, but their actual interpretation and usage might depend on the setup of polypheny.

Additional Client Info Properties:

In addition to the default client info properties arbitrary pairs of strings can be set as properties.

Overloads:

There are two primary overloads for the setClientInfo method:

Method Signature Description
setClientInfo( String name, String value ) Sets the value of the specified client info property.
setClientInfo( Properties properties ) Sets the values of multiple client info properties using the given Properties object.

Usage:

Sets a single property for the connection:

try ( Connection connection = DriverManager.getConnection( "jdbc:polypheny://localhost:20590" ) ) {
    connection.setClientInfo( "ApplicationName", "MyApp" );
} catch ( SQLException e ) {
    e.printStackTrace();
}

Sets multiple properties for the connection at once:

try ( Connection connection = DriverManager.getConnection( "jdbc:polypheny://localhost:20590" ) ) {
    Properties clientProperties = new Properties();
    clientProperties.setProperty( "ApplicationName", "MyApp" );
    clientProperties.setProperty( "ApplicationVersionString", "1.0.0" );
    clientProperties.setProperty( "ClientHostname", "myhost.example.com" );
    clientProperties.setProperty( "ClientUser", "username" );
    connection.setClientInfo( clientProperties );
} catch ( SQLException e ) {
    e.printStackTrace();
}

getClientInfo

public Properties getClientInfo()
            throws SQLException
public String getClientInfo(String name)
            throws SQLException

The getClientInfo methods of the Connection object in the Polypheny JDBC Driver provide a way to retrieve client-specific metadata properties set on the connection. These properties can offer insights about the application using the connection, such as its name, version, client machine’s hostname, and the username.

Default Client Info Properties:

Polypheny comes equipped with a set of default client info properties that can be retrieved using the getClientInfo methods. Here is a breakdown of these default properties:

Property Name Default Value Max Length Description
ApplicationName "" 2,147,483,647 The name of the application currently utilizing the connection.
ApplicationVersionString "" 2,147,483,647 Version description of the application currently utilizing the connection.
ClientHostname "" 2,147,483,647 The hostname of the computer the application using the connection is running on.
ClientUser "" 2,147,483,647 The name of the user that the application using the connection is performing work for. This may not be the same as the user name used in establishing the connection.
The default properties serve as a general guide, but their actual interpretation and the values they return might depend on the setup.

Overloads:

There are two main overloads for the getClientInfo method:

Method Signature Description
getClientInfo() Retrieves the full set of client info properties as a Properties object.
getClientInfo( String name ) Retrieves the value of the specified client info property.

Usage:

Obtain all client info properties for the connection:

try ( Connection connection = DriverManager.getConnection( "jdbc:polypheny://localhost:20590" ) ) {
    Properties clientProperties = connection.getClientInfo();
    // Use the clientProperties...
} catch ( SQLException e ) {
    e.printStackTrace();
}

Retrieve a single property value for the connection:

try ( Connection connection = DriverManager.getConnection( "jdbc:polypheny://localhost:20590" ) ) {
    String appName = connection.getClientInfo( "ApplicationName" );
    System.out.println( "Application Name: " + appName );
} catch ( SQLException e ) {
    e.printStackTrace();
}

getCatalog

public String getCatalog()
            throws SQLException

The method getCatalog() of the Connection object in the Polypheny JDBC Driver retrieves the name of the catalog set for this Connection object using the setCatalog(String catalog) method. In traditional relational database systems, a catalog refers to a subset of the database, and this method is meant to retrieve the current context of the connection.

However, it’s essential to understand that Polypheny does work differently. The value returned by the getCatalog() method is the value it was last set to using the setCatalog method or null if it wasn’t set before. The existence of this method in the Polypheny JDBC Driver is solely for maintaining consistency with the JDBC API.

Return:

Type Description
String The catalog name; the value it was last set to using the setCatalog method, or null if it was never set.

setCatalog

public void setCatalog(String catalog)
            throws SQLException
The implementation of setCatalog in the Polypheny JDBC Driver exists purely for API consistency reasons. Invoking this method only affects the value returned by getCatalog() and has no other impact on database operations.

The method setCatalog( String catalog ) of the Connection object in the Polypheny JDBC Driver is designed to select a specific catalog for the current Connection object. In traditional relational database systems, a catalog often refers to a subset of the database. This method allows the user to set the context to a particular catalog.

However, it’s crucial to note that Polypheny works different. Thus, invoking the setCatalog method has no actual impact on database operations. The sole purpose of implementing this method in the Polypheny JDBC Driver is for consistency with the JDBC API and to set the value that will be returned by the getCatalog() method. It does not affect the behavior or context of the connection in any way.

Parameters:

Name Type Description
catalog String The name of the catalog. Although this value has no effect on database operations, it will be returned by the getCatalog() method.

setHoldability and getHoldability

public void setHoldability(int holdability)
            throws SQLException
public int getHoldability()
            throws SQLException
Polypheny only supports the ResultSet.CLOSE_CURSORS_AT_COMMIT holdability mode. Attempting to set any other mode will result in an SQLException.

The setHoldability( int holdability ) and getHoldability() methods of the Connection object in the Polypheny JDBC Driver pertain to the holdability of ResultSet objects created using this Connection.

The setHoldability( int holdability ) method sets the desired holdability for ResultSet objects created through this connection. Holdability defines whether a result set should be closed when the subsequent transaction is committed.

The getHoldability() method fetches the current holdability setting for ResultSet objects created using this Connection.

Parameters:

Parameter Name Type Description
holdability int Only ResultSet.CLOSE_CURSORS_AT_COMMIT is supported.

Return Value:

Return Type Description
int The current holdability mode. Will always return ResultSet.CLOSE_CURSORS_AT_COMMIT in Polypheny.

Usage:

try (
        Connection connection = DriverManager.getConnection( "jdbc:polypheny://localhost:20590" );
) {
    // Set holdability mode
    connection.setHoldability( ResultSet.CLOSE_CURSORS_AT_COMMIT );

    // Fetch the current holdability mode
    int currentHoldability = connection.getHoldability();
    System.out.println( "Current holdability is: CLOSE_CURSORS_AT_COMMIT" );
} catch ( SQLException e ) {
    e.printStackTrace();
}

setSchema

public void setSchema(String schema)
            throws SQLException

It’s essential to understand the distinction between schemas and namespaces when working with Polypheny to prevent misconceptions. The setSchema method in Polypheny’s JDBC Driver sets the namespace, not a traditional schema.

The setSchema( String schema ) method of the Connection object in the Polypheny JDBC Driver is intended to set the current schema of this connection. However, it’s crucial to understand that Polypheny diverges from the traditional RDBMS model by not employing the standard schema concept. Instead, Polypheny introduces the notion of Namespaces.

Namespaces in Polypheny function similarly to schemas in other databases, serving as containers to group related tables and other database objects. Thus, when using the setSchema method with Polypheny’s JDBC driver, you’re actually setting the current namespace for the connection.

Parameters:

Parameter Name Type Description
schema String The name of the namespace to which this connection should be set.

getSchema

public String getSchema()
            throws SQLException
Be aware of the distinction between schemas and namespaces when working with Polypheny. The getSchema method in Polypheny’s JDBC Driver retrieves the active namespace, not a traditional schema.

The getSchema() method of the Connection object in the Polypheny JDBC Driver is used to retrieve the current schema (in the standard JDBC context) associated with the connection. However, in the Polypheny context, this method returns the current Namespace that has been set or is active for the connection.

Remember, Polypheny does not utilize the traditional concept of schemas. Instead, it operates with the concept of namespaces, which function similarly to schemas in most databases by grouping related tables and other database entities. Thus, when you call the getSchema method, you’re retrieving the current namespace for the connection.

Return Value:

Return Type Description
String The name of the current namespace set for this connection, or null if none has been specified.

setNetworkTimeout and getNetworkTimeout

public void setNetworkTimeout(Executor executor, int milliseconds)
            throws SQLException
public int getNetworkTimeout()
            throws SQLException

The setNetworkTimeout( Executor executor, int milliseconds ) and getNetworkTimeout() methods of the Connection object in the Polypheny JDBC Driver deal with setting and retrieving the timeout value, respectively, that determines how long a client will wait for a database response.

The setNetworkTimeout() method defines the period in milliseconds a client will wait for a database response. If the limit is exceeded, an SQLException is thrown. The Executor parameter, while present for JDBC API compliance, is ignored by the Polypheny driver, and only the timeout in milliseconds is considered.

The getNetworkTimeout() method returns the current timeout value.

The timeout value set by setNetworkTimeout is an upper limit on the time that a driver will wait for a database response. Be cautious when setting this value, as an overly aggressive timeout might cause valid operations to fail.

Parameters:

Parameter Name Type Description
executor Executor The Executor parameter, present for JDBC compliance, but ignored by Polypheny.
milliseconds int The time in milliseconds to wait for the database response.

Return Value:

Return Type Description
int The current timeout value in milliseconds.

Usage:

try (
        Connection connection = DriverManager.getConnection( "jdbc:polypheny://localhost:20590" );
) {
    // Set a network timeout of 5000 milliseconds. Executor parameter is ignored by Polypheny.
    Executor executor = Executors.newSingleThreadExecutor();  // For demonstration, but ignored.
    connection.setNetworkTimeout( executor, 5000 );

    // Fetch the current network timeout value
    int currentTimeout = connection.getNetworkTimeout();
    System.out.println( "Current network timeout is: " + currentTimeout + " milliseconds" );
} catch ( SQLException e ) {
    e.printStackTrace();
}

setTransactionIsolation and getTransactionIsolation

public void setTransactionIsolation(int level)
            throws SQLException
public int getTransactionIsolation()
            throws SQLException
Polypheny only supports the Connection.TRANSACTION_READ_COMMITTED transaction isolation level. Attempts to set any other level will result in an SQLException.

The setTransactionIsolation( int level ) and getTransactionIsolation() methods of the Connection object in the Polypheny JDBC Driver pertain to setting and retrieving the current transaction isolation level, respectively.

The setTransactionIsolation() method allows setting the desired transaction isolation level for this connection. However, in Polypheny, only the Connection.TRANSACTION_READ_COMMITTED level is supported. Any attempt to set a different isolation level will result in an SQLException.

The getTransactionIsolation() method fetches the current transaction isolation level of the connection. For Polypheny, it will always return Connection.TRANSACTION_READ_COMMITTED.

Parameters:

Parameter Name Type Description
level int The desired transaction isolation level, using the Connection constants.

Return Value:

Return Type Description
int The current transaction isolation level. In Polypheny’s case, it always returns Connection.TRANSACTION_READ_COMMITTED.

Usage:

try (
        Connection connection = DriverManager.getConnection( "jdbc:polypheny://localhost:20590" );
) {
    // Set the transaction isolation level. Only TRANSACTION_READ_COMMITTED is supported in Polypheny.
    connection.setTransactionIsolation( Connection.TRANSACTION_READ_COMMITTED );

    // Fetch the current transaction isolation level
    int isolationLevel = connection.getTransactionIsolation();
    System.out.println( "Current transaction isolation level is: " + isolationLevel );
} catch ( SQLException e ) {
    e.printStackTrace();
}

setTypeMap

public void setTypeMap(Map<String, Class<?>> map)
            throws SQLException

The setTypeMap( Map<String,Class<?>> map ) method in the Polypheny JDBC Driver allows you to provide a custom mapping for user-defined SQL types (UDTs) to classes in the Java programming language. By setting this map, you instruct the JDBC driver to automatically convert a UDT to its corresponding Java type when retrieving data from the database.

Each key in the map should be a fully-qualified SQL type name (which is identical to the polypheny type name of the UDT), and its associated value should be the Java class name that implements java.sql.SQLData.

When using setTypeMap, you are effectively setting a custom user-defined SQL type mapping for your connection session. This will be used for subsequent operations that involve UDTs until the connection is closed or a new map is set.

Usage:

Below is a code example demonstrating how one might use the setTypeMap method with the Polypheny JDBC Driver:

try (
        Connection connection = DriverManager.getConnection( "jdbc:polypheny://localhost:20590" );
) {
    Map<String, Class<?>> customTypeMap = new HashMap<>();
    customTypeMap.put( "MY_UDT", MyJavaClass.class );

    connection.setTypeMap( customTypeMap );

    // Now, when querying a table column of type "MY_SCHEMA.MY_UDT",
    // the returned value will be automatically converted to an instance of MyJavaClass.

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

getTypeMap

public Map<String, Class<?>> getTypeMap()
            throws SQLException

The getTypeMap() method in the Polypheny JDBC Driver returns a java.util.Map object that details the custom mapping of user-defined SQL types (UDTs) to classes in the Java programming language. Each key in the map is a fully-qualified SQL type name, while its corresponding value is a class name that implements java.sql.SQLData or java.io.Serializable.

Note that the map only contains the user defined mappings.

Usage:

This code example demonstes how one might use the getTypeMap method when using the Polypheny JDBC Driver:

try (
        Connection connection = DriverManager.getConnection( "jdbc:polypheny://localhost:20590" );
) {
    Map<String, Class<?>> typeMap = connection.getTypeMap();
    if ( typeMap.isEmpty() ) {
        System.out.println( "No custom type mappings found." );
    } else {
        for ( Map.Entry<String, Class<?>> entry : typeMap.entrySet() ) {
            System.out.println( "SQL Type: " + entry.getKey() + " - Java Class: " + entry.getValue().getName() );
        }
    }
} catch ( SQLException e ) {
    e.printStackTrace();
}

nativeSQL

public String nativeSQL(String sql)
            throws SQLException

The nativeSQL( String sql ) method of the Connection object in a typical JDBC Driver translates a SQL statement into the driver’s native SQL grammar. This allows a programmer to write SQL statements that work with multiple databases by converting vendor-specific dialects to a common form.

However, Polypheny supports a variety of SQL dialects in the form of plugins and consequently does not have a native dialect. This method thus has no effect.

createArrayOf

public Array createArrayOf(String typeName, Object[] elements)
            throws SQLException

The createArrayOf( String typeName, Object[] elements ) method in the Connection object of the Polypheny JDBC Driver is a feature that facilitates the creation of an Array object. This Array object represents an SQL ARRAY data type. The method is designed to create arrays that store elements of a specified SQL type and allows you to pass an array of objects as the input data.

Parameters:

Parameter Name Type Description
typeName String Specifies the SQL type name (equals the polypheny type name) of the elements to be stored in the array.
elements Object[] The array that holds the data items to populate the SQL ARRAY. The type of each element must match the specified SQL type (equals the Polypheny type name).

Return Value:

Return Type Description
Array An object that represents the SQL ARRAY data type. This object can then be used in subsequent SQL operations.

Usage:

Here’s a basic example showcasing how you can create an SQL array with integer elements:

try (
        Connection connection = DriverManager.getConnection( "jdbc:polypheny://localhost:20590" );
) {
    Integer[] intArray = new Integer[]{ 1, 2, 3, 4, 5 };
    Array sqlArray = connection.createArrayOf( "INTEGER", intArray );

    // Use the sqlArray in SQL operations, for instance, to insert into a table column of type ARRAY...
} catch ( SQLException e ) {
    e.printStackTrace();
}

createBlob

public Blob createBlob()
            throws SQLException

The createBlob() method of the Connection object of the Polypheny JDBC Driver is used to create an empty instance of the Blob interface. This interface represents a BLOB (Binary Large Object) data type, which stores a large block of binary data, such as an image, audio, or video file. Once created, the Blob can be populated with data using methods like setBytes, setBinaryStream, or setBlob.

Usage:

Here’s a basic example illustrating the creation and usage of a Blob:

try (
        Connection connection = DriverManager.getConnection( "jdbc:polypheny://localhost:20590" );
) {
    Blob myBlob = connection.createBlob();
    byte[] imageData = new byte[]{ 0x00, 0x01, 0x02, 0x03 }; // Some binary data, for instance, an image
    myBlob.setBytes( 1, imageData );
    // Use the Blob in SQL operations...
} catch ( SQLException e ) {
    e.printStackTrace();
}

createClob

public Clob createClob()
            throws SQLException

The createClob() method of the Connection object of the Polypheny JDBC Driver is used to create an empty instance of the Clob interface. This interface represents a CLOB (Character Large Object) data type, which stores a large block of text data, such as a document or character data. Once created, the Clob can be populated with data using methods like setString, setAsciiStream, or setCharacterStream. In Polypheny Clobs and NClobs both store data in UTF-8.

Usage:

try (
        Connection connection = DriverManager.getConnection( "jdbc:polypheny://localhost:20590" );
) {
    Clob myClob = connection.createClob();
    myClob.setString( 1, "This is some test content for the CLOB data type." );

    // Use the Clob in SQL operations...
} catch ( SQLException e ) {
    e.printStackTrace();
}

createNClob

public NClob createNClob()
            throws SQLException

The createNClob() method of the Connection object in the Polypheny JDBC Driver is employed to produce an empty instance of the NClob interface. This interface represents an NCLOB (National Character Large Object) data type, designed for storing large blocks of Unicode text data. After creation, the NClob can be populated with data through methods such as setString, setAsciiStream, or setCharacterStream. In Polypheny Clobs and NClobs both store data in UTF-8.

Usage:

try (
        Connection connection = DriverManager.getConnection( "jdbc:polypheny://localhost:20590" );
) {
    NClob myNClob = connection.createNClob();
    myNClob.setString( 1, "This is some Unicode text content for the NCLOB data type." );

    // Use the NClob in SQL operations...
} catch ( SQLException e ) {
    e.printStackTrace();
}

createSQLXML

public SQLXML createSQLXML()
            throws SQLException
In the current version of Polypheny, the createSQLXML() method is not yet supported. Invoking this method will throw an SQLFeatureNotSupportedException.

The createSQLXML() method of the Connection object in the Polypheny JDBC Driver is meant to produce an instance of the SQLXML interface. This interface represents an SQL XML data type, allowing for the storage and retrieval of XML data within SQL operations.

createStruct

public Struct createStruct(String typeName, Object[] attributes)
            throws SQLException

The createStruct( String typeName, Object[] attributes ) method of the Connection object in the Polypheny JDBC Driver provides functionality to create a Struct object. The Struct object represents the SQL STRUCT data type, which is a composite type that encapsulates one or more ordered attributes, each of a specific SQL data type. This allows you to group related pieces of data together, much like the concept of structures in programming or tuples in relational databases.

SQL structures are beneficial in situations where data needs to be organized in a composite format for database operations, such as inserting structured data into a table or fetching structured results from stored procedures.

Parameters:

Parameter Name Type Description
typeName String The SQL name of the type that this Struct object should map to. This name is specific to the database.
attributes Object[] An array containing the ordered attribute values of the SQL STRUCT.

Return Value:

Return Type Description
Struct An object that mirrors the SQL STRUCT data type. This Struct object can then be used in SQL operations.

Usage:

try (
        Connection connection = DriverManager.getConnection( "jdbc:polypheny://localhost:20590" );
) {
    Object[] attributes = new Object[]{ "John Doe", 30 };
    Struct personStruct = connection.createStruct( "PERSON_TYPE", attributes );

    // Use the personStruct in SQL operations, e.g., to insert into a table column of type STRUCT...
} catch ( SQLException e ) {
    e.printStackTrace();
}

isWrapperFor

public boolean isWrapperFor(Class<?> iface)

The isWrapperFor( Class<?> iface ) method is a companion method to the unwrap( Class<T> iface ) method in the JDBC API. It allows the caller to determine if the current instance wraps an object of a particular interface type. This check is useful to ascertain if one can safely call the unwrap method to retrieve the underlying object implementing that interface.

For the Polypheny JDBC Driver, this method can be used to check if a particular Polypheny-specific interface or feature is available via the current instance.

Parameters:

Parameter Name Type Description
iface Class<?> The class or interface to check against.

This method throws an SQLException if there’s a database access error.

Return Value:

  • true: If the current instance wraps an object of the specified type or is an instance of it.
  • false: Otherwise.

Usage:

Checking if the connection object wraps a Polypheny-specific interface:

try (
        Connection connection = DriverManager.getConnection( "jdbc:polypheny://localhost:20590" );
) {
    if ( connection.isWrapperFor( PolyConnection.class ) ) {
        // The connection either wraps or directly implements MyPolyphenyInterface
    }
} catch ( SQLException e ) {
    e.printStackTrace();
}

unwrap

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

The unwrap( Class<T> iface ) method is a standard method provided in the JDBC API that allows the caller to retrieve an object of a specific interface type that may be wrapped by the current instance. The purpose is to allow applications to use extensions or features of the underlying database driver that are not part of the standard JDBC API.

For the Polypheny JDBC Driver, this method can be used to gain access to Polypheny-specific features or properties which are not covered by standard JDBC interfaces.

Method Signature:

Return Type Method Description
<T> unwrap( Class<T> iface ) throws SQLException Returns an object that implements the given interface to allow access to non-standard methods, or a proxy for that object.

Parameters:

Parameter Name Type Description
iface Class<T> The class or interface of the object to be returned.

This function throws a SQLException if the Connectiondoes not implemenet the given interface or if there’s a database access error.

Usage:

The usage of unwrap depends on the specific interfaces provided by the Polypheny JDBC Driver. As an illustrative example:

try (
        Connection connection = DriverManager.getConnection( "jdbc:polypheny://localhost:20590" );
) {
    if ( connection.isWrapperFor( PolyConnection.class ) ) {
        PolyConnection polyConnection = connection.unwrap( PolyConnection.class );
        // Use the polyphenyconnection to invoke Polypheny-specific methods...
    }
} catch ( SQLException e ) {
    e.printStackTrace();
}

getMetaData

public DatabaseMetaData getMetaData()
            throws SQLException

The getMetaData() method of the Connection object in the Polypheny JDBC Driver returns a DatabaseMetaData object. This object contains methods to retrieve information about the database’s metadata. Metadata encompasses details about data, such as the number and names of tables in the database, information about the columns in those tables, and so forth.

The DatabaseMetaData object provides a mechanism for applications to gather insights about the database’s capabilities, structure, supported SQL grammar, and other essential aspects. This is especially beneficial for tools that must adapt to various databases, generate SQL for diverse databases, or aim to display details concerning the database structure.

Returns:

  • DatabaseMetaData: An object equipped with methods to fetch information about the database’s metadata.

Usage:

You can utilize the getMetaData() method to retrieve and display specific metadata information. Here’s a sample:

try (
        Connection connection = DriverManager.getConnection( "jdbc:polypheny://localhost:20590" );
) {
    DatabaseMetaData metaData = connection.getMetaData();

    System.out.println( "Database Product Name: " + metaData.getDatabaseProductName() );
    System.out.println( "Database Product Version: " + metaData.getDatabaseProductVersion() );
    System.out.println( "Driver Name: " + metaData.getDriverName() );
    System.out.println( "SQL Keywords: " + metaData.getSQLKeywords() );
} catch ( SQLException e ) {
    e.printStackTrace();
}
© Polypheny GmbH. All Rights Reserved.