Skip Headers

Oracle9iAS Containers for J2EE User's Guide
Release 2 (9.0.2)

Part Number A95880-01
Go To Documentation Library
Go To Product List
Solution Area
Go To Table Of Contents
Go To Index

Go to previous page Go to next page

Data Sources Primer

This chapter describes how to use the pre-installed default data source in your OC4J application. A data source, which is the instantiation of an object that implements the javax.sql.DataSource interface, enables you to retrieve a connection to a database server.

This chapter covers the following topics:

For more information on data sources, see the Data Source chapter in the Oracle9iAS Containers for J2EE Services Guide.


A data source is a Java object that has the properties and methods specified by the javax.sql.DataSource interface. Data sources offer a portable, vendor-independent method for creating JDBC connections. Data sources are factories that return JDBC connections to a database. J2EE applications use JNDI to look up DataSource objects. Each JDBC 2.0 driver provides its own implementation of a DataSource object, which can be bound into the JNDI namespace. Once bound, you can retrieve this data source object through a JNDI lookup.

Because they are vendor-independent, we recommend that J2EE applications retrieve connections to data servers using data sources.

Definition of Data Sources

OC4J data sources are stored in an XML file known as data-sources.xml.

Defining Data Sources

The data-sources.xml file is pre-installed with a default data source named OracleDS. For most uses, this default is all you will need. However, you can also add your own customized data source definitions. Enterprise Manager displays all data sources in the global Data Sources page. From the OC4J Home Page, scroll down to the Administration section and choose Data Source from the Application Defaults column. The following graphic shows the Data Source page.

Text description of def_ds2.gif follows.

Text description of the illustration def_ds2.gif

These data sources are able to be used by all applications deployed in this OC4J instance. To create data sources that are local to a particular application, drill down to the application page and then choose Data Source in the Administration section.

The OracleDS default data source is an emulated data source. That is, it is a wrapper around Oracle data source objects. You can use this data source for applications that access and update only a single data server. If you need to update more than one database and want these updates to be included in a JTA transaction, you must use a non-emulated data source. See the Data Sources chapter in the Oracle9iAS Containers for J2EE Services Guide for more information on non-emulated data sources.

The default emulated data source is extremely fast and efficient, because it does not enable two-phase commit operations. This would be necessary if you were to manage more than a single database.

The following shows the XML configuration for the default data source definition that you can use for most applications:


These fields can be modified in either the global Data Sources page or in the global data-sources.xml modification page. To navigate to the data-sources.xml modification page, select the default application from the OC4J Home page. Scroll down to the Administration section and choose Advanced Properties.

The Data Sources chapter in the Oracle9iAS Containers for J2EE Services Guide fully describes all elements for configuring any type of data source.

Configuring A New Data Source

You can configure global or local data sources. A global data source is available to all deployed applications in this OC4J instance. A local data source is configured within the deployed application and can only be used by that application.

See Oracle9iAS Containers for J2EE Services Guide for a full explanation of how to configure a data source and the elements within the data-sources.xml file.

To configure global data sources, select one of the following off of the OC4J Home Page:

To configure local data sources, you perform the same selection off of the application page. You must drill down to the particular application that this data source will be local to. On the application page, choose Data Source under the Resources column. It displays the same data source field page that is discussed in "Data Source Field Page".

Data Source Field Page

When you choose Data Source under the Application Defaults column, you can enter all configuration details about the data source into fields provided. This page is divided up into four sections.

Figure 4-1 shows the General section.

Figure 4-1 General Section of Data Source Definition

Text description of dsprime3.gif follows

Text description of the illustration dsprime3.gif

The General section enables you to define the following aspects about a data source:

Figure 4-2 shows the JNDI Locations section.

Figure 4-2 JNDI Locations

Text description of add_ds2.gif follows.

Text description of the illustration add_ds2.gif

The JNDI Locations section enables you to define the JNDI location string that the data source is bound with. This JNDI location is used within JNDI lookup for retrieving this data source. For emulated, you must provide all locations, even though only the EJB Aware Version Location is used. That is, you should only refer to the EJB Aware Version Location in your application.

Figure 4-3 shows the Connection Attributes section.

Figure 4-3 Connection Attributes

Text description of add_ds3.gif follows.

Text description of the illustration add_ds3.gif

This section enables you to modify connection tuning parameters, including the retry interval, pooling parameters, timeout parameters, and maximum attempt parameter.

Figure 4-4 shows the Properties section for the data source.

Figure 4-4 Properties

Text description of add_ds4.gif follows.

Text description of the illustration add_ds4.gif

If your data source is a third party data source, you may need to set certain properties. These properties would be defined in the third-party documentation. In addition, properties must be set for JTA transactions for the two-phase commit coordinator.

Defining the Location of the DataSource XML Configuration File

The elements you add or modify are stored by Enterprise Manager in an XML file. This file defaults to the name of data-sources.xml and is located in /j2ee/home/config. If you want to change the name or the location of this file, you can do this in the General Properties page off of the default application screen.

On the OC4J Home Page, scroll down to Default Application. Choose default. This brings you to the default application screen. Scroll down to the Administration section and choose General from the Properties column. Within the General Properties screen, shown below, you can modify the name and location of the data sources XML configuration file. Any location that you configure in the data sources path field must be relative to the /j2ee/home/config directory.

Text description of dsprime2.gif follows

Text description of the illustration dsprime2.gif

When applied, the data sources XML filename and path are stored in the global application.xml file. In the application.xml file, the <data-sources> element contains both the name and path of the data sources XML file.

The following shows the default configuration:

  path = "data-sources.xml"

The path attribute of the <data-sources> tag contains both path and name of the data-sources.xml file. The path can be fixed, or it can be relative to where the application.xml is located.

Retrieving a Connection From a Data Source

One way to modify data in your database is to retrieve a JDBC connection and use JDBC or SQLJ statements. We recommend that you use data source objects in your JDBC operations.

Do the following to modify data within your database:

  1. Retrieve the DataSource object through a JNDI lookup on the data source definition.

    The lookup is performed on the logical name of the default data source, which is an emulated data source that is defined in the ejb-location element.

    You must always cast or narrow the object that JNDI returns to the DataSource, because the JNDI lookup() method returns a Java object.

  2. Create a connection to the database represented by the DataSource object.

Once you have the connection, you can construct and execute JDBC statements against this database specified by the data source.

The following code represents the preceding steps:

Context ic = new InitialContext();
DataSource ds = (DataSource) ic.lookup("jdbc/OracleDS");
Connection conn = ds.getConnection();

Use the following methods of the DataSource object in your application code to retrieve the connection to your database:

You can cast the connection object returned on the getConnection method to oracle.jdbc.OracleConnection and use all the Oracle extensions. This is shown below:

oracle.jdbc.OracleConnection conn = 
(oracle.jdbc.OracleConnection) ds.getConnection();

Once retrieved, you can execute SQL statements against the database either through SQLJ or JDBC.

For more information, see the Data Sources chapter in the Oracle9iAS Containers for J2EE Services Guide.

Go to previous page Go to next page
Copyright © 2002 Oracle Corporation.

All Rights Reserved.
Go To Documentation Library
Go To Product List
Solution Area
Go To Table Of Contents
Go To Index