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)
setConnectionWaitTimeout()
ConnectionPoolDataSource.setConnectionWaitTimeout() sets the connection wait timeout interval to the specified number of seconds (also see getConnectionWaitTimeout()).
void setConnectionWaitTimeout(int timeout)
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)
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)
setDatabaseName()
IRISDataSource.setDatabaseName() sets the database name (InterSystems IRIS namespace) for this datasource. Also see getDatabaseName().
void setDatabaseName(String databaseName)
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)
setDefaultTransactionIsolation()
IRISDataSource.setDefaultTransactionIsolation() sets the default transaction isolation level. Also see getDefaultTransactionIsolation().
void setDefaultTransactionIsolation(int level)
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)
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)
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)
setLogFile()
IRISDataSource.setLogFile() unconditionally sets the log file name for this datasource.
void setLogFile(String logFile)
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)
setPassword()
IRISDataSource.setPassword() sets the password for this datasource. Also see getPassword().
void setPassword(String pwd)
setPortNumber()
IRISDataSource.setPortNumber() sets the port number for this datasource. Also see getPortNumber().
void setPortNumber(int portNumber)
setServerName()
IRISDataSource.setServerName() sets the server name for this datasource. Also see getServerName().
void setServerName(String serverName)
setServicePrincipalName()
IRISDataSource.setServicePrincipalName() sets the Service Principal Name for this datasource. Also see getServicePrincipalName().
void setServicePrincipalName(String name)
setSharedMemory()
IRISDataSource.setSharedMemory() sets shared memory connections for this datasource. Also see getSharedMemory().
void setSharedMemory(Boolean sharedMemory)
setSSLConfigurationName()
IRISDataSource.setSSLConfigurationName() sets the TLS Configuration Name for this datasource. Also see getSSLConfigurationName().
void setSSLConfigurationName(String name)
setURL()
IRISDataSource.setURL() sets the URL for this datasource. Also see getURL().
void setURL(String u)
setUser()
IRISDataSource.setUser() sets the username for this datasource. Also see getUser().
void setUser(String username)
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().
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().
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).
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]);
}
}