Compliance in JAVA-JDBC

This chapter identifies the features that a JDBC API implementation is required to support for each level of compliance. A JDBC API implementation includes a JDBC
technology-enabled driver and its underlying data source. Therefore, compliance is defined in terms of what features are available above the driver layer. Any features not identified here are optional. In general, a driver is not required to implement any feature that its underlying data source does not support.

Definitions

To avoid ambiguity, we will use these terms in our discussion of compliance:

• JDBC API implementation — a JDBC technology-enabled driver and its underlying data source. The driver may provide support for features that are not implemented by the underlying data source. It may also provide the mapping between standard syntax/semantics and the native API implemented by the data source.

• Relevant specifications — this document, the API specification, and the relevant SQL specification. This is also the order of precedence if a feature is described in more than one of these documents. For the JDBC 1.0 API, the relevant SQL specification is SQL92 and X/Open SQL CLI. For the JDBC 2.0 and 3.0 APIs, it is SQL92 plus the relevant sections of SQL99 and X/Open SQL CLI.
• Supported feature — a feature for which the JDBC API implementation supports standard syntax and semantics for that feature as defined in the relevant specifications.
• Extension — a feature that is not covered by any of the relevant specifications or a non-standard implementation of a feature that is covered.
  
• Fully implemented — a term applied to an interface that has all of its methods implemented to support the semantics defined in the relevant specifications.

• Required interface — an interface that must be included although it might not be fully implemented. Methods that are not implemented should throw an SQLException to indicate that the corresponding feature is not supported.

Guidelines and Requirements
The following guidelines apply to all levels of compliance:

• A JDBC API implementation must support Entry Level SQL92 plus the SQL command Drop Table (see note.)

Entry Level SQL92 represents a "floor" for the level of SQL that a JDBC API
implementation must support. Access to features based on SQL99 should be
provided in a way that is compatible with the relevant part of the SQL99
specification.

• Drivers must support escape syntax. Escape syntax is described in “Statements”.
• Drivers must support transactions. See Chapter 10 “Transactions” for details.
• Drivers should provide access to every feature implemented by the underlying data source, including features that extend the JDBC API. When a feature is not supported, the corresponding methods throw an SQLException. The intent is for applications using the JDBC API to have access to the same feature set as native applications.
• If a DatabaseMetaData method indicates that a given feature is supported, it must be supported via standard syntax and semantics as described in the relevant specifications. This may require the driver to provide the mapping to the data source’s native API or SQL dialect if it differs from the standard.
• If a feature is supported, all of the relevant metadata methods must be implemented. For example, if a JDBC API implementation supports the RowSet interface, it must also implement the RowSetMetaData interface.
• If a feature is not supported, the corresponding DatabaseMetaData method must say so. Attempting to access the unsupported feature causes an SQLException to be thrown.
  

Note – A JDBC API implementation is required to support the DROP TABLE
command as specified by SQL92, Transitional Level. However, support for the
CASCADE and RESTRICT options of DROP TABLE is optional. In addition, the
behaviour of DROP TABLE is implementation-defined when there are views or
integrity constraints defined that reference the table being dropped.

JDBC 1.0 API Compliance

A driver that is compliant with the JDBC 1.0 API must do the following:

• Adhere to the preceding guidelines and requirements
• Fully implement the following interfaces:
• java.sql.Driver
• java.sql.DatabaseMetaData (excepting those methods introduced in the JDBC 2.0 API and the JDBC 3.0 API)
• java.sql.ResultSetMetaData (excepting those methods introduced in the JDBC 2.0 API and the JDBC 3.0 API)
• Include the following required interfaces:
• java.sql.CallableStatement
• java.sql.Connection
• java.sql PreparedStatement
• java.sql.ResultSet
• java.sql.Statement

JDBC 2.0 API Compliance

A driver that is compliant with the JDBC 2.0 API must do the following:

• Comply with the JDBC 1.0 API requirements
• Implement the following additional DatabaseMetaData methods:
• deletesAreDetected
• getConnection
• getUDTs
• insertsAreDetetced
• othersDeletesAreVisible
• othersInsertsAreVisible
• othersUpdatesAreVisible
• ownDeletesAreVisible
• ownInsertsAreVisible
• ownUpdatesAreVisible
• supportsBatchUpdates
• supportsResultSetConcurrency
• supportsResultSetType
• updatesAreDetected
• Implement the following additional ResultSetMetaData methods:
• getColumnClassName
• getColumnType
• getColumnTypeName

JDBC 3.0 API Compliance

A driver that is compliant with the JDBC 3.0 API must do the following:

• Comply with the JDBC 2.0 API requirements
• Include the following required interfaces:
• java.sql.ParameterMetaData
• java.sql.Savepoint
• It must implement the following additional DatabaseMetaData methods:
• supportsSavepoints
• supportsNamedParameters
• supportsMultipleOpenResults
• supportsGetGeneratedKeys
• getSuperTypes
• getSuperTables
• getAttributes
• getResultSetHoldability
• supportsResultSetHoldability
• getSQLStateType
• getDatabaseMajorVersion
• getDatabaseMinorVersion
• getJDBCMajorVersion
• getJDBCMinorVersion

Determining Compliance Level

The JDBC API is a constituent technology of the Java platform. Compliance with the
JDBC API specification is determined as a subset of evaluating compliance with the
overall platform.
Note – As of this writing, there is no separate evaluation of compliance level for the JDBC API.

Deprecated APIs

Deprecation refers to a class, interface, constructor, method or field that is no longer recommended and may cease to exist in a future version. The following constructors and methods were deprecated in the JDBC 2.0 API:

java.sql.CallableStatement.getBigDecimal(int, int)
java.sql.Date(int, int, int)
java.sql.Date.getHours()
java.sql.Date.getMinutes()
java.sql.Date.getSeconds()
java.sql.Date.setHours(int)
java.sql.Date.setMinutes(int)
java.sql.Date.setSeconds(int)
java.sql.DriverManager.getLogStream()
java.sql.DriverManager.setLogStream(PrintStream)
java.sql.PreparedStatement.setUnicodeStream(int, InputStream,int)
java.sql.ResultSet.getBigDecimal(int, int)
java.sql.ResultSet.getBigDecimal(String, int)
java.sql.ResultSet.getUnicodeStream(int)
java.sql.ResultSet.getUnicodeStream(String)
java.sql.Time(int, int, int)
java.sql.Time.getDate()
java.sql.Time.getDay()
java.sql.Time.getMonth()
java.sql.Time.getYear()
java.sql.Time.setDate(int)
java.sql.Time.setMonth(int)
java.sql.Time.setYear(int)
java.sql.Timestamp(int, int, int, int, int, int, int)