JDBC Driver Support
The InterSystems IRIS® JDBC Driver is a fully compliant type 4 implementation of the JDBC 4.2 standard. This chapter lists all classes and interfaces of the JDBC 4.2 API, indicates the level of support for each one, and describes all InterSystems-specific features. The following topics are discussed:
JDBC and the InterSystems JDBC Driver — provides an overview and resource links for the JDBC driver.
JDBC Driver Compliance — lists all classes and interfaces specified by the JDBC standard, and indicates the current level of support.
Variants and Unsupported Optional Methods — provides details on classes that include permitted variances from the standard.
InterSystems Enhancements and Extensions — lists and discusses InterSystems extensions to the standard JDBC API.
JDBC and the InterSystems JDBC Driver
The Java JDBC API is the industry standard for vendor-neutral database connectivity. It provides a reliable way for Java applications to connect to data sources on any supported platform and to query or perform operations on them with SQL.
InterSystems JDBC is implemented in a type 4 driver to deliver the highest possible performance. Type 4 means that it is a direct-to-database pure Java driver, installed inside the client JVM and requiring no external software support. It is fully compliant with the JDBC 4.2 API specification, supporting all required interfaces and adhering to all JDBC 4.2 guidelines and requirements. InterSystems IRIS supports all features except SQL Exception handling enhancements, National Character Set conversions, and the XML data type.
See Using Java with InterSystems Software for a full description of API features and usage. That book also provides an overview of all InterSystems IRIS Java technologies enabled by the JDBC driver (see “InterSystems Java Connectivity Options”).
Installation and Configuration
The InterSystems JDBC driver is included in the standard InterSystems IRIS installation package. No extra installation or setup procedures are required. See “Client-Server Configuration” in Using Java with InterSystems Software for information on client requirements and usage.
JDBC Driver Compliance
This section provides information on the level of support for each JDBC interface.
Required java.sql Interfaces
The following interfaces must be implemented. Some classes contain methods that are optional if the implementation depends on a feature that the database does not support. The standard implementation annotation indicates that the generic implementation of the class has been used without alteration:
java.sql.CallableStatement — implemented with some permitted variances (see “CallableStatement: Unsupported Methods” and “CallableStatement getBinaryStream() Extension Method”).
java.sql.ClientInfoStatus — standard implementation.
java.sql.Connection — implemented with some permitted variances (see Connection: Unsupported or Restricted Methods).
java.sql.DatabaseMetaData — implemented with some permitted variances (see “DatabaseMetaData: Variant Methods”).
java.sql.Date — standard implementation.
java.sql.Driver — implemented with some permitted variances (see “Driver: Unsupported Methods”).
java.sql.DriverManager — standard implementation.
java.sql.DriverPropertyInfo — standard implementation.
java.sql.ParameterMetaData — all methods fully supported.
java.sql.PreparedStatement — implemented with some permitted variances (see “PreparedStatement: Unsupported Methods”).
java.sql.ResultSet — implemented with some permitted variances (see “ResultSet: Unsupported or Restricted Methods”) .
java.sql.ResultSetMetaData — all methods fully supported.
java.sql.RowIdLifeTime — standard implementation.
java.sql.SQLPermission — standard implementation.
java.sql.Statement — implemented with some permitted variances (see “Statement: Unsupported or Restricted Methods”).
java.sql.Time — standard implementation.
java.sql.Timestamp — standard implementation.
java.sql.Types — standard implementation.
java.sql.Wrapper — all methods fully supported.
Optional java.sql Interfaces
All optional java.sql interfaces are listed below. Italicized items are not implemented:
java.sql.Array
java.sql.Blob — all methods fully supported.
java.sql.Clob — all methods fully supported.
java.sql.NClob — all methods fully supported.
java.sql.Ref
java.sql.RowId — all methods fully supported.
java.sql.Savepoint — all methods fully supported.
java.sql.SQLData
java.sql.SQLInput
java.sql.SQLOutput
java.sql.SQLXML
java.sql.Struct
java.sql Exceptions
The InterSystems JDBC driver throws only the following exceptions:
The following exceptions are listed here for completeness, but are not required and are never used:
DataTruncation
SQLClientInfoException
SQLDataException
SQLFeatureNotSupportedException
SQLIntegrityConstraintViolationException
SQLInvalidAuthorizationSpecException
SQLNonTransientConnectionException
SQLNonTransientException
SQLRecoverableException
SQLSyntaxErrorException
SQLTimeoutException
SQLTransactionRollbackException
SQLTransientConnectionException
SQLTransientException
Required javax.sql Interfaces
The following required interfaces are supported. The standard implementation annotation indicates that the generic implementation of the class has been used without alteration:
javax.sql.ConnectionEvent — standard implementation.
javax.sql.DataSource — implemented with enhancements and additional methods (see “DataSource Extensions and Enhancements” for details).
javax.sql.RowSetEvent — standard implementation.
javax.sql.StatementEvent — standard implementation.
Optional javax.sql Interfaces
All optional javax.sql interfaces are listed below. Italicized items are not implemented:
javax.sql.CommonDataSource — not implemented. Use javax.sql.DataSource instead (see “DataSource Extensions and Enhancements” for related information).
javax.sql.ConnectionEventListener — all methods fully supported.
javax.sql.ConnectionPoolDataSource — implemented with variants and additional methods (see “ConnectionPoolDataSource Extensions and Enhancements” for details).
javax.sql.PooledConnection — all methods fully supported.
javax.sql.Rowset
javax.sql.RowSetInternal
javax.sql.RowSetListener
javax.sql.RowSetMetaData
javax.sql.RowSetReader
javax.sql.RowSetWriter
javax.sql.StatementEventListener
javax.sql.XAConnection
javax.sql.XADataSource
Variants and Unsupported Optional Methods
The following interfaces have optional methods that the InterSystems JDBC driver does not support, or methods implemented in a non-standard manner:
CallableStatement: Unsupported Methods
java.sql.CallableStatement does not support the following optional methods:
getArray()
Array getArray(int i) Array getArray(String parameterName)
Copy code to clipboard
getObject()
Object getObject(int i, java.util.Map map) Object getObject(String parameterName, java.util.Map map)
Copy code to clipboardgetRef()
Ref getRef(int i) Ref getRef(String parameterName)
Copy code to clipboardgetRowId() and setRowId()
java.sql.RowId getRowId(int i) java.sql.RowId getRowId(String parameterName) void setRowId(String parameterName, java.sql.RowId x)
Copy code to clipboardgetURL() and setURL()
java.net.URL getURL(int i) java.net.URL getURL(String parameterName) void setURL(String parameterName, java.net.URL val)
Copy code to clipboardgetSQLXML() and setSQLXML()
java.sql.SQLXML getSQLXML(int parameterIndex) java.sql.SQLXML getSQLXML(String parameterName) void setSQLXML(String parameterName, java.sql.SQLXML xmlObject)
Copy code to clipboard
The java.sql.CallableStatement class also has one InterSystems extension method, which is discussed elsewhere (see “CallableStatement getBinaryStream() Extension Method”).
Connection: Unsupported or Restricted Methods
java.sql.Connection does not support the following optional methods:
abort()
void abort(Executor executor)
Copy code to clipboardcreateArrayOf()
java.sql.Array createArrayOf(String typeName, Object[] elements)
Copy code to clipboardcreateBlob()
Blob createBlob()
Copy code to clipboardcreateClob()
Clob createClob()
Copy code to clipboardcreateNClob()
java.sql.NClob createNClob()
Copy code to clipboardcreateSQLXML()
java.sql.SQLXML createSQLXML()
Copy code to clipboardcreateStruct()
java.sql.Struct createStruct(String typeName, Object[] attributes)
Copy code to clipboardgetTypeMap()
java.util.Map getTypeMap()
Copy code to clipboardsetTypeMap()
void setTypeMap(java.util.Map map)
Copy code to clipboard
The following optional java.sql.Connection methods are implemented with restrictions or limitations:
prepareCall()
Only TYPE_FORWARD_ONLY is supported for resultSetType. Only CONCUR_READ_ONLY is supported for resultSetConcurrency.
java.sql.CallableStatement prepareCall(String sql, int resultSetType, int resultSetConcurrency)
Copy code to clipboardsetReadOnly()
A no-op (the InterSystems IRIS driver does not support READ_ONLY mode)
void setReadOnly(Boolean readOnly)
Copy code to clipboardsetCatalog()
A no-op (the InterSystems IRIS driver does not support catalogs)
void setCatalog(String catalog)
Copy code to clipboardsetTransactionIsolation()
Only TRANSACTION_READ_COMMITED and TRANSACTION_READ_UNCOMMITED are supported for level.
void setTransactionIsolation(int level)
Copy code to clipboard
The following java.sql.Connection methods do not support CLOSE_CURSORS_AT_COMMIT for resultSetHoldability:
createStatement()
java.sql.Statement createStatement(int resultSetType, int result, int resultSetHoldability)
Copy code to clipboardprepareCall()
java.sql.CallableStatement prepareCall(String sql, int resultSetType, int resultSetConcurrency, int resultSetHoldability)
Copy code to clipboardprepareStatement()
java.sql.PreparedStatement prepareStatement(String sql, int resultSetType, int resultSetConcurrency, int resultSetHoldability)
Copy code to clipboard
InterSystems IRIS currently supports only zero or one Auto Generated Keys. An exception is thrown if the java.sql.Connection methods below provide columnIndexes or columnNames arrays whose lengths are not equal to one.
prepareStatement()
java.sql.PreparedStatement prepareStatement(String sql, int[] columnIndexes) java.sql.PreparedStatement prepareStatement(String sql, String[] columnNames)
Copy code to clipboard
DatabaseMetaData: Variant Methods
java.sql.DatabaseMetaData is fully supported, but has methods that vary from the JDBC standard due to InterSystems-specific handling of their return values. The following methods are affected:
supportsMixedCaseQuotedIdentifiers()
InterSystems IRIS returns false, which is not JDBC compliant.
boolean supportsMixedCaseQuotedIdentifiers()
Copy code to clipboardgetIdentifierQuoteString()
If delimited id support is turned on, InterSystems IRIS returns " (double quote character), which is what a JDBC compliant driver should return; otherwise InterSystems IRIS returns a space.
String getIdentifierQuoteString()
Copy code to clipboard
Driver: Unsupported Methods
java.sql.Driver does not support the following optional method:
getParentLogger()
void getParentLogger()
Copy code to clipboard
PreparedStatement: Unsupported Methods
java.sql.PreparedStatement does not support the following optional methods:
setArray()
void setArray(int i, Array x)
Copy code to clipboardsetRef()
void setRef(int i, Ref x)
Copy code to clipboardsetRowId()
void setRowId(int parameterIndex, RowId x)
Copy code to clipboardsetSQLXML()
void setSQLXML(int parameterIndex, SQLXML xmlObject)
Copy code to clipboardsetUnicodeStream()
Deprecated in Java JDK specification.
void setUnicodeStream(int i, InputStream x, int length)
Copy code to clipboardsetURL()
void setURL(int i, java.net.URL x)
Copy code to clipboard
ResultSet: Unsupported or Restricted Methods
InterSystems IRIS does not support TYPE_SCROLL_SENSITIVE result set types. The following method is implemented with restrictions:
setFetchDirection()
Does not support ResultSet.FETCH_REVERSE (instead, use afterLast to move the result set's cursor to after the last row, and use previous to scroll backwards).
void setFetchDirection(int direction)
Copy code to clipboard
java.sql.ResultSet does not support the following optional methods:
getArray()
Array getArray(int i) Array getArray(String colName)
Copy code to clipboardgetCursorName()
String getCursorName()
Copy code to clipboardgetObject()
Object getObject(int i, java.util.Map map) Object getObject(String colName, java.util.Map map)
Copy code to clipboardgetRef()
Ref getRef(int i) Ref getRef(String colName)
Copy code to clipboardgetHoldability()
int getHoldability()
Copy code to clipboardgetUnicodeStream()
Deprecated in Java JDK specification.
java.io.InputStream getUnicodeStream(int i) java.io.InputStream getUnicodeStream(String colName)
Copy code to clipboardgetURL()
java.net.URL getURL(int i) java.net.URL getURL(String colName)
Copy code to clipboardupdateArray()
void updateArray(int i, Array x) void updateArray(String colName, Array x)
Copy code to clipboardupdateRef()
void updateRef(int i, Ref x) void updateRef(String colName, Ref x)
Copy code to clipboard
Statement: Unsupported or Restricted Methods
java.sql.Statement does not support the following optional methods:
cancel()
void cancel()
Copy code to clipboardcloseOnCompletion()
void closeOnCompletion()
Copy code to clipboardisCloseOnCompletion()
boolean isCloseOnCompletion()
Copy code to clipboard
The following optional java.sql.Statement methods are implemented with restrictions or limitations:
getResultSetHoldability()
Only HOLD_CURSORS_OVER_COMMIT
int getResultSetHoldability()
Copy code to clipboardsetCursorName()
A no-op.
void setCursorName(String name)
Copy code to clipboardsetEscapeProcessing()
A no-op (does not apply)
void setEscapeProcessing(Boolean enable)
Copy code to clipboardsetFetchDirection()
Does not support ResultSet.FETCH_REVERSE (instead, use afterLast to move the result set's cursor to after the last row, and use previous to scroll backwards).
void setFetchDirection(int direction)
Copy code to clipboard
InterSystems IRIS currently supports only zero or one auto-generated key. An exception is thrown if the java.sql.Statement methods below provide columnIndexes or columnNames arrays whose lengths are not equal to one:
execute()
boolean execute(String sql, int[] columnIndexes) boolean execute(String sql, String[] columnNames)
Copy code to clipboardexecuteUpdate()
int executeUpdate(String sql, int[] columnIndexes) int executeUpdate(String sql, String[] columnNames)
Copy code to clipboard
InterSystems Enhancements and Extensions
The following classes provide additional InterSystems-specific extension methods:
ConnectionPoolDataSource Extensions and Enhancements discusses com.intersystems.jdbc.IRISConnectionPoolDataSource, which is the InterSystems implementation of the javax.sql.ConnectionPoolDataSource interface.
DataSource Extensions and Enhancements discusses com.intersystems.jdbc.IRISDataSource, which is the InterSystems implementation of javax.sql.DataSource.
CallableStatement getBinaryStream() Extension Method
java.sql.CallableStatement implements the following additional InterSystems-specific extension method:
getBinaryStream()
Retrieves the value of the designated parameter (where i is the index of the parameter) as a java.io.InputStream object.
java.io.InputStream getBinaryStream(int i)
Copy code to clipboardThis method is a complement to the standard setBinaryStream() method, and an alternative to getCharacterStream() (which returns java.io.Reader).
ConnectionPoolDataSource Extensions and Enhancements
The com.intersystems.jdbc.IRISConnectionPoolDataSource class fully implements the javax.sql.ConnectionPoolDataSource interface. This class does not inherit the methods of javax.sql.CommonDataSource, which is not supported by the InterSystems JDBC driver.
getPooledConnection() is implemented because it is required by the JDBC standard, but the InterSystems IRIS implementation should never be called directly. InterSystems IRIS driver connections must always be obtained by calling the getConnection() method. (See “Using a Connection Pool” in Using Java with InterSystems Software for more information).
getPooledConnection()
javax.sql.PooledConnection getPooledConnection() javax.sql.PooledConnection getPooledConnection(String usr,String pwd)
Copy code to clipboard
Calling applications should never use the getPooledConnection() methods or the PooledConnection class. InterSystems IRIS driver connections must always be obtained by calling the getConnection() method (which is inherited from IRISDataSource). The InterSystems IRIS driver provides pooling transparently through the java.sql.Connection object that it returns.
IRISConnectionPoolDataSource inherits from IRISDataSource (see “DataSource Extensions and Enhancements”), which provides additional InterSystems extension methods.
ConnectionPoolDataSource Extension Methods
IRISConnectionPoolDataSource also supports the following additional InterSystems IRIS-only management methods (see “Using a Connection Pool” in Using Java with InterSystems Software for more information):
restartConnectionPool()
Restarts a connection pool. Closes all physical connections, and empties the connection pool.
void restartConnectionPool()
Copy code to clipboardgetPoolCount()
Returns the current number of entries in the connection pool.
int getPoolCount()
Copy code to clipboardsetMaxPoolSize()
Sets a maximum connection pool size. If the maximum size is not set, it defaults to 40.
void setMaxPoolSize(int max)
Copy code to clipboardgetMaxPoolSize()
Returns the current maximum connection pool size
int getMaxPoolSize()
Copy code to clipboard
DataSource Extensions and Enhancements
The com.intersystems.jdbc.IRISDataSource class fully implements the javax.sql.DataSource interface. This class does not inherit the methods of javax.sql.CommonDataSource, which is not supported by the InterSystems JDBC driver.
The InterSystems IRIS implementation of this method is enhanced to provide automatic, transparent connection pooling. (See “Using a Connection Pool” in Using Java with InterSystems Software for more information).
getConnection()
java.sql.Connection getConnection() java.sql.Connection getConnection(String usr,String pwd)
Copy code to clipboard
DataSource Extension Methods
In addition to the methods defined by the interface, IRISDataSource also implements the following methods that can be used to get or set DataSource properties supported by InterSystems IRIS. (See “Setting Connection Properties” in Using Java with InterSystems Software for more information).
getConnectionSecurityLevel()
Returns an int representing the current Connection Security Level setting.
int getConnectionSecurityLevel()
Copy code to clipboardgetDatabaseName()
Returns a String representing the current database (InterSystems IRIS namespace) name.
String getDatabaseName()
Copy code to clipboardgetDataSourceName()
Returns a String representing the current data source name.
String getDataSourceName()
Copy code to clipboardgetDefaultTransactionIsolation()
Gets the current default transaction isolation.
int getDefaultTransactionIsolation()
Copy code to clipboardgetDescription()
Returns a String representing the current description.
String getDescription()
Copy code to clipboardgetEventClass()
Returns a String representing an Event Class object.
String getEventClass()
Copy code to clipboardgetKeyRecoveryPassword()
Returns a String representing the current Key Recovery Password setting.
getKeyRecoveryPassword()
Copy code to clipboardgetNodelay()
Returns a boolean representing a current TCP_NODELAY option setting.
boolean getNodelay()
Copy code to clipboardgetPassword()
Returns a String representing the current password.
String getPassword()
Copy code to clipboardgetPortNumber()
Returns an int representing the current port number.
int getPortNumber()
Copy code to clipboardgetServerName()
Returns a String representing the current server name.
String getServerName()
Copy code to clipboardgetServicePrincipalName()
Returns a String representing the current Service Principal Name setting.
String getServicePrincipalName()
Copy code to clipboardgetSSLConfigurationName()
Returns a String representing the current SSL Configuration Name setting.
getSSLConfigurationName()
Copy code to clipboardgetURL()
Returns a String representing a current URL for this connection.
String getURL()
Copy code to clipboardgetUser()
Returns a String representing the current username.
String getUser()
Copy code to clipboardsetConnectionSecurityLevel()
Sets the connection security level
Sets the Connection Security Level for this DataSource object.
Copy code to clipboardsetDatabaseName()
Sets the database name (InterSystems IRIS namespace) for this connection.
void setDatabaseName(String dn)
Copy code to clipboardsetDataSourceName()
Sets the data source name for this connection. DataSourceName is an optional setting and is not used by IRISDataSource to connect.
void setDataSourceName(String dsn)
Copy code to clipboardsetDefaultTransactionIsolation()
Sets the default transaction isolation level.
void setDefaultTransactionIsolation(int level)
Copy code to clipboardsetDescription()
Sets the description for this connection. Description is an optional setting and is not used by IRISDataSource to connect.
void setDescription(String d)
Copy code to clipboardsetEventClass()
Sets the Event Class for this connection. 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.
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.
void setEventClass(String e)
Copy code to clipboardsetKeyRecoveryPassword()
Sets the Key Recovery Password for this connection.
setKeyRecoveryPassword(java.lang.String password)
Copy code to clipboardsetLogFile()
Unconditionally sets the log file name for this connection.
setLogFile(java.lang.String logFile)
Copy code to clipboardsetNodelay()
Sets the TCP_NODELAY option for this connection. Toggling this flag can affect the performance of the application. If not set, it defaults to true.
void setNodelay(boolean nd)
Copy code to clipboardsetPassword()
Sets the password for this connection.
void setPassword(String p)
Copy code to clipboardsetPortNumber()
Sets the port number for this connection
void setPortNumber(int pn)
Copy code to clipboardsetServerName()
Sets the server name for this connection.
void setServerName(String sn)
Copy code to clipboardsetServicePrincipalName()
Sets the Service Principal Name for this connection.
void setServicePrincipalName(String name)
Copy code to clipboardsetSSLConfigurationName()
Sets the SSL Configuration Name for this connection.
setSSLConfigurationName(java.lang.String name)
Copy code to clipboardsetURL()
Sets the URL for this connection.
void setURL(String u)
Copy code to clipboardsetUser()
Sets the username for this connection.
void setUser(String u)
Copy code to clipboard