15 Using JDBC Drivers with WebLogic Server

WebLogic Server uses JDBC drivers to provide access to various databases. WebLogic Server comes with a default set of JDBC drivers but third-party JDBC drivers can also be used.

• JDBC Driver Support
  WebLogic Server provides support for application data access to any database using a JDBC-compliant driver.
• JDBC Drivers Installed with WebLogic Server
  The Oracle JDBC Thin driver 19.3 is installed with Oracle WebLogic Server 14.1.1.0.0. In addition to the Oracle Thin Driver, the mySQL Connector/J 8.0 (mysql-connector-java-commercial-8.0.14-bin.jar) JDBC driver, WebLogic-branded DataDirect drivers are also installed with WebLogic Server.
• Adding Third-Party JDBC Drivers Not Installed with WebLogic Server
  To use third-party JDBC drivers that are not installed with WebLogic Server, you can add them to the DOMAIN_HOME/lib directory.
• Globalization Support for the Oracle Thin Driver
  For globalization support with the Oracle Thin driver, Oracle supplies the orai18n.jar file.
• Using the Oracle Thin Driver in Debug Mode
  The ORACLE_HOME\oracle_common\modules\oracle.jdbc folder includes the ojdbc8_g.jar (for JDK8), which is the version of the Oracle Thin driver with classes to support debugging and tracing. To use the Oracle Thin driver in debug mode, add the path to these files at the beginning of your CLASSPATH.

JDBC Driver Support

WebLogic Server provides support for application data access to any database using a JDBC-compliant driver.

The JDBC-compliant driver needs to meet the following requirements:

• The driver must be thread-safe.

• The driver must implement standard JDBC transactional calls, such as setAutoCommit() and setTransactionIsolation(), when used in transactional aware environments.

• If the driver that does not implement serializable or remote interfaces, it cannot pass objects to an RMI client application.

When WebLogic Server features use a database for internal data storage, database support is more restrictive than for application data access. The following WebLogic Server features require internal data storage:

• Container Managed Persistence (CMP)

• Rowsets

• JMS/JDBC Persistence and use of a WebLogic JDBC Store

• JDBC Session Persistence

• RDBMS Security Providers

• Database Leasing (for singleton services and server migration)

• JTA Logging Last Resource (LLR) optimization.

JDBC Drivers Installed with WebLogic Server

The Oracle JDBC Thin driver 19.3 is installed with Oracle WebLogic Server 14.1.1.0.0. In addition to the Oracle Thin Driver, the mySQL Connector/J 8.0 (mysql-connector-java-commercial-8.0.14-bin.jar) JDBC driver, WebLogic-branded DataDirect drivers are also installed with WebLogic Server.

The drivers files are named ojdbc8.jar, ojdbc8_g.jar, and ojdbc8dms.jar for JDK8 and JDK11.

Note:

See Using WebLogic-branded DataDirect Drivers in Developing JDBC Applications for Oracle WebLogic Server.

These drivers are installed in subdirectories of $ORACLE_HOME/oracle_common/modules. The manifest in the weblogic.jar lists this file so that it is loaded when weblogic.jar is loaded (when the server starts). Therefore, you do not need to add this JDBC driver to your CLASSPATH. If you plan to use a third-party JDBC driver that is not installed with WebLogic Server, you must install the drivers, which includes updating your CLASSPATH with the path to the driver files, and may include updating your PATH with the path to database client files. See Supported Configurations in What's New in Oracle WebLogic Server .

Note:

WebLogic Server includes a version of the Derby DBMS installed with the WebLogic Server examples in the WL_HOME\common\derby directory. Derby is an all-Java DBMS product included in the WebLogic Server distribution solely in support of demonstrating the WebLogic Server examples. For more information about Derby, see http://db.apache.org/derby.

Adding Third-Party JDBC Drivers Not Installed with WebLogic Server

To use third-party JDBC drivers that are not installed with WebLogic Server, you can add them to the DOMAIN_HOME/lib directory.Here, DOMAIN_HOME represents the directory in which the WebLogic Server domain is configured. The default path is ORACLE_HOME/user_projects/domains.

For more information, see Adding JARs to the Domain /lib Directory in Developing Applications for Oracle WebLogic Server.

Note:

In previous releases, adding a new JDBC driver or updating a JDBC driver where the replacement JAR has a different name than the original JAR required updating the WebLogic Server's classpath to include the location of the JDBC driver classes. This is no longer required.

Using a Third-Party JAR File in DOMAIN_HOME/lib

Using a third-party JAR file in DOMAIN_HOME/lib is only supported for third-party JDBC drivers that are not installed with WebLogic Server. The drivers installed with WebLogic Server are described in JDBC Drivers Installed with WebLogic Server.

When you use a third-party JAR file in the DOMAIN_HOME/lib directory, note the following:

• The classloader that gets created is a child of the system classpath classloader in WebLogic Server.

• Any classes that are in JARs in this directory are visible only to Java EE applications in the server, such as EAR files.

• You can use the WebLogic Server Administration Console and WLST online to configure and manage the JAR files. (You may also be able to use WLST offline because the data source is not deployed.)

• These JAR files do not work when run from a standalone client (such as the t3 RMI client) or standalone applications (such as java utils.Schema).

• If there are multiple domain directories involved (that is, multiple machines without a shared file system), the JAR file must be installed in /lib in each domain directory.

• WebLogic Server use of methods called on third-party drivers (such as TimesTen abort and DB2 setDB2ClientUser) is supported.

Note:

For details on WebLogic Server functionality supported with these JAR files, see Database Interoperability in What's New in Oracle WebLogic Server, and the appropriate version of the Oracle Fusion Middleware Supported System Configurations matrix documentation for specific database driver and DB version certification information.

Data Source Support

Third-party JAR files installed in /lib can be used with the following:

• All data source types supported by WebLogic Server system resources including Generic, Multi Data Source, and Active GridLink. The Universal Connection Pool data source does not apply since the UCP JAR is not third-party.

• Packaged data sources in an EAR or a WAR.

• Java EE 6 data source definition defined in an EAR or WAR.

Although not JDBC methods, using a third-party JAR file in /lib does apply to WebLogic Server data source callbacks like Multi Data Source failover, connection, replay, and harvesting.

Example 15-1 Example of Using a Third-Party JAR File in /lib

The following example shows the files contained in a standalone WAR file named getversion.war. The Derby JAR files are located in WEB-INF/lib or DOMAIN_HOME/lib (or both). The class file is compiled and installed at WEB-INF/classes/demo/GetVersion.class.

<web-app>
  <welcome-file-list>
    <welcome-file>welcome.jsp</welcome-file>
  </welcome-file-list>
  <display-name>GetVersion</display-name>
  <servlet>
    <description></description>
    <display-name>GetVersion</display-name>
    <servlet-name>GetVersion</servlet-name>
    <servlet-class>
       demo.GetVersion
    </servlet-class>
  </servlet>
<!-- Data source description can go in the web.xml descriptor or as an annotation in the java code - see below
  <data-source>
    <name>java:global/DSD</name>
    <class-name>org.apache.derby.jdbc.ClientDataSource</class-name>
    <port-number>1527</port-number>
    <server-name>localhost</server-name>
    <database-name>examples</database-name>
    <transactional>false</transactional>
  </data-source>
-->
</web-app>
 
WEB-INF/weblogic.xml
 
<weblogic-web-app>
  <container-descriptor>
    <prefer-web-inf-classes>true</prefer-web-inf-classes>
  </container-descriptor>
</weblogic-web-app>
 
Java file
 
package demo;
 
import java.io.IOException;
import java.io.PrintWriter;
import java.sql.Connection;
import java.sql.SQLException;
import javax.annotation.Resource;
import javax.annotation.sql.DataSourceDefinition;
import javax.servlet.ServletException;
import javax.servlet.annotation.WebServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import javax.sql.DataSource;
 
@DataSourceDefinition(name="java:global/DSD",
className="org.apache.derby.jdbc.ClientDataSource",
portNumber=1527,
serverName="localhost",
databaseName="examples",
transactional=false
)
@WebServlet(urlPatterns = "/GetVersion")
public class GetVersion extends javax.servlet.http.HttpServlet
  implements javax.servlet.Servlet {
  @Resource(lookup = "java:global/DSD")
  private DataSource ds;
 
  public GetVersion() {
    super();
  }
 
  protected void doGet(HttpServletRequest request,
    HttpServletResponse response) throws ServletException, IOException {
    doPost(request, response);
  }
 
  protected void doPost(HttpServletRequest request,
    HttpServletResponse response) throws ServletException, IOException {
    response.setContentType("text/html");
 
    PrintWriter writer = response.getWriter();
    writer.println("<html>");
    writer.println("<head><title>GetVersion</title></head>");
    writer.println("<body>" + doit() +"</body>");
    writer.println("</html>");
    writer.close();
  }
 
  private String doit() {
    String ret = "FAILED";
    Connection conn = null;
    try {
      conn = ds.getConnection();
      ret = "Connection obtained with version= " +
        conn.getMetaData().getDriverVersion();
    } catch(Exception e) {
      e.printStackTrace();
    } finally {
      try {
        if (conn != null)
          conn.close();
      } catch (Exception ignore) {}
    }
    return ret;
  }
}

Globalization Support for the Oracle Thin Driver

For globalization support with the Oracle Thin driver, Oracle supplies the orai18n.jar file.This file replaces nls_charset.zip.

If you use character sets other than US7ASCII, WE8DEC, WE8ISO8859P1 and UTF8 with CHAR and NCHAR data in Oracle object types and collections, you must include orai18n.jar and orai18n-mapping.jar in your CLASSPATH.

The orai18n.jar and orai18n-mapping.jar are included with the WebLogic Server installation in the ORACLE_HOME\oracle_common\modules\oracle.nlsrtl_12.1.0 folder. These files are not referenced by the weblogic.jar manifest file, so you must add them to your CLASSPATH before they can be used.

Using the Oracle Thin Driver in Debug Mode

The ORACLE_HOME\oracle_common\modules\oracle.jdbc folder includes the ojdbc8_g.jar (for JDK8), which is the version of the Oracle Thin driver with classes to support debugging and tracing. To use the Oracle Thin driver in debug mode, add the path to these files at the beginning of your CLASSPATH.