JDBC Quick Reference
This chapter is a quick reference for the following extended classes and options:
-
Class ConnectionPoolDataSource — methods related to InterSystems connection pooling.
-
Class IRISDataSource — InterSystems-specific connection properties.
-
Connection Parameter Options — lists connection parameters that can be used in properties files.
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”.
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()
ConnectionPoolDataSource.getMaxPoolSize() returns an int representing the current maximum connection pool size (also see setMaxPoolSize()).
int getMaxPoolSize()
ConnectionPoolDataSource.getPoolCount() returns an int representing the current number of entries in the connection pool. Throws SQLException.
int getPoolCount()
Always use IRISDataSource.getConnection() instead of this method.
ConnectionPoolDataSource.getPooledConnection() is required by the interface, but should never be invoked directly. The InterSystems JDBC driver controls connection pooling transparently.
ConnectionPoolDataSource.restartConnectionPool() restarts a connection pool. Closes all physical connections, and empties the connection pool. Throws SQLException.
void restartConnectionPool()
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).
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.
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).
IRISDataSource.getConnectionSecurityLevel() returns an int representing the current Connection Security Level setting. Also see setConnectionSecurityLevel().
int getConnectionSecurityLevel()
IRISDataSource.getDatabaseName() returns a String representing the current database (InterSystems IRIS namespace) name. Also see setDatabaseName().
String getDatabaseName()
IRISDataSource.getDataSourceName() returns a String representing the current data source name. Also see setDataSourceName().
String getDataSourceName()
IRISDataSource.getDefaultTransactionIsolation() returns an int representing the current default transaction isolation level. Also see setDefaultTransactionIsolation().
int getDefaultTransactionIsolation()
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()
IRISDataSource.getKeyRecoveryPassword() returns a String representing the current Key Recovery Password setting. Also see setKeyRecoveryPassword().
String getKeyRecoveryPassword()
IRISDataSource.getNodelay() returns a Boolean representing a current TCP_NODELAY option setting. Also see setNodelay().
boolean getNodelay()
IRISDataSource.getPassword() returns a String representing the current password. Also see setPassword().
String getPassword()
IRISDataSource.getPortNumber() returns an int representing the current port number. Also see setPortNumber().
int getPortNumber()
IRISDataSource.getServerName() returns a String representing the current server name. Also see setServerName().
String getServerName()
IRISDataSource.getServicePrincipalName() returns a String representing the current Service Principal Name setting. Also see setServicePrincipalName().
String getServicePrincipalName()
IRISDataSource.getSSLConfigurationName() returns a String representing the current TLS Configuration Name setting. Also see setSSLConfigurationName().
String getSSLConfigurationName()
IRISDataSource.getURL() returns a String representing the current URL for this datasource. Also see setURL().
String getURL()
IRISDataSource.getUser() returns a String representing the current username. Also see setUser().
String getUser()
IRISDataSource.setConnectionSecurityLevel() sets the connection security level for this datasource. Also see getConnectionSecurityLevel().
void setConnectionSecurityLevel(int level)
-
level — connection security level number.
IRISDataSource.setDatabaseName() sets the database name (InterSystems IRIS namespace) for this datasource. Also see getDatabaseName().
void setDatabaseName(String databaseName)
-
databaseName — InterSystems IRIS namespace string.
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.
IRISDataSource.setDefaultTransactionIsolation() sets the default transaction isolation level. Also see getDefaultTransactionIsolation().
void setDefaultTransactionIsolation(int level)
-
level — default transaction isolation level number.
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.
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.
IRISDataSource.setKeyRecoveryPassword() sets the Key Recovery Password for this datasource. Also see getKeyRecoveryPassword().
void setKeyRecoveryPassword(String password)
-
password — datasource Key Recovery Password string.
IRISDataSource.setLogFile() unconditionally sets the log file name for this datasource.
void setLogFile(String logFile)
-
logFile — datasource log file name string.
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).
IRISDataSource.setPassword() sets the password for this datasource. Also see getPassword().
void setPassword(String pwd)
-
pwd — datasource password string.
IRISDataSource.setPortNumber() sets the port number for this datasource. Also see getPortNumber().
void setPortNumber(int portNumber)
-
portNumber — datasource port number.
IRISDataSource.setServerName() sets the server name for this datasource. Also see getServerName().
void setServerName(String serverName)
-
serverName — datasource server name string.
IRISDataSource.setServicePrincipalName() sets the Service Principal Name for this datasource. Also see getServicePrincipalName().
void setServicePrincipalName(String name)
-
name — datasource Service Principal Name string.
IRISDataSource.setSSLConfigurationName() sets the TLS Configuration Name for this datasource. Also see getSSLConfigurationName().
void setSSLConfigurationName(String name)
-
name — TLS Configuration Name string.
IRISDataSource.setURL() sets the URL for this datasource. Also see getURL().
void setURL(String u)
-
u — URL string.
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:
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().
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().
Optional. String containing current Key Recovery Password setting. Default = null. See IRISDataSource methods getKeyRecoveryPassword() and setKeyRecoveryPassword().
Required. String containing password. Default = null. See IRISDataSource methods getPassword() and setPassword()
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().
Optional. String indicating Service Principal Name. Default = null. See IRISDataSource methods getServicePrincipalName() and setServicePrincipalName()
Optional. Integer indicating TCP/IP SO_RCVBUF value (ReceiveBufferSize). Default = 0 (use system default value).
Optional. Integer indicating TCP/IP SO_SNDBUF value (SendBufferSize). Default = 0 (use system default value).
Optional. String containing current TLS Configuration Name for this object. Default = null. See IRISDataSource methods getSSLConfigurationName() and setSSLConfigurationName().
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()
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()
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]);
}
}
