Skip Headers
Oracle® Fusion Middleware Configuring and Managing JDBC Data Sources for Oracle WebLogic Server
12c Release 1 (12.1.1)

Part Number E24367-06
Go to Documentation Home
Home
Go to Table of Contents
Contents
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

B WebLogic Server 12.1.1 Support for Oracle 12c Database

This chapter provides information on how to configure WebLogic Server Release 12.1.1 to run with an Oracle 12c database.

Using an Oracle 12c Database with WebLogic Server 12.1.1

The following sections provide information on how to prepare and use an Oracle 12c database with WebLogic Server 12.1.1:

Using 11g Drivers with Oracle 12c Database

The simplest integration of WebLogic Server 12.1.1 with a 12c database is to use the 11g (specifically 11.2.0.3) driver jar files included in your WebLogic Server 12.1.1 distribution. There are no known problems or upgrade issues when using 11g drivers with a 12c database. Please note the following:

  • The Pluggable Database (PDB) feature can be used without any new client jar files or WebLogic Server changes. However, the ALTER SESSION SET CONTAINER feature to dynamically change containers from the client cannot be used.

  • Application Continuity is not supported.

  • Database resident connection pool (DRCP) and ONS auto configuration are not supported.

  • Global database service (GDS) can be used with an Active GridLink data source.

  • JDBC 4.1 methods are not supported.

Using 12c Drivers with Oracle 12c Database

The following sections provides information on how to prepare and use 12c drivers to run with WebLogic Server 12.1.1 and an Oracle 12c database:

Required Oracle 12c Driver Files

This section lists the files required to use an Oracle 12c driver with WebLogic Server 12.1.1. These files are installed under the 12c database $ORACLE_HOME directory. It is necessary to install either the Client package or the Database package.

Note:

These jar files must be added to the CLASSPATH used for running WebLogic Server at the head of the CLASSPATH. They must come before all of the 11g client jar files.

Select one of the following ojdbc files :

  • jdbc/lib/ojdbc7.jar

  • jdbc/lib/ojdbc7_g.jar

  • jdbc/lib/ojdbc7dms.jar

  • jdbc/lib/ojdbc6.jar

  • jdbc/lib/ojdbc6_g.jar

  • jdbc/lib/ojdbc6dms.jar

The following table lists additional required driver files:

Table B-1 Additional 12c Driver Files

File Description

ucp/lib/ucp.jar

Universal Connection Pool

opmn/lib/ons.jar

Oracle Network Server client

jlib/orai18n.jar

I18N support

jlib/orai18n-mapping.jar

I18N support

jlib/oraclepki.jar

Oracle Wallet support

jlib/osdt_cert.jar

Oracle Wallet support

jlib/osdt_core.jar

Oracle Wallet support


The following table lists additional files for SQL XML support:

Table B-2 Additional Files for SQL XML Support

File Description

rdbms/jlib/xdb.jarucp/lib/ucp.jar

SQLXML support

lib/xmlparserv2_sans_jaxp_services.jar

SQLXML support

jlib/orai18n-collation.jar

SQLXML support


Download Oracle 12c Database Files

The 12c Oracle database jar files are not shipped with this version of WebLogic Server. Oracle recommends that you do a custom install of the client kit for a minimal installation. See http://www.oracle.com/technetwork/database/enterprise-edition/downloads/index.html.

Under Oracle Database 12c Release 1, select the See All link for your OS platform. For a minimal install, under the Oracle Database 12c Release 1 Client heading, select the proper zip file and download it. Unzip the file and run the installer. Select Custom, then select the Oracle JDBC/Thin interfaces, Oracle Net listener, and Oracle Advanced security check boxes.

Update the WebLogic Server CLASSPATH

To use an Oracle 12c database and Oracle 12c JDBC driver, you must update the CLASSPATH in your WebLogic Server environment. Prepend the required files specified in Required Oracle 12c Driver Files to the CLASSPATH (before the 11.2.0.3 Driver jar files).

The following code sample outlines a simple shell script that updates the CLASSPATH of your WebLogic environment. Make sure ORACLE_HOME is set appropriately. This example assumes the SEP variable is set to the correct CLASSPATH separator (";" or ":") for your platform.

#!/bin/sh
 
# source this file in to add the new 12c jar files at the beginning of the
# CLASSPATH
 
case "`uname`" in   
*CYGWIN*)           
SEP=";"           
;;   
Windows_NT)           
SEP=";"           
;;   
*)           
SEP=":"           
;;
esac
# For external, just use ORACLE_HOME;
dir=${ORACLE_HOME:?}
 
# We need one of the following
#jdbc/lib/ojdbc7.jar
#jdbc/lib/ojdbc7_g.jar
#jdbc/lib/ojdbc7dms.jar
#jdbc/lib/ojdbc6.jar
#jdbc/lib/ojdbc6_g.jar
#jdbc/lib/ojdbc6dms.jar
if [ "$1" = "" ]
then 
ojdbc=ojdbc7.jar
else 
ojdbc="$1"
fi
case "$ojdbc" in
ojdbc7.jar|ojdbc7_g.jar|ojdbc7dms.jar|ojdbc6.jar|ojdbc6_g.jar|ojdbc6dms.jar)  
ojdbc=jdbc/lib/$ojdbc 
;;
*) 
echo "Invalid argument - must be ojdbc7.jar|ojdbc7_g.jar|ojdbc7dms.jar|ojdbc6.jar|ojdbc6_g.jar|ojdbc6dms.jar"  
exit 1 
;;
esac
CLASSPATH="${dir}/${ojdbc}${SEP}$CLASSPATH"
CLASSPATH="${dir}/ucp/lib/ucp.jar${SEP}$CLASSPATH"
CLASSPATH="${dir}/opmn/lib/ons.jar${SEP}$CLASSPATH"
CLASSPATH="${dir}/jlib/orai18n.jar${SEP}$CLASSPATH"
CLASSPATH="${dir}/jlib/orai18n-mapping.jar${SEP}$CLASSPATH"
CLASSPATH="${dir}/jlib/oraclepki.jar ${SEP}$CLASSPATH"
CLASSPATH="${dir}/jlib/osdt_cert.jar ${SEP}$CLASSPATH"
CLASSPATH="${dir}/jlib/osdt_core.jar${SEP}$CLASSPATH"
# SQL XML support
CLASSPATH="${dir}/lib/xmlparserv2_sans_jaxp_services.jar${SEP}$CLASSPATH"
CLASSPATH="${dir}/jlib/orai18n-collation.jar${SEP}$CLASSPATH"
CLASSPATH="${dir}/rdbms/jlib/xdb.jar${SEP}$CLASSPATH"

For example, save this script in your environment with the name setdb12c_jars.sh. Then run run script with the ojdbc6dms.jar:

.  ./setdb12c_jars.sh ojdbc6dms.jar

Other Considerations

This section provides additional information when using WebLogic Server 12.1.1 with an Oracle 12c database:

  • WebLogic Server 12.1.1 does not support using the aqapi.jar file from the 12c database distribution and doess not support using AQ JMS with the 12c database.

  • WebLogic Server 12.1.1 supports Application continuity when using both the 12c client jar files and 12c database with an Active GridLink data source. See Using Application Continuity.

  • Oracle supports running the 12c client jar files with an 11g database.

  • If you are running with Active GridLink, you must add the -Doracle.ucp.PreWLS1212Compatible=true system property to the server command line when running with 12c client jar files.

  • 12c client jars contain several changes in local transaction processing to maintain compliance with the JDBC specification. If setAutoCommit(true) is called and a local transaction exists, the transaction is automatically committed (in earlier releases, no action is taken). If setAutoCommit(true) is set and commit is called, an exception is thrown (in earlier releases, no action is taken). It is possible that existing applications will encounter these situations and it may be difficult to immediately change the software. Add the -Doracle.jdbc.autoCommitSpecCompliant=false system property to the server command line to preserve the legacy behavior existing applications.

  • JDBC 4.1 methods are supported when running with ojdbc7*.jar files

JDBC 4.1 Support for JDK 7

This release of WebLogic Server supports the JDBC 4.1 Specification when the environment is using JDK 7 and the JDBC driver is JDBC 4.1 compliant. To use new JDBC 4.1 methods with the Oracle thin client, you must use the ojdbc7.jar. If the methods are called for a driver that does not support JDBC 4.1, a java.lang.AbstractMethodError is thrown. See "JDBC™ 4.1 Specification" at http://download.oracle.com/otndocs/jcp/jdbc-4_1-mrel-spec/index.html.

Note:

WebLogic Server currently does not support the java.sql.driver interfaces required to use the Java SE 7 getParrentLogger method. See http://docs.oracle.com/javase/7/docs/api/index.html?java/sql/Driver.html.

JDK 7 also brings support for minor changes in Rowset 1.1 defined at http://jcp.org/aboutJava/communityprocess/maintenance/jsr114/114MR2approved.pdf. The WebLogic Server implementation of the new RowSetFactory is called weblogic.jdbc.rowset.JdbcRowSetFactory.

Using Application Continuity

In today's environment, application developers are required to deal explicitly with outages of the underlying software, hardware, communications, and storage layers. As a result, application development is complex and outages are exposed to the end users. For example, some applications warn users not to hit the submit button twice. When a warning is ignored, users may unintentionally purchase items twice or submit multiple payments for the same invoice.

Application Continuity (also referred to as Replay) is a general purpose, application-independent infrastructure for Active GridLink and Generic data sources that enables the recovery of work from an application perspective and masks many system, communication, and hardware failures. The semantics assure that end-user transactions can be executed on time and at-most-once. The only time an end user should see an interruption in service is when the outage is such that there is no point in continuing.

The following sections provide information on how to configure and use Application Continuity:

How Application Continuity Works

Following any outage that is due to a loss of database service, planned or unplanned, Application Continuity rebuilds the database session. Once an outage is identified by Fast Application Notification or a recoverable ORACLE error, the Oracle driver:

  • Establishes a new database session to clear any residual state.

  • If a callback is registered, issues a callback allowing the application to re-establish initial state for that session.

  • Executes the saved history accumulated during the request.

The Oracle driver determines the timing of replay calls. Calls may be processed chronologically or using a lazy processing implementation depending on how the application changes the database state. The replay is controlled by the Oracle 12c Database Server. For a replay to be approved, each replayed call must return exactly the same client visible state that was seen and potentially used by the application during the original call execution.

Requirements and Considerations

The following section provides requirements and items to consider when using Application Continuity with WebLogic applications:

  • Requires an Oracle 12c JDBC Driver and Database. See Using 12c Drivers with Oracle 12c Database.

  • For this release, Application Continuity only supports read and write transactions. XA transactions are not supported. See Selecting the Driver for Application Continuity.

    Note:

    Remember to set autocommit=FALSE to prevent breaking the transaction semantics and disabling Application Continutity in your environment.

  • Deprecated oracle.sql.* concrete classes are not supported. Occurrences should be changed to use either the corresponding oracle.jdbc.* interfaces or java.sql.* interfaces. Oracle recommends using the standard java.sql.* interfaces.

  • Application Continuity works by storing intermediate results in memory. An application may run slower and require significantly more memory than running without the feature.

  • Using the WebLogic statement cache is not supported. The size of the WebLogic statement cache must be set to 0.

  • Use of Oracle Proxy Authentication disables Application Continuity.

  • There are additional limitations and exceptions to the Application Continuity feature which may affect whether your application can use Replay. For more information, see "Application Continuity for Java" in the Oracle® Database JDBC Developer's Guide.

  • The database service that is specified in the URL for the datasource must be configured with the failover type set to TRANSACTION and the -commit_outcome parameter to TRUE . For example:

    srvctl modify service -d mydb -s myservice -e TRANSACTION -commit_outcome TRUE -rlbgoal SERVICE_TIME -clbgoal SHORT

Configuring Application Continuity

The following sections provide information on how to implement Application Continuity in your environment:

Selecting the Driver for Application Continuity

The administration console does not have an entry for a replay driver. To configure the JDBC replay data source, you must manually replace the existing Oracle data source class with the replay data source class oracle.jdbc.replay.OracleDataSourceImpl.

From the WebLogic Server Amdinistration console:

  1. From the WebLogic Server Administration Home page, select Configure GridLink for RAC Data Source.

  2. Click New and select GridLink Data Source or Generic Data Source.

  3. In Database Driver, select one of the non-XA entries for Oracle's Driver (Thin) for GridLink Connections Versions: 11 and later.

  4. Finish creating the data source without targeting to a server.

  5. Select and edit the new data source.

  6. From the Configuration: Connection Pool tab, replace the value of the Driver Class Name attribute with oracle.jdbc.replay.OracleDataSourceImpl.

  7. Click Save.

  8. Select the Targets tab.

  9. Select the target server(s).

  10. Click Save.

Make sure the Database Type is Oracle. See Requirements and Considerations.

Using a Connection Callback

The following sections provide information on how to use a Connection Callback:

Create an Initialization Callback

To create a connection initialization callback, your application must implement the initialize(java.sql.Connection connection) method of the oracle.ucp.jdbc.ConnectionInitializationCallback interface. Only one callback can be created per connection pool.

The callback is ignored if a labeling callback is registered for the connection pool. Otherwise, the callback is executed at every connection check out from the pool and at each successful reconnect following a recoverable error at replay. Use of the same callback at run time and at replay ensures that exactly the same initialization that was used when the original session was established is used during the replay. If the callback invocation fails, replay is disabled on that connection.

Note:

Connection Initialization Callback is not supported for clients (JDBC over RMI).

The following example demonstrates a simple initialization callback implementation:

. . .
import oracle.ucp.jdbc.ConnectionInitializationCallback ;
. . .
class MyConnectionInitializationCallback implements ConnectionInitializationCallback { 
  public MyConnectionInitializationCallback()  { 
  }
  public void initialize(java.sql.Connection connection)  throws SQLException {
     // Re-set the state for the connection, if necessary
  }
}
Registering an Initialization Callback

The WLDataSource interface provides the registerConnectionInitializationCallback(ConnectionInitializationCallback callback) method for registering initialization callbacks. Only one callback may be registered on a connection pool. The following example demonstrates registering an initialization callback that is implemented in the MyConnectionInitializationCallback class:

. . .
import weblogic.jdbc.extensions.WLDataSource;
. . .
MyConnectionInitializationCallback callback = new MyConnectionInitializationCallback();
((WLDataSource)ds).registerConnectionInitializationCallback(callback);
. . .

The callback can also be registered by entering the callback class in the Connection Initialization Callback attribute on the Oracle tab for a data source in the Administration Console.

Unregister an Initialization Callback

The WLDataSource interface provides the unregisterConnectionInitializationCallback() method for unregistering a ConnectionInitializationCallback. The following example demonstrates removing an initialization callback:

. . .
import weblogic.jdbc.extensions.WLDataSource;
((WLDataSource)ds).unregisterConnectionInitializationCallback();
. . .

Disabling Application Continuity for a Connection

You can disable Application Continuity on a per-connection basis using the following:

. . .
if (connection instanceof oracle.jdbc.replay.ReplayableConnection) {
 ((oracle.jdbc.replay.ReplayableConnection)connection).disableReplay();
}
. . .

Configuring Logging for Application Continuity

To enable logging of Application Continuity processing, use the following WebLogic property:

-Dweblogic.debug.DebugJDBCReplay=true

Use -Djava.util.logging.config.file=configfile, where configfile is the path and file name of the configuration file property used by standard JDK logging, to control the log output format and logging level. The following is an example of a configuration file that uses the SimplFormatter and sets the logging level to FINEST:

handlers = java.util.logging.ConsoleHandler 
java.util.logging.ConsoleHandler.level = ALL
java.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatter 
#OR - use other formatters like the ones below 
#java.util.logging.ConsoleHandler.formatter = java.util.logging.XMLFormatter 
#java.util.logging.ConsoleHandler.formatter = oracle.ucp.util.logging.UCPFormatter 

#OR - use FileHandler instead of ConsoleHandler 
#handlers = java.util.logging.FileHandler 
#java.util.logging.FileHandler.pattern = replay.log 
#java.util.logging.FileHandler.limit = 3000000000
#java.util.logging.FileHandler.count = 1 
#java.util.logging.FileHandler.formatter = java.util.logging.SimpleFormatter
oracle.jdbc.internal.replay.level attribute=FINEST

See Using Logging Services for Application Logging for Oracle WebLogic Server.

Global Database Services

Global Data Services (GDS) enables you to use a global service to provide seamless central management in a distributed database environment. A global server provides automated load balancing, fault tolerance and resource utilization across multiple RAC and single-instance Oracle databases interconnected by replication technologies such as Data Guard or GoldenGate.

The following sections provide information on requirements and configuration for GDS in WebLogic Server:

Requirements and Considerations

The following section provides requirements and considerations when using Global Database Services in WebLogic Server:

  • Requires an Oracle 12c JDBC Driver and Database. See Using an Oracle 12c Database with WebLogic Server 12.1.1.

  • It is not possible to use a single SCAN address to replace multiple Global Service manger (GSM) addresses.

  • For update operations to be handled correctly, you must define a service for updates that is only enabled on the primary database.

  • Define a separate service for Read-only operations that is located on the primary and secondary databases.

  • Since only a single service can be defined for a URL and a single URL for a datasource configuration, one datasource must be defined for the update service and another datasource defined for the read-only service.

  • Your application must be written so that update operations are process by the update datasource and read-only operations are processed by the read-only datasource.

Creating a GridLink DataSource for GDS Connectivity

Use the Administration Console to create a GridLink datasource that uses a modified URL to provide GDS connectivity. See "Create JDBC GridLink data sources" in the Oracle WebLogic Server Administration Console Help.

The connection information for a GDS URL is similar to a RAC Cluster, containing the following basic information:

  • Service name (Global Service Name)

  • Address/port pairs for Global Service Managers

  • GDS Region in the CONNECT_DATA parameter

The following is a sample URL:

jdbc:oracle:thin:@(DESCRIPTION= 
    (ADDRESS_LIST=(LOAD_BALANCE=ON)(FAILOVER=ON) 
         (ADDRESS=(HOST=myHost1.com)(PORT=1111)(PROTOCOL=tcp)) 
         (ADDRESS=(HOST=myHost2.com)(PORT=2222)(PROTOCOL=tcp))) 
    (CONNECT_DATA=(SERVICE_NAME=my.gds.cloud)(REGION=west)))

Container Database with Pluggable Databases

Container Database (CDB) is an Oracle Database feature that minimizes the overhead of having many of databases by consolidating them into a single database with multiple Pluggable Databases (PDB) in a single CDB. See "Managing Oracle Pluggable Databases" in the Oracle Database Administrator's Guide.

Creating Service for PDB Access

Access to a PDB is completely transparent to a WebLogic Server data source. It is accessed like any other database using a URL with a service. The service must be associated with the PDB. It can be created in SQLPlus by associating a session with the PDB, creating the service and starting it.

alter session set container = cdb1_pdb1; -- configure service for each PDB
execute dbms_service.create_service('replaytest_cdb1_pdb1.regress.rdbms.dev.us.myCompany.com','replaytest_cdb1_pdb1.regress.rdbms.dev.us.myCompany.com');
execute DBMS_SERVICE.START_SERVICE('replaytest_cdb1_pdb1.regress.rdbms.dev.us.myCompany.com');

If you want to set up the service for use with Application Continuity, it needs to be appropriately configured. For example, SQLPlus:

declare
params dbms_service.svc_parameter_array ;
begin
params('goal') := 'service_time' ;
params('commit_outcome') := 'true' ;
params('aq_ha_notifications') := 'true' ;
params('failover_method') := 'BASIC' ;
params('failover_type') := 'TRANSACTION' ;
params('failover_retries') := 60 ;
params('failover_delay') := 2 ;
dbms_service.modify_service('replaytest_cdb1_pdb1.regress.rdbms.dev.us.myCompany.com', params);
end;
/

Setting the PDB using JDBC

Initially when a connection is created for the pool, it is created using the URL with the service associated with a specific PDB in a CDB.

Executing ALTER SESSION SET CONTAINER is not supported from JDBC in WebLogic Server 12.1.1.

Automatic ONS Listener Support

In WebLogic Server 12.1.1, automatic ONS listeners are not supported. The ONS configuration information must be specified in the Oracle parameters for the datasource.

Database Resident Connection Pooling Support

In WebLogic Server 12.1.1, Database Resident Connection Pooling (DRCP) is not supported.