3
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 DataSources chapter in the Oracle Application Server 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 exist in an XML file known as data-sources.xml.

Defining Location of the DataSource XML Configuration File

Your application can know about the data sources defined in this file only if the application.xml file knows about it. The path attribute in the <data-sources> element in the application.xml file must contain the name and path to your data-sources.xml file, as follows:

<data-sources
  path = "data-sources.xml"
/>

The path attribute of the <data-sources> element 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. Both the application.xml and data-sources.xml files are located in j2ee/home/config/application.xml. Thus, the path contains only the name of the data-sources.xml file.

Defining Data Sources

The j2ee/home/config/data-sources.xml file is pre-installed with a default data source. For most uses, this default is all you will need. However, you can also add your own customized data source definitions.

The 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 Oracle Application Server Containers for J2EE Services Guide for more information.

This data source is extremely fast and efficient, because it does not require any JTA or XA operations. These would be necessary if you were to manage more than a single database.

The following is 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="hr"
  password="hr"
  url="jdbc:oracle:thin:@myhost:1521:ORCL"
  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. 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.

Note:
Instead of providing the password in the clear, you can use password indirection. For details, see the Oracle Application Server Containers for J2EE Services Guide.

Alternatively, you can use the admin.jar command to install the data source as follows:

% java -jar admin.jar ormi://myhost admin welcome  

	-application myapp -installDataSource -jar $ORACLE_HOME/jdbc/classes12.jar 

	-url jdbc:oracle:thin:@myhost:1521:ORCL 

	-connectionDriver oracle.jdbc.driver.OracleDriver 

	-location jdbc/DefaultOracleDS -username hr -password hr

Note:

You must restart OC4J after you modify the data-sources.xml file.

See "Options for the OC4J Administration Management JAR" for a full description of the required parameters for this option.

The Data Sources chapter in the Oracle Application Server Containers for J2EE Services Guide fully describes all attributes.

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:

Retrieve the DataSource object through a JNDI lookup on the data source definition in the data-sources.xml file.

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 in the data-sources.xml file.

You must always cast or narrow the object that JNDI returns to the DataSource, because the JNDI lookup() method returns a Java object.
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 Oracle Application Server Containers for J2EE Services Guide.

3Data Sources Primer