|Oracle9iAS Containers for J2EE User's Guide
Release 2 (9.0.2)
Part Number A95880-01
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:
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.
OC4J data sources are stored in an XML file known as
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.
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.
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" />
classattribute defines the type of data source you want to use.
ejb-locationattributes 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-locationJNDI name in the JNDI lookup for retrieving this data source.
connection-driverattribute defines the type of connection you expect to be returned to you from the data source.
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.
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.
To configure global data sources, select one of the following off of the OC4J Home Page:
data-sources.xmlon 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".
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.
The General section enables you to define the following aspects about a data source:
com.evermind.sql.ConnectionDataSource, that the data source is instantiated as.
Figure 4-2 shows the JNDI Locations section.
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.
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.
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.
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
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 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.
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:
DataSourceobject 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
You must always cast or narrow the object that JNDI returns to the
DataSource, because the JNDI
lookup() method returns a Java
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:
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:
Once retrieved, you can execute SQL statements against the database either through SQLJ or JDBC.