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.

Available ResuSetTypes:

Available Concurrency Modes:

Available Holdability Modes:

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

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.

Available ResultSetTypes:

Available Concurrency Modes:

Available Holdability Modes:

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

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();
}

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 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:

Returns:

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

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

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:

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

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.

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

Return Value (for getAutoCommit):

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:

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:

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:

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:

Overloads:

There are two main overloads for the getClientInfo method:

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:

setCatalog

public void setCatalog(String catalog)
            throws SQLException

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:

setHoldability and getHoldability

public void setHoldability(int holdability)
            throws SQLException

public int getHoldability()
            throws 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:

Return Value:

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

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:

getSchema

public String getSchema()
            throws SQLException

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:

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.

Parameters:

Return Value:

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

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:

Return Value:

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:

Return Value:

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

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:

Return Value:

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:

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:

Parameters:

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();
}

Previous

Driver

Next

Overview