4
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:

• Introduction

• Definition of Data Sources

• Retrieving a Connection From a Data Source

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

Introduction

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 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:

<data-source
  class="com.evermind.sql.DriverManagerDataSource"
  name="OracleDS"
  location="jdbc/OracleCoreDS"
  xa-location="jdbc/xa/OracleXADS"
  ejb-location="jdbc/OracleDS"
  connection-driver="oracle.jdbc.driver.OracleDriver"
  username="scott"
  password="tiger"
  url="jdbc:oracle:thin:@localhost:5521:oracle"
  inactivity-timeout="30"
/>

• The class attribute defines the type of data source you want to use.

• The location, xa-location, and ejb-location attributes are JNDI names that this data source is bound to within the JNDI namespace. While you must specify all three, we recommend that you use only the ejb-location JNDI name in the JNDI lookup for retrieving this data source.

• The connection-driver attribute defines the type of connection you expect to be returned to you from the data source.

• The URL, username, and password identify the database, its username, and password.

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:

• Data Sources under the Application Defaults column--This page allows you to add data source definitions one field at a time. See "Data Source Field Page" for a description of this page.

• Advanced Properties in the default application--On the OC4J Home Page, select the default application. Scroll down to the Administration section and select Advanced Properties. Select data-sources.xml on this page. This allows you to add data sources using the XML definitions. This is useful if you have been provided the XML. You can just copy in the data source XML.

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 the illustration dsprime3.gif

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

• Name--A user-defined name to identify the data source.

• Description--A user-defined description of the data source.

• Data Source Class--This is the class, such as com.evermind.sql.ConnectionDataSource, that the data source is instantiated as.

• Schema--This is an optional parameter. Input the file name that contains the Java to database mappings for a particular database.

• Username/Password--The username and password used to authenticate to the database that this data source represents.

• JDBC URL--The URL to the database represented by this data source. For example, if using an Oracle Thin driver, the URL could be the following: jdbc:oracle:thin:@my-lap:1521:SID.

• JDBC Driver--The JDBC driver to use. One example of a JDBC driver is oracle.jdbc.driver.OracleDriver.

Figure 4-2 shows the JNDI Locations section.

Figure 4-2 JNDI Locations

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 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 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 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:

<data-sources
  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:

• getConnection();

  The username and password are those defined in the data source definition.

• getConnection(String username, String password);

  This username and password overrides the username and password defined in the data source definition.

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.