Skip to main content

JDBC Quick Reference

This chapter is a quick reference for the following extended classes and options:

Note:

This chapter lists only the extension methods and variants discussed in this book. See “JDBC Driver Support” in the Implementation Reference for Java Third Party APIs for a complete description of all InterSystems JDBC driver features, including extensions, variants, and implementation of optional JDBC features.

Class ConnectionPoolDataSource

The com.intersystems.jdbc.ConnectionPoolDataSource class fully implements the javax.sql.ConnectionPoolDataSource interface, and also includes the following set of extension methods to control InterSystems IRIS connection pooling. For more information, see “Using IRISConnectionPoolDataSource Methods”.

getConnectionWaitTimeout()

ConnectionPoolDataSource.getConnectionWaitTimeout() returns the number of seconds that a Connection Pool Manager will wait for any connections to become available (also see setConnectionWaitTimeout()). 

int getConnectionWaitTimeout()
getMaxPoolSize()

ConnectionPoolDataSource.getMaxPoolSize() returns an int representing the current maximum connection pool size (also see setMaxPoolSize()). 

int getMaxPoolSize()
getPoolCount()

ConnectionPoolDataSource.getPoolCount() returns an int representing the current number of entries in the connection pool. Throws SQLException. 

int getPoolCount()
getPooledConnection()

Always use IRISDataSource.getConnection() instead of this method.

Do not call this method

ConnectionPoolDataSource.getPooledConnection() is required by the interface, but should never be invoked directly. The InterSystems JDBC driver controls connection pooling transparently.

restartConnectionPool()

ConnectionPoolDataSource.restartConnectionPool() restarts a connection pool. Closes all physical connections, and empties the connection pool. Throws SQLException. 

void restartConnectionPool()
setMaxPoolSize()

ConnectionPoolDataSource.setMaxPoolSize() sets a maximum connection pool size. If the maximum size is not set, it defaults to 40 (also see getMaxPoolSize()). 

void setMaxPoolSize(int max)

  • max — optional maximum connection pool size (default 40).

setConnectionWaitTimeout()

ConnectionPoolDataSource.setConnectionWaitTimeout() sets the connection wait timeout interval to the specified number of seconds (also see getConnectionWaitTimeout()). 

void setConnectionWaitTimeout(int timeout)

  • timeout — timeout interval in seconds (defaults to 0).

If no connections are available after the timout period expires, an exception is thrown. Defaults to 0, indicating that the connection will either be immediately made available, or an exception will be thrown indicating that the pool is full.

Class IRISDataSource

The com.intersystems.jdbc.IRISDataSource class fully implements the javax.sql.DataSource interface, and also includes numerous extension methods for getting or setting InterSystems IRIS connection properties (see “Connection Parameter Options” for more information).

IRISDataSource does not inherit the methods of javax.sql.CommonDataSource, which is not supported by the InterSystems JDBC driver.

getConnection()
Required Method with Extended Functionality

Required method IRISDataSource.getConnection() returns a java.sql.Connection. Throws SQLException.

This method must always be used to obtain InterSystems IRIS driver connections. The InterSystems IRIS driver also provides pooling transparently through the java.sql.Connection object that getConnection() returns. 

java.sql.Connection getConnection()
java.sql.Connection getConnection(String usr,String pwd)

  • usr — optional username argument for this connection.

  • pwd — optional password argument for this connection.

This method provides pooling, and must always be used in place of getPooledConnection() and the methods of the PooledConnection class (see “Class ConnectionPoolDataSource” for more information).

getConnectionSecurityLevel()

IRISDataSource.getConnectionSecurityLevel() returns an int representing the current Connection Security Level setting. Also see setConnectionSecurityLevel().

int getConnectionSecurityLevel()
getDatabaseName()

IRISDataSource.getDatabaseName() returns a String representing the current database (InterSystems IRIS namespace) name. Also see setDatabaseName().

String getDatabaseName()
getDataSourceName()

IRISDataSource.getDataSourceName() returns a String representing the current data source name. Also see setDataSourceName().

String getDataSourceName()
getDefaultTransactionIsolation()

IRISDataSource.getDefaultTransactionIsolation() returns an int representing the current default transaction isolation level. Also see setDefaultTransactionIsolation().

int getDefaultTransactionIsolation()
getDescription()

IRISDataSource.getDescription() returns a String representing the current description. Also see setDescription().

String getDescription()

IRISDataSource.getEventClass() returns a String representing an Event Class object. Also see setEventClass().

String getEventClass()
getKeyRecoveryPassword()

IRISDataSource.getKeyRecoveryPassword() returns a String representing the current Key Recovery Password setting. Also see setKeyRecoveryPassword().

String getKeyRecoveryPassword()
getNodelay()

IRISDataSource.getNodelay() returns a Boolean representing a current TCP_NODELAY option setting. Also see setNodelay().

boolean getNodelay()
getPassword()

IRISDataSource.getPassword() returns a String representing the current password. Also see setPassword().

String getPassword()
getPortNumber()

IRISDataSource.getPortNumber() returns an int representing the current port number. Also see setPortNumber().

int getPortNumber()
getServerName()

IRISDataSource.getServerName() returns a String representing the current server name. Also see setServerName().

String getServerName()
getServicePrincipalName()

IRISDataSource.getServicePrincipalName() returns a String representing the current Service Principal Name setting. Also see setServicePrincipalName().

String getServicePrincipalName()
getSharedMemory()

IRISDataSource.getSharedMemory() returns a Boolean indicating whether the connection is using shared memory. Also see setSharedMemory().

Boolean getSharedMemory()
getSSLConfigurationName()

IRISDataSource.getSSLConfigurationName() returns a String representing the current TLS Configuration Name setting. Also see setSSLConfigurationName().

String getSSLConfigurationName()
getURL()

IRISDataSource.getURL() returns a String representing the current URL for this datasource. Also see setURL().

String getURL()
getUser()

IRISDataSource.getUser() returns a String representing the current username. Also see setUser().

String getUser()
setConnectionSecurityLevel()

IRISDataSource.setConnectionSecurityLevel() sets the connection security level for this datasource. Also see getConnectionSecurityLevel().

void setConnectionSecurityLevel(int level)

  • level — connection security level number.

setDatabaseName()

IRISDataSource.setDatabaseName() sets the database name (InterSystems IRIS namespace) for this datasource. Also see getDatabaseName().

void setDatabaseName(String databaseName)

  • databaseName — InterSystems IRIS namespace string.

setDataSourceName()

IRISDataSource.setDataSourceName() sets the data source name for this datasource. DataSourceName is an optional setting and is not used to connect. Also see getDataSourceName().

void setDataSourceName(String dataSourceName)

  • dataSourceName — data source name string.

setDefaultTransactionIsolation()

IRISDataSource.setDefaultTransactionIsolation() sets the default transaction isolation level. Also see getDefaultTransactionIsolation().

void setDefaultTransactionIsolation(int level)

  • level — default transaction isolation level number.

setDescription()

IRISDataSource.setDescription() sets the description for this datasource. Description is an optional setting and is not used to connect. Also see getDescription().

void setDescription(String desc)

  • desc — datasource description string.

setEventClass()

IRISDataSource.setEventClass() sets the Event Class for this datasource. The Event Class is a mechanism specific to InterSystems IRIS JDBC. It is completely optional, and the vast majority of applications will not need this feature. Also see getEventClass().

void setEventClass(String eventClassName)

  • eventClassName — name of transaction event class.

The InterSystems JDBC server will dispatch to methods implemented in a class when a transaction is about to be committed and when a transaction is about to be rolled back. The class in which these methods are implemented is referred to as the “event class.” If an event class is specified during login, then the JDBC server will dispatch to %OnTranCommit just prior to committing the current transaction and will dispatch to %OnTranRollback just prior to rolling back (aborting) the current transaction. User event classes should extend %ServerEvent. The methods do not return any values and cannot abort the current transaction.

setKeyRecoveryPassword()

IRISDataSource.setKeyRecoveryPassword() sets the Key Recovery Password for this datasource. Also see getKeyRecoveryPassword().

void setKeyRecoveryPassword(String password)

  • password — datasource Key Recovery Password string.

setLogFile()

IRISDataSource.setLogFile() unconditionally sets the log file name for this datasource. 

void setLogFile(String logFile)

  • logFile — datasource log file name string.

setNodelay()

IRISDataSource.setNodelay() sets the TCP_NODELAY option for this datasource. Toggling this flag can affect the performance of the application. If not set, it defaults to true. Also see getNodelay().

void setNodelay(boolean noDelay)

  • noDelay — optional datasource TCP_NODELAY setting (defaults to true).

setPassword()

IRISDataSource.setPassword() sets the password for this datasource. Also see getPassword().

void setPassword(String pwd)

  • pwd — datasource password string.

setPortNumber()

IRISDataSource.setPortNumber() sets the port number for this datasource. Also see getPortNumber().

void setPortNumber(int portNumber)

  • portNumber — datasource port number.

setServerName()

IRISDataSource.setServerName() sets the server name for this datasource. Also see getServerName().

void setServerName(String serverName)

  • serverName — datasource server name string.

setServicePrincipalName()

IRISDataSource.setServicePrincipalName() sets the Service Principal Name for this datasource. Also see getServicePrincipalName().

void setServicePrincipalName(String name)

  • name — datasource Service Principal Name string.

setSharedMemory()

IRISDataSource.setSharedMemory() sets shared memory connections for this datasource. Also see getSharedMemory().

void setSharedMemory(Boolean sharedMemory)

  • sharedMemory — on = 0, off = 1

setSSLConfigurationName()

IRISDataSource.setSSLConfigurationName() sets the TLS Configuration Name for this datasource. Also see getSSLConfigurationName().

void setSSLConfigurationName(String name)

  • name — TLS Configuration Name string.

setURL()

IRISDataSource.setURL() sets the URL for this datasource. Also see getURL().

void setURL(String u)

  • u — URL string.

setUser()

IRISDataSource.setUser() sets the username for this datasource. Also see getUser().

void setUser(String username)

  • username — username string.

Connection Parameter Options

This section lists and describes the connection properties provided by jdbc.IRISDataSource (the InterSystems implementation of javax.sql.DataSource). Connection properties can be set by passing them to DriverManager (as described in “Using DriverManager to Connect”) or calling connection property accessors (see “Class IRISDataSource” for a complete list).

The following connection properties are supported:

connection security level

Optional. Integer indicating Connection Security Level. Valid levels are 0, 1, 2, 3, or 10. Default = 0.

0 - Instance Authentication (Password)

1 - Kerberos (authentication only)

2 - Kerberos with Packet Integrity

3 - Kerberos with Encryption

10 - TLS

See IRISDataSource methods getConnectionSecurityLevel() and setConnectionSecurityLevel().

host

Optional. String specifying the SERVER IP address or host name.

Connection parameter host — IP address or Fully Qualified Domain Name (FQDN). For example, both 127.0.0.1 and localhost indicate the local machine.

See DataSource methods getServerName() and setServerName().

key recovery password

Optional. String containing current Key Recovery Password setting. Default = null. See IRISDataSource methods getKeyRecoveryPassword() and setKeyRecoveryPassword().

password

Required. String containing password. Default = null. See IRISDataSource methods getPassword() and setPassword()

port

Optional. Integer specifying the TCP/IP port number for the connection.

Connection parameter port— TCP port number on which the InterSystems IRIS SuperServer is listening. The default is 1972 (or the first available number higher than that if more than one instance of InterSystems IRIS is installed — see DefaultPort in the Parameter File Reference).

See DataSource methods getPortNumber() and setPortNumber().

service principal name

Optional. String indicating Service Principal Name. Default = null. See IRISDataSource methods getServicePrincipalName() and setServicePrincipalName()

SharedMemory

Optional. Boolean indicating whether or not to always use shared memory for localhost and 127.0.0.1. Default = null. See IRISDataSource methods getSharedMemory() and setSharedMemory(). Also see “Shared Memory Connections”.

SO_RCVBUF

Optional. Integer indicating TCP/IP SO_RCVBUF value (ReceiveBufferSize). Default = 0 (use system default value).

SO_SNDBUF

Optional. Integer indicating TCP/IP SO_SNDBUF value (SendBufferSize). Default = 0 (use system default value).

SSL configuration name

Optional. String containing current TLS Configuration Name for this object. Default = null. See IRISDataSource methods getSSLConfigurationName() and setSSLConfigurationName().

TCP_NODELAY

Optional. Boolean indicating TCP/IP TCP_NODELAY flag (Nodelay). Default = true.

Connection parameter nodelay — sets the TCP_NODELAY option if connecting via a IRISDataSource object. Toggling this flag can affect the performance of the application. Valid values are true and false. If not set, it defaults to true.

See IRISDataSource methods getNodelay() and setNodelay()

TransactionIsolationLevel

Optional. A java.sql.Connection constant indicating Transaction Isolation Level. Valid values are TRANSACTION_READ_UNCOMMITTED or TRANSACTION_READ_COMMITTED. Default = null (use system default value TRANSACTION_READ_UNCOMMITTED).

See IRISDataSource methods getDefaultTransactionIsolation() and setDefaultTransactionIsolation()

user

Required. String containing username. Default = null. See IRISDataSource methods getUser() and setUser()

Listing Connection Properties

Code similar to the following can be used to list the available properties for any compliant JDBC driver:

   java.sql.Driver drv = java.sql.DriverManager.getDriver(url);
   java.sql.Connection dbconnection = drv.connect(url, user, password);
   java.sql.DatabaseMetaData meta = dbconnection.getMetaData();
   System.out.println ("\n\n\nDriver Info: ==========================");
   System.out.println (meta.getDriverName());
   System.out.println ("release " + meta.getDriverVersion() + "\n");

   java.util.Properties props = new Properties();
   DriverPropertyInfo[] info = drv.getPropertyInfo(url,props);
   for(int i = 0; i <info.length; i++) {
      System.out.println ("\n" + info[i].name);
      if (info[i].required) {System.out.print("   Required");}
         else {System.out.print ("   Optional");}
      System.out.println (", default = " + info[i].value);
      if (info[i].description != null)
         System.out.println ("   Description:" + info[i].description);
      if (info[i].choices != null) {
         System.out.println ("   Valid values: ");
         for(int j = 0; j < info[i].choices.length; j++)
            System.out.println("      " + info[i].choices[j]);
      }
   }

Previous sectionJDBC for Occasional Users
FeedbackOpens in a new tab