Proactive insights, news and tips from Oracle WebLogic Server Support. Learn Oracle from Oracle.

Using Oracle JDBC Type Interfaces

Stephen Felts

One of the hot new features in Oracle database, first introduced in 12c, is Application Continuity (AC).  The feature basically will detect that a connection has gone bad and substitute a new one under the covers (I'll talk about it more in another article).  To be able to do that, the application is given a connection wrapper instead of the real connection.  Wrappers or dynamic proxies can only be generated for classes based on interfaces.  The Oracle types, like REF and ARRAY, were originally introduced as concrete classes.  There are new interfaces for the Oracle types that you will need to use to take advantage of this new AC feature (introduced in WLS 10.3.6 and/or the JDBC driver).

First, some history so that you understand the needed API changes.  In the early days of WebLogic data source, any references to vendor proprietary methods were handled by hard-coded references.  Keeping up with adding and removing methods was a significant maintenance problem. At the peak of the insanity, we had over one thousand lines of code that referenced Oracle-proprietary methods and the server could not run without an Oracle jar in the classpath (even for DB2-only shops).  In release 8.1 in March 2003, we introduced wrappers for all JDBC objects such that we dynamically generated proxies that implement all public interface methods of, and delegate to, the underlying vendor object.  The hard-coded references and the maintenance nightmare went away and just as importantly, we could provide debugging information, find leaked connections, automatically close objects when the containing object closed, replace connections that fail testing, etc.  The Oracle types were concrete classes so proxies were generated for these classes implementing the WLS vendor interfaces weblogic.jdbc.vendor.oracle.*.  Applications can cast to the WLS vendor interfaces or use getVendorObj to access the underlying driver object. Later, we added an option to unwrap data types, with a corresponding loss of functionality like no debug information.

Although the focus of this article is Oracle types, the dynamic proxies work for any vendor.   For example, you can cast a DB2 connection to use a proprietary method  ((com.ibm.db2.jcc.DB2Connection)conn).setDB2ClientUser("myname").

Starting with Oracle driver, the database team needed wrappers for the new AC feature and introduced new interfaces.  For WebLogic data source users, that's good news - no more unwrapping, the weblogic.jdbc.vendor package is no longer needed, and it's all transparent.  Before you go and change your programs to use the new Oracle proprietary interfaces, the recommended approach is to first see if you can just use standard JDBC API's.  In fact, as part of defining the new interfaces, Oracle proprietary methods were dropped if there was an equivalent standard JDBC API or the method was not considered to add significant value.  This table defines the mapping.  The goal is to get rid of references to the first and second columns and replace them with the third column.

" align="center">Old Oracle types Deprecated WLS Interface New interfaces
oracle.sql.ARRAY weblogic.jdbc.vendor.oracle.OracleArray oracle.jdbc.OracleArray
oracle.sql.STRUCT weblogic.jdbc.vendor.oracle.OracleStruct oracle.jdbc.OracleStruct
oracle.sql.CLOB weblogic.jdbc.vendor.oracle.OracleThinClob oracle.jdbc.OracleClob
oracle.sql.BLOB weblogic.jdbc.vendor.oracle.OracleThinBlob oracle.jdbc.OracleBlob
oracle.sql.REF weblogic.jdbc.vendor.oracle.OracleRef oracle.jdbc.OracleRef

This is a job for a shell hacker!  Much of it can be automated and the compiler can tell you if you are referencing a method that has gone away - then check if the missing method is in the equivalent jdbc.sql interface (e.g., getARRAY() becomes the JDBC standard getArray()).

You can take a look at a sample program that I wrote to demonstrate all of these new interfaces at  oracletypes.txt (note that this is actually a ".java" program so rename ".txt" to ".java"). It covers programming with all of these Oracle types.  While use of Blob and Clob might be popular, Ref and Struct might not be used as much.  The sample program shows how to create, insert, update, and access each type using both standard and extension methods.  Note that you need to use the Oracle proprietary createOracleArray() instead of the standard createArrayOf(). Although the sample program doesn't use the standard createBlob() or createClob(), these are supported for the Oracle driver.

The API's can be reviewed in the Javadoc at the oracle.jdbc API Reference .

This is a first step toward using Application Continuity.  But it's also a good move to remove Oracle API's that will eventually go away and use standard JDBC interfaces and new Oracle interfaces.



Join the discussion

Comments ( 4 )
  • guest Thursday, July 11, 2013

    Great blog post, good background / historic info and great new feature!

  • guest Thursday, June 25, 2015

    You really should do some SEO. I've been looking for days for a working example of the new API, without success, found yours only when I'd finished my code and was looking for the definition of OracleStruct. Still thanks, nice work.

  • Stephen Felts Monday, June 29, 2015

    The good news is that this information is now in the programming guide for WebLogic JDBC.


    You are correct that searching for it isn't easy.

  • Stephen Felts Friday, August 28, 2015

    There is also a good JDBC MOS with examples at


Please enter your name.Please provide a valid email address.Please enter a comment.CAPTCHA challenge response provided was incorrect. Please try again.