By Steve Felts-Oracle on Aug 01, 2014
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.
- Web module (war)
- EJB module
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.