Skip to main content
Previous section

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 extension methods to control InterSystems IRIS connection pooling:

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()
Copy code to clipboard
getMaxPoolSize()

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

int getMaxPoolSize()
Copy code to clipboard
getPoolCount()

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

int getPoolCount()
Copy code to clipboard
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()
Copy code to clipboard
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)
Copy code to clipboard
  • max — optional maximum connection pool size (defaults to 40).

setConnectionWaitTimeout()

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

void setConnectionWaitTimeout(int timeout)
Copy code to clipboard
  • 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)
Copy code to clipboard
  • 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()
Copy code to clipboard
getDatabaseName()

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

String getDatabaseName()
Copy code to clipboard
getDataSourceName()

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

String getDataSourceName()
Copy code to clipboard
getDefaultTransactionIsolation()

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

int getDefaultTransactionIsolation()
Copy code to clipboard
getDescription()

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

String getDescription()
Copy code to clipboard
getEventClass()

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

String getEventClass()
Copy code to clipboard
getKeyRecoveryPassword()

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

String getKeyRecoveryPassword()
Copy code to clipboard
getNodelay()

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

boolean getNodelay()
Copy code to clipboard
getPassword()

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

String getPassword()
Copy code to clipboard
getPortNumber()

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

int getPortNumber()
Copy code to clipboard
getServerName()

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

String getServerName()
Copy code to clipboard
getServicePrincipalName()

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

String getServicePrincipalName()
Copy code to clipboard
getSharedMemory()

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

Boolean getSharedMemory()
Copy code to clipboard
getSSLConfigurationName()

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

String getSSLConfigurationName()
Copy code to clipboard
getURL()

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

String getURL()
Copy code to clipboard
getUser()

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

String getUser()
Copy code to clipboard
setConnectionSecurityLevel()

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

void setConnectionSecurityLevel(int level)
Copy code to clipboard
  • 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)
Copy code to clipboard
  • 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)
Copy code to clipboard
  • dataSourceName — data source name string.

setDefaultTransactionIsolation()

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

void setDefaultTransactionIsolation(int level)
Copy code to clipboard
  • 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)
Copy code to clipboard
  • 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)
Copy code to clipboard
  • 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) 
Copy code to clipboard
  • password — datasource Key Recovery Password string.

setLogFile()

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

void setLogFile(String logFile)
Copy code to clipboard
  • 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)
Copy code to clipboard
  • 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)
Copy code to clipboard
  • pwd — datasource password string.

setPortNumber()

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

void setPortNumber(int portNumber)
Copy code to clipboard
  • portNumber — datasource port number.

setServerName()

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

void setServerName(String serverName)
Copy code to clipboard
  • serverName — datasource server name string.

setServicePrincipalName()

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

void setServicePrincipalName(String name)
Copy code to clipboard
  • name — datasource Service Principal Name string.

setSharedMemory()

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

void setSharedMemory(Boolean sharedMemory)
Copy code to clipboard
  • sharedMemory — on = 0, off = 1

setSSLConfigurationName()

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

void setSSLConfigurationName(String name)
Copy code to clipboard
  • name — SSL Configuration Name string.

setURL()

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

void setURL(String u)
Copy code to clipboard
  • u — URL string.

setUser()

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

void setUser(String username)
Copy code to clipboard
  • 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” in the reference chapter 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 - SSL/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 SSL 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]);
      }
   }
Copy code to clipboard