JDBC Driver - Driver

The Polypheny JDBC Driver is a bridge between applications and Polypheny databases, enabling seamless data access and manipulation. Built upon the Java Database Connectivity (JDBC) API, this driver facilitates integration with Polypheny’s distinctive capabilities while adhering to standard JDBC workflows, ensuring both reliability and performance for transactional and analytical tasks alike.

Creating a Connection

A connection to a Polypheny instance can be established using the getConnection method.

getConnection

public Connection getConnection(String url)
            throws SQLException
public Connection getConnection(String url, Properties info)
            throws SQLException
public Connection getConnection(String url, String user, String password)
            throws SQLException

Parameters:

Parameter Description Overload Availability
url The connection URL for the Polypheny database. All
info A list of arbitrary string tag/value pairs in a Properties object. Second (getConnection(String, Properties))
user The username for authentication. Third (getConnection(String, String, String))
password The password associated with the given username. Third (getConnection(String, String, String))

Usage:

Using the Simple URL String

try ( Connection conn = DriverManager.getConnection( "jdbc:polypheny://localhost:20590" ) ) {
    // Your database operations...
} catch ( SQLException e ) {
    e.printStackTrace();
}

Using a Properties Object for Additional Settings

Properties props = new Properties();
props.put( "user", "pa" );
props.put( "password", "pa" );
// ... add other properties as needed

try ( Connection conn = DriverManager.getConnection( "jdbc:polypheny://localhost:20590", props ) ) {
    // Your database operations...
} catch ( SQLException e ) {
    e.printStackTrace();
}

Using Separate String Parameters for Username and Password

try ( Connection conn = DriverManager.getConnection( "jdbc:polypheny://localhost:20590", "pa", "pa" ) ) {
    // Your database operations...
} catch ( SQLException e ) {
    e.printStackTrace();
}

URL Structure

The JDBC URL for connecting to Polypheny has a specific structure that allows for various configurations. The generic structure is as follows:

jdbc:polypheny://[username:password]@host[:port][/namespace][?property1=value1&...&propertyN=valueN]

Each section in the URL represents:

username:password
Optional authentication credentials.
host
The address of the Polypheny server.
port
The port number on which the Polypheny server is running.
namespace
Optional database namespace.
property=value
Optional properties that configure the connection.

Default values:

  • If no host is specified, localhost is used as the default.
  • If no port is specified, 20591 is used as the default.

Examples:

  • Basic Connection: A connection to the default Polypheny instance (using default port).
    jdbc:polypheny://localhost
    
  • With Authentication: A connection with specified username and password (“pa” for both).
    jdbc:polypheny://pa:pa@localhost
    
  • With Port: Specifying the port in the connection. In this example, we use the default port 20591.
    jdbc:polypheny://localhost:20591
    
  • With Namespace: A connection specifying a particular namespace to use as default for all executed statements. Here we specify the default namespace called “pulic”. Please refer to the corresponding documentation for further information on namespaces.
    jdbc:polypheny://localhost/public
    
  • With Properties: A connection with additional properties like autocommit and nwtimeout.
    jdbc:polypheny://localhost?autocommit=false&nwtimeout=2500
    
  • Combination: A combined example with username, password, port, namespace, and properties.
    jdbc:polypheny://pa:pa@localhost:20591/myNamespace?autocommit=true&nwtimeout=3000
    

Connection Properties Details

The table below provides a comprehensive overview of the connection properties available for a Polypheny JDBC connection:

Property Type Values/Description Example Notes
user String Specifies the username for authentication. user=pa  
password String Specifies the password associated with the given username. password=pa  
autocommit Boolean Determines if each SQL statement is treated as a transaction. autocommit=true Values: true or false
readonly Boolean Indicates if the connection is in read-only mode. readonly=true Values: true or false. Currently ignored, reserved for future use.
holdability String Specifies the holdability of ResultSet objects. holdability=HOLD Values: HOLD or CLOSE (Currently ignored)
isolation String Indicates the transaction isolation level. isolation=SERIALIZABLE Values: COMMITTED, DIRTY, SERIALIZABLE, REPEATABLE_READ (Currently ignored)
nwtimeout Integer Specifies the network timeout in seconds. Corresponds to the JDBC network timeout. nwtimeout=30 Values: true or false
strict Boolean Specifies if the driver should strictly adhere to the jdbc standard (see callout below). strict=true  
Be aware that older versions of the Polypheny JDBC Driver (prior to the 2.0 release) exhibited behavior that was not fully compliant with the JDBC standard. In developing the new driver, the focus has been on strict adherence to the standard. However, to maintain compatibility with applications crafted for older versions of the driver, the strict property can be set to false.
Please note that schemas are called namespaces in Polypheny. Please refer to the corresponding documentation for further information.

Closing a Connection

It’s essential to close connections when they are no longer needed to prevent resource leaks and to ensure optimal application and database performance. This can be achieved automatically using one of the methods below.

  • Using Try-With-Resources: Leveraging the try-with-resources statement, connections close automatically after the block executes.
    try ( Connection conn = DriverManager.getConnection( "jdbc:polypheny://localhost:20590" ) ) {
      // Use the connection
    } catch ( SQLException e ) {
      e.printStackTrace();
    }
    
  • Explicit Close: For those not using the try-with-resources feature, manually close the connection within a finally block.
    Connection conn = null;
    try {
      conn = DriverManager.getConnection( "jdbc:polypheny://localhost:20590" );
      // Use the connection
    } catch ( SQLException e ) {
      e.printStackTrace();
    } finally {
      if ( conn != null ) {
          try {
              conn.close();
          } catch ( SQLException e ) {
              e.printStackTrace();
          }
      }
    }
    

More methods

acceptsURL

public boolean acceptsURL(String url)
            throws SQLException

The PolyphenyDriver is Polypheny’s implementation of the JDBC Driver interface, designed to facilitate Java applications in connecting and interacting with the Polypheny database system. This implementation ensures seamless integration with Java’s standard JDBC API while harnessing the specific features and capabilities of the Polypheny system. This document will guide you through the intricacies of using the PolyphenyDriver to establish and manage your database connections.

The method acceptsURL( String url ) of the PolyphenyDriver can be used to check if the Polypheny JDBC Driver understands and can potentially connect to the given URL. This method can be particularly useful if your application has to manage connections to multiple types of databases or needs to verify the validity of a connection string before attempting a connection.

The acceptsURL method returns a boolean. It will return true if the driver understands the provided URL, otherwise false.

The method does not establish an actual connection to the database. It simply checks if the URL structure is something the driver can understand.
If the driver recognizes the URL but realizes it is malformed, it still returns true.

Usage:

Driver polyphenyDriver = new org.polypheny.jdbc.PolyphenyDriver();
boolean isSupported = polyphenyDriver.acceptsURL( "jdbc:polypheny://localhost:20591" );

if ( isSupported ) {
    // Proceed with the connection or other logic
} else {
    System.out.println( "Provided URL is supported by the Polypheny JDBC driver." );
}

getMajorVersion

public int getMajorVersion()

The method getMajorVersion() of the PolyphenyDriveris designed to help applications retrieve the major version number of the Polypheny JDBC driver, enabling them to manage compatibility and features accordingly.

Usage:

To obtain the major version of the Polypheny JDBC Driver, simply invoke the getMajorVersion() method on an instance of the driver:

Driver polyphenyDriver = new org.polypheny.jdbc.PolyphenyDriver();
int majorVersion = polyphenyDriver.getMajorVersion();

System.out.println( "Polypheny JDBC Driver Major Version: " + majorVersion );

getMinorVersion

public int getMinorVersion()

The getMinorVersion() method of the PolyphenyDriver provides applications with the ability to retrieve the minor version number of the Polypheny JDBC driver.

Usage:

To acquire the minor version of the Polypheny JDBC Driver, invoke the getMinorVersion() method on a driver instance:

Driver polyphenyDriver = new org.polypheny.jdbc.PolyphenyDriver();
int minorVersion = polyphenyDriver.getMinorVersion();

System.out.println( "Polypheny JDBC Driver Minor Version: " + minorVersion );

getParentLogger

public Logger getParentLogger()
            throws SQLFeatureNotSupportedException

The getParentLogger() method of the PolyphenyDriver is a part of the JDBC specification, designed to retrieve the parent Logger object for a Driver. It helps in getting an understanding of the logging activities of the underlying driver.

However, for the Polypheny JDBC Driver, logging functionality has not been implemented. As a result, invoking the getParentLogger() method will always result in a SQLFeatureNotSupportedException being thrown, indicating that this feature is not currently supported by the driver.

Usage & Expectation:

While developers can technically invoke the getParentLogger() method on a driver instance, they should anticipate a SQLFeatureNotSupportedException as mentioned above:

Driver polyphenyDriver = new org.polypheny.jdbc.PolyphenyDriver();
try {
    Logger parentLogger = polyphenyDriver.getParentLogger();
    // This block will not be reached
} catch ( SQLFeatureNotSupportedException e ) {
    System.out.println( "Logging is not implemented in the Polypheny JDBC Driver." );
}

getPropertyInfo

public DriverPropertyInfo[] getPropertyInfo(String url, Properties info)
            throws SQLException

The method getPropertyInfo of the PolyphenyDriver retrieves an array of DriverPropertyInfo objects, providing details about the properties supported and required by the Polypheny JDBC driver. The DriverPropertyInfo objects returned as well as their values is based on the properties already specified and/or set in the url or the Property object passed to this method. This method offers applications such as GUI tools insights into the possible properties they can request form a user, especially when establishing a connection.

DriverPropertyInfo Attributes:

Attribute Type Description
name String Name of the property
value String Current value of the property
required Boolean Indicates if the property is mandatory
description String A brief description of the property
choices String[] Array of possible choices (only for properties with a limited set of possible values)

Supported Properties:

Property Description Choices Required
user Specifies the username for authentication. If not specified, the database uses the default user. - No
password Specifies the password. If not specified, the database assumes no password. - No
autocommit Determines if each SQL statement is treated as a transaction. true, false No
readonly Indicates if the connection is in read-only mode. Currently ignored. true, false No
holdability Specifies the holdability of ResultSet objects. HOLD, CLOSE No
isolation Indicates the transaction isolation level. COMMITTED, DIRTY, SERIALIZABLE, REPEATABLE_READ No
nwtimeout Specifies the network timeout in seconds. Corresponds to the JDBC network timeout. - No

Usage:

To retrieve properties associated with a given URL and a set of Properties, use the method as follows:

Driver polyphenyDriver = new org.polypheny.jdbc.PolyphenyDriver();
Properties props = new Properties();
// Set any desired properties
DriverPropertyInfo[] infos = polyphenyDriver.getPropertyInfo( "jdbc:polypheny://localhost:20590", props );

// Loop through infos to get details about each property
for ( DriverPropertyInfo info : infos ) {
    System.out.println( info.name + ": " + info.description );
}

jdbcCompliant

public boolean jdbcCompliant()

The jdbcCompliant() method of the PolyphenyDriver allows applications to determine if the Polypheny JDBC Driver adheres to the JDBC specification. For the Polypheny JDBC Driver, this method will always return true, indicating that it is fully JDBC compliant.

This compliance assures that the Polypheny JDBC Driver meets the standard requirements set out in the JDBC specification, providing reliable and consistent behavior for applications that rely on said standard.

Usage:

To check the JDBC compliance of the Polypheny JDBC Driver, invoke the jdbcCompliant() method on a driver instance:

Driver polyphenyDriver = new org.polypheny.jdbc.PolyphenyDriver();

if ( polyphenyDriver.jdbcCompliant() ) {
    System.out.println( "The Polypheny JDBC Driver is JDBC compliant." );
} else {
    // This block will never be executed for the Polypheny JDBC Driver
    System.out.println( "The Polypheny JDBC Driver is not JDBC compliant." );
}
© Polypheny GmbH. All Rights Reserved.