First Publication: 01-Nov-04
Last Update: 16-Jan-06
Author: Frances Zhao
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:
Native data sources implement the java.sql.DataSource interface and are provided by JDBC driver vendor.
This demo requires that the following sofware components are installed and configured correctly:
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.
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">
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.
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:
connection-pool-name="Pool Using DataSource Factory"
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.
A native data source has no dependencies on a connection pool. Here's an example of a 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.
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 =
Connection nativeDSConn = nativeDS.getConnection();
There are four data sources configured for this How-to. Please see the included %HOWTO_HOME%/etc/data-sources.xml for details.
The following instructions are for running this demonstration on a standalone instance of Oracle Containers for J2EE 10g (10.1.3).
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:
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.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
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).
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.
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:
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.
In this document, you should have: