Monday Mar 09, 2015

WLS JDBC Driver Patching

The handling of Oracle driver jar patches is complicated but getting sorted out. This article tries to gather the information in one place with pointers to more details.  There are a few patches that are still not available, marked as TBA (To Be Available) in the tables below.  As these files become available, this page will be updated.

WLS 10.3.6, 12.1.1, and 12.1.1 shipped Database 11.2.0.3 jar files.  However these are non-standard versions of the jars with additional bug fixes and enhancements to support WLS.  That means that you can't just drop in an 11.2.0.3 patch or upgrade to 11.2.0.4 using standard released jar files. Although support is required to provide 11.2.0.3 patches as needed, it will be difficult and the recommendation is to upgrade to a special 11.2.0.4 patch that contains 11.2.0.4 and all of the patches and enhancements in the 11.2.0.3 database jar files shipped with WLS. It's further complicated because WLS started using the Oracle Universal Installer in 12.1.2, requiring a different patch format.

WLS 10.3.6, 12.1.1, 12.1.2, and 12.1.3 also support running with Oracle Database 12c client jar files. For WLS 10.3.6 through 12.1.2, the jar files must be manually installed; there is no installer or patch to automate this upgrade. To get patches, you must be running with the Database 12.1.0.2 jar files; WLS patches will not be generated for the Database 12.1.0.1 jar files. WLS 12.1.3 ships with a pre-release version of Database 12.1.0.2 driver jar files and a patch will be available to upgrade to the production version of these files. After this upgrade, standard database Oracle patch files will work as expected for WLS 12.1.3 (and WLS 12.1.2 with a manual upgrade to database 12.1.0.2 jar files).

Patching the installed Oracle Driver

WLS Release

Oracle Driver Install

Database Jar

Patch Strategy

Documentation

10.3.6

11.2.0.3.0AS11.1.1.6.0

11.2.0.4 WLS patch

https://support.oracle.com/epmos/faces/DocumentDisplay?id=1970437.1

12.1.1

11.2.0.3.0AS11.1.1.6.0

11.2.0.4 WLS patch

https://support.oracle.com/epmos/faces/DocumentDisplay?id=1970437.1

12.1.2

11.2.0.3.0AS12.1.2.0.0

11.2.0.4 opatch

Patch Request 18557114 for bug 19477203

12.1.3

Pre-12.1.0.2

12.1.0.2 opatch to bring up to shipping 12.1.0.2; standard opatch for additional bug fixes

TBA soon


























Running with the Database 12c Driver

WLS Release

12.1.0.2 installation

Database Jar Patch Strategy

Documentation for Installation
Documentation for patching

10.3.6

Manual installation of 12.1.0.2

12.1.0.2 WLS patch

https://support.oracle.com/epmos/faces/DocumentDisplay?id=1564509.1
TBA

12.1.1

Manual installation of 12.1.0.2

12.1.0.2 WLS patch

https://support.oracle.com/epmos/faces/DocumentDisplay?id=1564509.1
TBA

12.1.2

Manual installation of 12.1.0.2

12.1.0.2 opatch

https://docs.oracle.com/middleware/1212/wls/JDBCA/ds_12cdriver.htm#JDBCA272

Standard patch procedure

12.1.3

Pre-12.1.0.2 installed; Patch to bring up to shipping 12.1.0.2

12.1.0.2 opatch

https://docs.oracle.com/middleware/1213/wls/JDBCA/ds_12cdriver.htm#JDBCA272

TBA soon for make-up patch

Standard patch procedure

On a related topic, updating non-Oracle driver jar files is covered by the following note.

https://support.oracle.com/epmos/faces/DocumentDisplay?id=1

This includes the DataDirect and MySQL drivers that are shipped in the kit. The jar file is backed up and removed, the new file installed, and the CLASSPATH adjusted if the jar name changes.

You'll notice that releases earlier than WLS 10.3.6 are not discussed.  For releases earlier than WLS 10.3.4, they depend only on the ojdbcN.jar file.  It's possible that they will work with the 11.2.0.4 jar file but that hasn't been certified and they are not still in error correction support.  For WLS 10.3.4 or 10.3.5, it depends not only on a specific ojdbc jar file but also ONS/UCP jars that have the package names renamed.  They will likely not work correctly with the 11.2.0.4 jar file (certainly not Active GridLink).  Since these releases ended error correction support in May 2012, you will need to upgrade to WLS 10.3.6 or 12.1.x to use later driver jar files.

Friday Aug 01, 2014

Using 3rd party JDBC Jar Files

If you look at the documentation for adding a 3rd party JDBC jar file, it recommends adding it to the system classpath by updating comEnv.sh.  See http://docs.oracle.com/middleware/1212/wls/JDBCA/third_party_drivers.htm#JDBCA233.  However, there more options with some advantages and disadvantages.  To use some of these options, you need to know something about application archive files.

The general precedence of jar files in the classpath is the following:

system classpath >> DOMAIN_HOME/lib >> APP-INF/lib >> WEB-INF/lib

The highest priority is given to jar files on the system classpath.  The advantage of using the system classpath is that it works for all environment including standalone applications. 

The rest of the options only work for applications deployed in the application server.  That includes the WLS administration console and WLST but not an application like 'java utils.Schema'.  These approaches work on WLS 10.3.6 and later.

The simplest way to add a jar file when you don't need it accessed in a standalone application is to drop it in DOMAIN_HOME/lib.  This is an easy way to access a driver for a data source in the application server. It won't work for jar files that are shipped with WLS and already part of the system classpath because the system classpath takes precedence.  That's why this article focuses on "3rd party" jar files.  More information and recommendations about using DOMAIN_HOME/lib can be found at http://docs.oracle.com/middleware/1212/wls/WLPRG/classloading.htm#i1096881 .

APP-INF/lib will only work in an EAR file and applies to all applications in the EAR file.  APP-INF is located at the root directory in the EAR file at the same level as META-INF.  This approach and the next have the advantage of packaging the driver with the application archive.  However, it's not efficient if the driver is needed by more than one archive and you probably should use DOMAIN_HOME/lib.

WEB-INF/lib only works in a WAR file and must be located at the root directory in the WAR file.  It only applies to the corresponding web application.  By using a WEB-INF/weblogic.xml file that has "<prefer-web-inf-classes>true</prefer-web-inf-classes>", the jar files in WEB-INF/lib take precedence over others (that is, the default precedence defined above is overridden).  This is useful if you want different versions of the driver for different applications in various WAR files.   Note that starting in WLS 12.1.1 with Java EE 6 support, it's possible to have a standalone WAR file that is not embedded in an EAR file.

Here's an indented list that attempts to capture the hierarchy of the files and directories described above in EAR and WAR files.

Application (ear)

  • Web module (war)
    • WEB-INF/lib
    • WEB-INF/web.xml
    • WEB-INF/weblogic.xml
  • EJB module
  • META-INF
  • APP-INF/lib

There is sample code for a WAR file at this link.  The data source definition can appear either as a descriptor in web.xml or as an annotation in the java file.  weblogic.xml can be used to set prefer-web-inf-classes appropriately.  The @Resource annotation is used to reference the data source in the application code.  This program prints the version of the driver.  You can play with two versions of the Derby driver to see how the precedence works.

Note:  You can't have two versions of the same jar in both domain/lib or the system classpath and  WEB-INF/lib or APP-INF/lib with prefer-web-inf-classes or prefer-application-packages set.  That is, either you use domain/lib or system classpath to get it into all applications in the domain or you use it embedded in the application but not both.  If you don't follow this restriction, it's possible (depending on the jar, the version changes, and the order in which the jars are referenced) that a ClassCastException will occur in the application.

The choice of where you locate the JDBC jar file depends on your application.  For standalone application access, use the system classpath.  For simple access in all or most applications, use DOMAIN_HOME/lib.  For access across an EAR file, use APP-INF/lib.  For access within a single WAR file, use WEB-INF/lib.



Thursday Jul 11, 2013

Using Oracle JDBC Type Interfaces

One of the hot new features in Oracle database 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.   In WLS 10.3.6 and/or the JDBC 11.2.0.3 driver, there are new interfaces for the Oracle types that you will need to use to take advantage of this new AC feature.

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 11.2.0.3, 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   https://blogs.oracle.com/WebLogicServer/resource/StephenFeltsFiles/OracleTypes.txt (note that this is actually a ".java" program). 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 starting with the 11.2.0.3 version of the Javadoc.  A copy is available at http://download.oracle.com/otn_hosted_doc/jdeveloper/905/jdbc-javadoc/oracle/jdbc/package-summary.html .

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.



About

The official blog for Oracle WebLogic Server fans and followers!

Stay Connected

Search

Archives
« March 2015
SunMonTueWedThuFriSat
1
2
3
4
5
7
8
10
11
12
13
14
15
17
18
19
20
21
22
23
25
26
27
28
29
30
31
    
       
Today