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 data source. Determine the data source for your environment according
to the enterprise bean and 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 associate it with a Java Database Connectivity (JDBC)
provider that is configured for access to a specific vendor database.
The application server requires both objects for your applications
to make calls to that particular database and receive data from it.
The data source provides connection management capabilities that physically
make possible these exchanges between your applications and the database.Remember: The server has to be restarted for the
newly-created datasource to be available for a Java Naming
and Directory Interface (JNDI) from the application.
Procedure
- Open the administrative console.
- Access the necessary console panel.
Use one
of the following paths:
- Click .
- Click
- Click
- Click .
- 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 topic on scope settings.
Version 4 only: From this point onward, the
steps for creating
WebSphere Application Server Version
4 data sources differ from the steps for creating data sources of
the latest standard 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 panel.
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 resource references
for an application to this data source. Follow these requirements
when you specify 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 topic on naming.
- Click Next to see the Select JDBC provider panel.
The Select JDBC provider panel is skipped
if you do not have any JDBC providers that are configured at the current
scope.
- Select an existing JDBC provider, or create a new provider.
- Select an existing JDBC provider.
- Click Select an existing JDBC provider.
- Select a JDBC driver from the list.
- Click Next. You now see the panel entitled Enter
database specific properties for the data source.
- Create a new JDBC provider.
- Click Create new JDBC provider.
- Click Next to see the Create
JDBC provider panel.
- Use the first drop-down list to select the database type of the
JDBC provider that you need to create.
The User-Defined option: 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 panel 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 panels:
- database class path information
- database-specific properties
- If the JDBC provider type is displayed in the second list, select
your JDBC provider type. 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 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 panel 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 WebSphere environment
variable that is displayed on this panel, 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 panel and clicking Next.
- Use the Native library path field to specify
additional class files that your JDBC driver might require to function
properly on your application server platform. Type the full directory
path name of these class files.
- Click Next. You now see the Enter
database specific properties for the data source panel.
- Complete all of the fields on the Enter database
specific properties for the data source panel.
- 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 panel
are specific to your database type. See the topic, Data source minimum
required settings, by vendor, for information on these property settings.
The article addresses both current and deprecated JDBC providers that
are predefined in the application server.
User-defined data sources: This wizard panel
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 data source property names. The
application server defines them as data source custom properties,
displays them on a custom properties console panel, 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 panel in the administrative console by
clicking . Review the
property default values 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 WebSphere 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.
- Optional: Configure the security aliases for
the data source.
You can select none for any of the authentication
methods, or choose one of the following types:
- Component-managed authentication alias -
specifies an authentication alias to use when the component resource
reference res-auth value is Application. To define a new alias, navigate
to . 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.
- Use the drop-down list to select an existing component-managed
authentication alias.
- To create a new alias, click the links that are provided. This
action closes the data source wizard and triggers the administrative
console to display the J2C authentication data panel. Click New to
define a new alias. Click OK to save your settings
and view the new alias on the J2C authentication data panel. Restart
the data source wizard by navigating back to the data source collection
panel, selecting the appropriate scope, and clicking New.
For more information on Java 2
Connector (J2C) security, see the topic on managing Java 2 Connector Architecture authentication
data entries.
- Mapping-configuration alias - is used only
in the absence of a login configuration on the component resource
reference. The specification of a login configuration and the associated
properties on the component resource reference is the preferred way
to define the authentication strategy when the res-auth value is set
to Container. If you specify the DefaultPrincipalMapping login configuration,
the associated property is a JAAS - J2C authentication data entry
alias.
- Container-managed authentication alias -
is used only in the absence of a login configuration on the component
resource reference. The specification of a login configuration and
the associated properties on the component resource reference determines
the container-managed authentication strategy when the res-auth value
is set to Container.
Note: If you have defined security domains in the application
server, you can click Browse... to select an
authentication alias for the resource that you are configuring. Security
domains support isolating authentication aliases between servers.
The tree view is useful in determining the security domain to which
an alias belongs, and the tree view can help you determine the servers
that are able to access each authentication alias. The tree view is
tailored for each resource, so domains and aliases are hidden when
you cannot use them.
- Click Next to view the Summary panel,
and review any information for the data source.
If any
information is not correct, you can click Previous to
go back and correct it.
- Click Finish to save the configuration
and exit the wizard.
You now see the Data
sources panel, which 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 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 or DB2 Using IBM JCC Driver, learn about optional
data source properties in the Application Programming Guide and
Reference for Java for your
version of DB2 for z/OS.
- You can add the commitOrRollbackOnCleanup custom property to the
settings of a JDBC data source if you want a specific action taken
with any uncommitted work if your JDBC data source unexpectedly closes.
The values that can be specified for this property are commit or rollback.
If
your JDBC data source supports Unit of Work (UOW) detection, this
property only applies when you are working within a discrete unit
of work. If your JDBC data source does not support UOW detection,
this property always applies.
If you do not add this property
to your JDBC data source settings, any detected implicit transaction
is rolled back, and your application must deal with any undetected
implicit transactions.
To add this custom property to your JDBC
data source configuration settings:
- In the administrative console, click .
- Enter commitOrRollbackOnCleanup in the Name field,
and either commit or rollback in
the Value field.
- Save your changes.