Application components use a data source to access connection instances
to a relational database.
Before you begin
The application server supports two different versions of a data
source. Determine the data source for your environment according to the enterprise
bean and the servlet specification levels that are the basis of your applications:
- Data sources (WebSphere Application Server Version
4) are for use with the Enterprise JavaBeans (EJB) 1.0 specification and
the Java Servlet 2.2 specification.
- Data sources of the latest standard version are for use with applications
that implement the more advanced releases of these specifications.
About this task
When you create a data source, you must associate it with a JDBC
provider that is configured for access to a specific vendor database. The
application server requires that both objects for your application to make
calls to that particular database and receive data from it. The data source
provides the connection management capabilities that allow data exchanges
between your applications and the database server.
Procedure
- Open the administrative console.
- Access the necessary console page in one of two
ways:
- Click Resources > JDBC > Data sources, or Data
sources (WebSphere Application Server Version 4).
- Click Resources > JDBC > JDBC providers > JDBC_provider > Data
sources, or Data sources (WebSphere Application Server Version 4).
- Select the scope at which applications
can use the data source. You can choose a cell, node, cluster,
or server. For more information, see the Administrative console scope settings article.
Version 4 only: From this point onward, the steps
for creating Data sources (WebSphere Application Server Version 4) differ
from the steps for creating data sources of the latest version. To configure
a Version 4 data source:
- Click New. This action causes
the Create a data source wizard to launch and display the Enter basic
data source information page. The first field is the scope
field, which is read-only. This field displays your previous scope selection.
- Type a data source name in the Data source name
field. This name identifies the data source for administrative
purposes only.
- Type a Java Naming and Directory Interface (JNDI)
name in the JNDI name field. The application server uses the JNDI
name to bind application resource references to this data source. Follow these
requirements when specifying JNDI names:
- Do not assign duplicate JNDI names across different resource types (such
as data sources versus J2C connection factories or JMS connection factories).
- Do not assign duplicate JNDI names for multiple resources of the same
type in the same scope.
For more information on JNDI, consult the Naming article.
- Set a component-managed alias to secure your data
source. A component-managed alias represents a combination of ID
and password that is specified in an application for data source authentication.
Therefore, the alias that you set on the data source must be identical to
the alias in the application code. For more information on Java 2 Connector
(J2C) security, see the Managing J2EE Connector Architecture authentication data entries article.
Configuring
an alias is an optional step. If you do not require application components
to authenticate with the data source, select (none) from the drop-down
list.
To set a component-managed alias, either select an existing alias
or create a new one.
- Use the drop-down list to select an existing component-managed authentication
alias.
- To create a new alias, click the create a new one link. This
action closes the data source wizard and triggers the administrative console
to display the J2C authentication data collection page. Click New to
define a new alias. Click OK to save your settings and view the new
alias on the J2C authentication data collection page. Restart the data source
wizard by navigating back to the data source collection page, selecting the
appropriate scope, and clicking New.
- Click Next to see the wizard page Select
JDBC provider.
- Either select an existing JDBC provider, or create
a new provider.
To select an existing JDBC provider:
- Click Select an existing JDBC provider.
- Select a JDBC driver from the drop-down list.
- Click Next. You now see the page entitled
Enter database specific properties for the data source.
To create a new JDBC provider:
- Click Create new JDBC provider.
- Click Next to see the Create JDBC provider page.
- Use the first drop-down list to select the database type of
the JDBC provider that you need to create.
Supported configurations: Select
User-Defined for
your database type if you encounter either of the following scenarios:
- You do not see your database type.
- You cannot select the JDBC provider type that you need in the next step.
The user-defined selection triggers the wizard page to display your provider
type as a User-defined JDBC provider, and your implementation type as User-defined.
Consult your database documentation for the JDBC driver class files, data
source properties, and so on that are required for your user-defined provider.
You must supply this information on the next two wizard pages: one page for
database class path information, and the other page for database-specific
properties.
sptcfg
- Select your JDBC provider type if it is displayed in the second
drop-down list. Select Show Deprecated to trigger the display
of both current and deprecated providers. If you cannot find your provider
in this expanded list, then select User-Defined from the previous list
of database types.
- From the third drop-down list, select the implementation type
that is necessary for your application. If your application does
not require that connections support two-phase commit transactions, choose Connection
Pool Data Source. Choose XA Data Source, however, if your application
requires connections that support two-phase commit transactions. Applications
that use this data source configuration have the benefit of container-managed
transaction recovery.
After you select an implementation type, the wizard
fills the name and the description fields for your JDBC provider. You can
type different values for these fields; they exist for administrative purposes
only.
- Click Next after you have defined your database type,
provider type, and implementation type. Now you see the wizard page Enter
database class path information.
- In the class path field, type the full path location of the
database JDBC driver class files. Your class path information becomes
the value of the environment variable that is displayed on this page, in the
form of ${DATABASE_JDBC_DRIVER_PATH}. The application server uses the
variable to define your JDBC provider; this practice eliminates the need to
specify static JDBC class paths for individual applications. Remember that
if you do not provide the full, correct JDBC driver class path for the variable,
your data source ultimately fails. If the field already displays a fully qualified
class path, you can accept that variable definition by completing the rest
of this wizard page and clicking Next.
- Use the Native library path field to
specify additional class files that your JDBC driver might require to function
properly in your application server environment. Type the full directory path
name of these class files.
- Click Next . You will now see the panel entitled Enter
database specific properties for the data source.
- Complete all of the fields on the Enter database
specific properties page.
- Click Use this data source in container managed persistence (CMP) if
container managed persistence (CMP) enterprise beans must access this data
source.
- Any other property fields that are displayed on this wizard page are specific
to your database type. Read Data source minimum required settings, by vendor for
information on these property settings. The topic addresses the current and
deprecated JDBC providers that are pre-defined in the application server.
User-defined data sources: This wizard page does not
display additional property fields for data sources that correspond with your
user-defined JDBC providers. However, from the JDBC driver class files that
you installed, the application server can generally extract the necessary
property names for the data source. The application server defines them as
data source custom properties, displays them on a custom properties
console page, and assigns them default values. Consult your database documentation
about setting these properties and any other requirements for your user-defined
data source. After you create the data source, navigate to the corresponding
custom properties collection page in the administrative console by clicking . Review the default
values for the properties, and modify them if necessary.
The
application server can only extract vendor-specific properties from the driver
class files if you install the files on the deployment manager node and configure
their representative variables correctly. Otherwise, the product displays
an informational message (as opposed to an error message) that directs you
to manually define the necessary properties as custom properties.
- Click Finish to save the configuration
and exit the wizard. You now see the data source collection
page that displays your new configuration in a table, along with other data
sources that are configured for the same scope.
What to do next
You can override the default values for some data source properties.
You can also configure additional properties that your database vendor might
require or offers as options. Consult your database documentation about these
settings.
If you use the DB2 Universal JDBC Driver provider,
learn about optional data source properties in the Application Programming
Guide and Reference for Java for your version of DB2 for z/OS.
The
following topics in this information center inform you how to use the administrative
console to assign or modify property values: