My Oracle Support Banner

New Jdbc Interfaces for Oracle types (Doc ID 1364193.1)

Last updated on NOVEMBER 08, 2021

Applies to:

JDBC - Version and later
Information in this document applies to any platform.
Replace types concrete classes with types interfaces.


Deprecation of concrete classes in the next major Oracle JDBC release. Applicable to the all the users who are using Oracle JDBC driver and above.

Background :-

Back in 1996 when Oracle implemented JDBC, the development team chose to create concrete classes instead of using interfaces for Oracle JDBC Types. The documentation recommended users to use these classes. This created the following problems

* Hard coding classes is not a standard way of programming. Types should be declared as interfaces, allowing implementations to evolve over time without breaking binary compatibility
* The classes exposed many of the internal methods
* Hard coding classes make it hard to change the implementation of the classes, defeating the purpose of Object Oriented programming
* Many of the new features are exposed through proxy pattern making almost impossible to implement
such features without breaking backward compatibility.

In Oracle database, new interfaces are created for each Oracle type that uses connection. Creating interfaces for all types (including the ones that do not use connection) is planned for the next major RDBMS release.

Concrete classes will now implement a public interface from the oracle.jdbc package and internal interfaces in oracle.jdbc.internal (the latter are not exposed to end users. Users should use methods exposed in java.sql whenever possible for standard compatibility and methods in oracle.jdbc for Oracle specific extensions.


User Benefits for using the new interfaces :-

The Oracle JDBC team puts a lot of effort in cleaning up the interfaces and making their usage efficient & streamlined with the rest of the Oracle JDBC APIs. Most of the changes are simple replacements and the resulting user code should be more compact and clean. The changes have very low risk in terms of regression. The modified code will easily pick up any future new features without little to no code changes.

What are the affected types?

In Oracle database version only types that have an embedded connection will be replaced by interfaces.

Old types New interfaces
oracle.sql.ARRAY oracle.jdbc.OracleArray
oracle.sql.STRUCT oracle.jdbc.OracleStruct
oracle.sql.CLOB oracle.jdbc.OracleClob
oracle.sql.BLOB oracle.jdbc.OracleBlob
oracle.sql.REF oracle.jdbc.OracleRef
oracle.sql.OPAQUE oracle.jdbc.OracleOpaque

oracle.sql.StructDescriptor, oracle.sql.ArrayDescriptor & oracle.sql.OpaqueDescriptor are removed since they do not serve any purpose that cannot be achieved via the new interfaces.

Changing user code to use new interfaces :-

Changing the code to use new interfaces is trivial, but should be handled with care. The following example applies to oracle.sql.ARRAY but similar changes apply to other types as well. A list of suggested changes are furnished below:

* Import: modify import statements to use the new interfaces (oracle.jdbc) instead of old interfaces (oracle.sql)
* Declaration: use standard Java interfaces for declaration whenever possible. If there is a need to use Oracle extension use the new Oracle interfaces under oracle.jdbc
* Methods: use standard Java interfaces whenever possible
o (Oracle Types): use methods in standard Java interfaces whenever possible. If required use methods from Oracle interfaces under oracle.jdbc
o (Defines): refrain from using Oracle specific methods such as getARRAY, instead use standard Java methods such as getArray or getObject for the ones that does not have standard Java interfaces
o (Binds): Refrain from using Oracle specific methods such as setARRAY, instead use standard Java methods such as setArray or setObject for the ones that does not have standard Java interfaces

Examples of change in usage :-

Import Statement

Replacing import statements is the easiest change it could be done by a simple script, which uses find

As it can be seen the new code is neater and more compact compared to the old one.


To view full details, sign in with your My Oracle Support account.

Don't have a My Oracle Support account? Click to get started!

In this Document

My Oracle Support provides customers with access to over a million knowledge articles and a vibrant support community of peers and Oracle experts.