docs.intersystems.com
Home  /  Application Development: Language and Database Interoperability  /  InterSystems Implementation Reference for Java Third Party APIs  /  JDBC Driver Support


InterSystems Implementation Reference for Java Third Party APIs
JDBC Driver Support
[Back]  [Next] 
InterSystems: The power behind what matters   
Search:  


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
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 JDBC with InterSystems IRIS 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 JDBC with InterSystems IRIS 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:
Optional java.sql Interfaces
All optional java.sql interfaces are listed below. Italicized items are not implemented:
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:
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:
Optional javax.sql Interfaces
All optional javax.sql interfaces are listed below. Italicized items are not implemented:
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
Unsupported Optional Methods
java.sql.CallableStatement does not support the following optional methods:
Note:
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
Unsupported Optional Methods
java.sql.Connection does not support the following optional methods:
Optional Methods with Restrictions
The following optional java.sql.Connection methods are implemented with restrictions or limitations:
The following java.sql.Connection methods do not support CLOSE_CURSORS_AT_COMMIT for resultSetHoldability:
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.
DatabaseMetaData: Variant Methods
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:
Driver: Unsupported Methods
Unsupported Optional Method
java.sql.Driver does not support the following optional method:
PreparedStatement: Unsupported Methods
Unsupported Optional Methods
java.sql.PreparedStatement does not support the following optional methods:
ResultSet: Unsupported or Restricted Methods
Optional Method with Restrictions
InterSystems IRIS does not support TYPE_SCROLL_SENSITIVE result set types. The following method is implemented with restrictions:
Unsupported Optional Methods
java.sql.ResultSet does not support the following optional methods:
Statement: Unsupported or Restricted Methods
Unsupported Optional Methods
java.sql.Statement does not support the following optional methods:
Optional Methods with Restrictions
The following optional java.sql.Statement methods are implemented with restrictions or limitations:
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:
InterSystems Enhancements and Extensions
The following classes provide additional InterSystems-specific extension methods:
CallableStatement getBinaryStream() Extension Method
java.sql.CallableStatement implements the following additional InterSystems-specific extension method:
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.
Restricted Method
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 JDBC with InterSystems IRIS for more information).
Caution:
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 JDBC with InterSystems IRIS for more information):
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.
Enhanced Required Method
The InterSystems IRIS implementation of this method is enhanced to provide automatic, transparent connection pooling. (See Using a Connection Pool in Using Java JDBC with InterSystems IRIS for more information).
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 JDBC with InterSystems IRIS for more information).