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
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:
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:
-
Stand Alone Installation: %ORACLE_HOME%/bin/oc4j
start
Note that the oc4j command
expects the JAVA_HOME environment variable to point to a full JDK
installation.
-
OracleAS Managed Installation: %ORACLE_HOME%/opmn/bin/opmnctl startall
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:
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:
Running the Application
In a browser window, browse to:
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
Bookmark
