OC4J data sources are stored in an XML file known asdata-sources.xml.
Defining Data Sources
Thedata-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.
Definition of Data Sources
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.
TheOracleDS 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
■ Theclass attribute defines the type of data source you want to use.
■ Thelocation,xa-location, andejb-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 theejb-location JNDI name in the JNDI lookup for retrieving this data source.
■ Theconnection-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.
Definition of Data Sources
These fields can be modified in either the global Data Sources page or in the global data-sources.xml modification page. To navigate to thedata-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 thedata-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" on page 4-4 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. Selectdata-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" on page 4-4.
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.
Definition of Data Sources
Figure 4–1 General Section of Data Source Definition
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.
Definition of Data Sources
Figure 4–2 shows the JNDI Locations section.
Figure 4–2 JNDI Locations
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
Definition of Data Sources
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
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 ofdata-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.