How-To Configure and Use OC4J 10g (10.1.3) Data Sources

First Publication: 01-Nov-04
Last Update: 16-Jan-06
Author: Frances Zhao

• Introduction
• What are the Prerequisites?
  • What Should You Know?
  • What are the Software Requirements?
  • What are the Notations?
• How to Build the Application?
  • Configuring the Data Sources
• How to Run the Application?
  • Examining the How to Distribution
  • Setting up the Application
  • Running an OC4J Instance
  • Generating, Compiling and Deploying the Application
  • Running the Application
• Summary

Introduction

This demo shows how to configure OC4J's managed and native data sources, and tests connections to the configured data sources in JSP code.

OC4J 10.1.3 provides a simplified data source classification, and there are only two types of data sources: managed and native. Managed data sources are data sources that are managed by OC4J. A managed data source is an OC4J-provided implementation of the java.sql.DataSource interface that acts as a wrapper to a JDBC driver or data source.

Managed data sources differ from native data sources in the following manner:

• The connections retrieved from a managed data source can participate in global transactions.
• A managed data source makes use of OC4J's connection pool and statement cache.
• A connection returned from a managed data source is wrapped with an OC4J Connection proxy.

Native data sources implement the java.sql.DataSource interface and are provided by JDBC driver vendor.

What are the Prerequisites?

What you should know?

• You should be familiar with these technologies: DataSource, JSP;
• Link to other OC4J Howto's on OTN

What are the Software Requirements?

This demo requires that the following sofware components are installed and configured correctly:

• Oracle Containers for J2EE 10g (10.1.3) , standalone version, with a web site configured (example http-web-site)
• Sun JDK 1.4_02 or above.
• Any HTML browser like Mozilla, Microsoft Internet Explorer, Netscape, etc.

What are the Notations?

• %ORACLE_HOME% - The directory where you installed OC4J.
• %JAVA_HOME% - The directory where your JDK is installed
• %HOWTO_HOME% - The directory where this demo is unzipped

How to Build the Application?

Configuring the Data Sources

Like in previous OC4J versions, the OC4J 10.1.3 data sources are still defined in an appliction's data-sources.xml file. The default data source configuration file for all applications is still located at %ORACLE_HOME%/j2ee/home/config/data-sources.xml.

To define data sources you can edit the data sources configuration file directly or use Enterprise Manager to create, delete, and modify data sources. This How-to explains the first approach only.

Defining a Connection Pool

A managed data source uses a connection pool to efficiently manage connections. If you use managed data sources, you must define at least one connection pool. Here's an example definition from this How-to:

<connection-pool name="Pool Using DataSource Factory">
  <connection-factory
    factory-class="oracle.jdbc.pool.OracleDataSource"
    user="scott"
    password="tiger"
    url="jdbc:oracle:thin:@//dbhost:1521/dbservicename">
  </connection-factory>
</connection-pool>

The connection-pool element contains a name attribute that uniquely identifies the connection pool. A connection pool uses a connection factory (defined by the connection-factory element) to get physical connections from the database.

The connection-factory element contains the URL that the JDBC driver uses to connect to the database along with a default user and password that can be used to get connections from the database. The factory-class attribute defines the implementation class provided by the JDBC driver that is used to get the connections. The implementation class must be an implementation of java.sql.Driver, javax.sql.DataSource, javax.sql.XADataSource, or javax.sql.ConnectionPoolDataSource.

Defining a Managed Data Source

After you have defined at least one connection pool you can define a managed data source. Here's an example of a managed data source in this How-to using the connection pool defined above:

<managed-data-source
  name="OracleManagedDS2"
  connection-pool-name="Pool Using DataSource Factory"
  jndi-name="jdbc/OracleManagedDS2"/>

The name attribute uniquely identifies the managed data source. The jndi-name attribute defines the location with which this data source will be placed into JNDI. The connection-pool-name attribute identifies the connection pool with which this managed data source will interact to get connections.

Defining a Native Data Source

A native data source has no dependencies on a connection pool. Here's an example of a native data source:

<native-data-source
  name="OracleNativeDS"
  jndi-name="jdbc/OracleNativeDS"
  description="Native DataSource"
  data-source-class="oracle.jdbc.pool.OracleDataSource"
  user="scott"
  password="tiger"
  url="jdbc:oracle:thin:@//dbhost:1521/dbservicename">
</native-data-source>

The name attribute uniquely identifies the native data source. The jndi-name attribute defines the location with which this data source will be placed into JNDI. The data-source-class defines the implementation class of the native data source and must be an implementation of javax.sql.DataSource. The user and password attributes define the default user and password. The url attribute defines the url that the data source will use to communicate with the database.

Using the Configured Data Sources

Once the data sources are configured, you still use them in the same way as in previous OC4J versions. Here is an example in this How-to's JSP code:

InitialContext ic = new InitialContext();
DataSource nativeDS =
  (DataSource) ic.lookup("jdbc/OracleNativeDS");
Connection nativeDSConn = nativeDS.getConnection();

More about this application

There are four data sources configured for this How-to. Please see the included %HOWTO_HOME%/etc/data-sources.xml for details.

• Native data source: using Oracle JDBC DataSource
• Managed data source: using a connection pool with an XADataSource connection factory
• Managed data source: using a connection pool with a DataSource connection factory
• Managed data source: using a connection pool with a Driver connection factory

For each data source, clicking the associated button would invoke a JSP that tries to obtain a connection from that data source. A new page would indicate whether the connection is successfully obtained, or an exception has occurred. There would be a back link on the new page that brings you back to this page.

 

How to Run the Application?

The following instructions are for running this demonstration on a standalone instance of Oracle Containers for J2EE 10g (10.1.3).

Examining the How to Distribution

• build - temporary directory created during the build
• log - temporary directory holding build/deploy logs
• etc - all necessary files to package the application
• lib - holds the application archives that could be deployed (e.g., ear, war, rar, jar files)
• doc - the How-to document and Javadoc's
• • javadoc - the javadoc of the different source files
  • how-to-datasource.html - this How-to page
• src - the source of the demo
  • web - contains HTML pages and the JSP code

Setting Up the Application

Environment Configuration

Please check to make sure that the following properties are configured correctly in the ant-oracle.properties file located in the root of the sample's distribution (NOTE:  Some of these properties will default to the values of corresponding environment variables as noted below.  If you have these variables setup in your environment you may not have to alter the values in the file).  If necessary, modify these variable to the proper values for you environment:

• oracle.home - the root directory of oracle installation.  Defaults to ORACLE_HOME environment variable.
• java.home -  the root directory of JDK installation.  Defaults to JAVA_HOME environment variable.
• oracleas.host - the hostname of the platform on which the OC4J instance is running.  Defaults to localhost.
• oracleas.http.port - the port on which the OC4J HTTP listener is listening.  Defaults to 8888.
• oracleas.admin.port  - the port on which the OC4J administration processor is listening.  Defaults to 23791.
• oracleas.admin.user - the name of the OC4J administrator.  Defaults to " oc4jadmin".
• oracleas.admin.password - the password for the OC4J administrator.  Defaults to " welcome".
• oracleas.binding.module - the name of the HTTP web site to which the deployed application is bound.  Defaults to " default-web-site".

In addition, please make sure that the ant command associated with the OC4J ant distribution is in your execution path ( %ORACLE_HOME%/ant/bin).

Configuring the Environment for a Managed OracleAS Instance

If you are running a managed version of the Oracle Application Server 10 g, you are using OPMN, you must change the following values to match your configuration:

• oracleas.http.port - the port on which the Oracle HTTP Server (OHS) is listening.
• oracleas.admin.port  - The OPMN request port, as specified in opmn.xml, the default value is 6003.  You can also check the OPMN request port using the following command: %ORACLE_HOME%/opmn/bin/opmnctl status -port
• oracleas.admin.user - the name of the OC4J administrator.  Defaults to " oc4jadmin".
• oracleas.deployer.uri - the URI to use to do the different administration operation (deployment, undeployment). The file contains different URI depending of the topology of your application: stand alone OC4J, Managed Single Node or Managed Cluster. You just need to un-comment the URI that matches your toplogy.
• oracleas.oc4j.instance - This is the managed OC4J instance where the application will be deployed or undeployed.

Database Configuration

This demo requires an Oracle database and listener to be running. Note down the hostname, port number, and the service name used -- you need to modify the %HOWTO_HOME%/etc/data-sources.xml with these information.

Starting the OC4J Instance

Start an OracleAS 10 g (10.1.3) instance as follows:

Generating, Compiling and Deploying the Application

Build Script Setup

Ensure Ant 1.6.2 or above is installed on your machine and configured correctly. On some operating systems Ant does not currently support the use of environment variables. If this is the case for your operating system, please modify the common.xml file located in the top-level %HOWTO_HOME% directory.

In addition, please make sure that the ant command associated with the OC4J ant distribution is in your execution path ( %ORACLE_HOME%/ant/bin).

Build the Application

In the top-level %HOWTO_HOME% directory, type the command:

• ant

You should now have newly created datasource_demo.ear in your %HOWTO_HOME%/dist directory.

This command would also attempt to deploy the application if the build is successful. It will first test whether OC4J is running.

Deploy and Bind the Application

You can also deploy and bind the application separately by using the following command. Make sure the %ORACLE_HOME% environment variable is defined. In the top-level %HOWTO_HOME% directory, type the command:

• ant bind-web-app

Running the Application

In a browser window, browse to:

• http://localhost:8888/datasource_demo

If the website hostname or port number are different, then use those values instead.

For each data source, clicking the associated button would invoke a JSP that tries to obtain a connection from that data source. A new page would indicate whether the connection is successfully obtained, or an exception has occurred. There would be a back link on the new page that brings you back to the beginning page.

Summary

In this document, you should have:

• Known what are the new types of OC4J data sources
• Learned how to configure and use each type of data source