Configure a data source using the administrative console

Application components use a data source to access connection instances to a relational database. We associate data sources with a JDBC provider configured for access to a specific vendor database. The application server requires both objects for the 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 the applications and the database.

The appserver has to be restarted for the newly-created datasource to be available for a JNDI from the application.

Tasks

1. Open the administrative console and access the necessary console panel using one of the following paths:
   • Resources > JDBC > Data sources
   • Resources > JDBC > JDBC providers > JDBC_provider > Data sources

2. Select the scope: Cell, node, cluster, or server.

3. Click New.

   The Create a data source wizard launches. The read-only scope field displays the previous scope selection.

4. Set the Data source name.

5. Set the JNDI name.

   The application server uses the JNDI name to bind resource references for an application to this data source.

   • Do not assign duplicate JNDI names across different resource types, such as data sources versus J2C or JMS connection factories.
   • Do not assign duplicate JNDI names for multiple resources of the same type in the same scope.

6. Click Next to see the Select JDBC provider panel.

   The Select JDBC provider panel is skipped if we do not have any JDBC providers configured at the current scope.

7. Select an existing JDBC provider, or create a new provider.

8. Complete all of the fields on the Enter database specific properties for the data source panel.

   • If using XA data source, click...
     Use this data source in container managed persistence (CMP)

   • Any other property fields displayed on this wizard panel are specific to the database type. See: Data source minimum required settings, by vendor.

   For User-defined data sources 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 we 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 the database documentation about setting these properties and any other requirements for our user-defined data source. After creating the data source, navigate to the corresponding custom properties collection panel in the administrative console by clicking Data sources > data_source > Custom properties. 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 we 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.

9. Optional: Configure the security aliases for the data source.

   A 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...

   Related Items > J2EE Connector Architecture (J2C) authentication data entries

   Component-managed alias	Represents a combination of ID and password specified in an application for data source authentication. The alias that we set on the data source must be identical to the alias in the application code.
   Mapping-configuration alias	Used if login configuration is absent on the component resource reference. Specifying a login configuration and 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 we specify the DefaultPrincipalMapping login configuration, the associated property is a JAAS - J2C authentication data entry alias.
   Container-managed authentication alias	Used if login configuration is absent on the component resource reference. Specifying a login configuration and associated properties on the component resource reference determines the container-managed authentication strategy when the res-auth value is set to Container.

   1. Use the drop-down list to select an existing component-managed authentication alias.

   2. To create a new alias, click the links 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. Restart the data source wizard by navigating back to the data source collection panel, selecting the appropriate scope, and clicking New.

   If we have defined security domains in the application server, we can click Browse... to select an authentication alias for the resource that we 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 we cannot use them.

10. Click Next to view the Summary panel, and review any information for the data source.

    If any information is not correct, we can click Previous to go back and correct it.

11. Click Finish to save the configuration and exit the wizard. You now see the Data sources panel, which displays the new configuration in a table along with other data sources configured for the same scope.

What to do next

• We can override the default values for some data source properties.

• We can configure additional properties that the database vendor might require or offers as options. Consult the database documentation about these settings.

• If we 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 our version of DB2 for z/OS.

• We can add the commitOrRollbackOnCleanup custom property to the settings of a JDBC data source if we want a specific action taken with any uncommitted work if the JDBC data source unexpectedly closes. The values that can be specified for this property are commit or rollback.

  If our JDBC data source supports Unit of Work (UOW) detection, this property only applies when we are working within a discrete unit of work. If our JDBC data source does not support UOW detection, this property always applies.

  If we do not add this property to the JDBC data source settings, any detected implicit transaction is rolled back, and the application must deal with any undetected implicit transactions.

  To add this custom property to the JDBC data source configuration settings:

  1. In the administrative console, click JDBC providers > JDBC_provider > Data sources > data_source > Custom properties > New.

  2. Enter commitOrRollbackOnCleanup in the Name field, and either commit or rollback in the Value field.

  3. Save changes.

Use the administrative console to assign the property values:

• Connection pool settings
• Tune connection pools
• WAS data source properties
• Java EE resource provider or connection factory custom properties collection

Configure a Version 4 data source

1. Click New to proceed to the console panel for defining required properties.

2. On this properties panel specify values for the fields that are grouped under the heading Configuration. The application server requires these properties to implement the JDBC driver classes.

3. Save the configuration by clicking OK. We are now finished with the primary data source configuration tasks.

4. Define other properties that the database vendor might require, or offer as options, for using the JDBC driver.

   Begin by clicking the Custom Properties link. Assign relevant properties based on the database documentation.

Subtopics

1. Disable statement pooling
   
2. Data source collection
   
3. Data source settings
   
4. Data source (WAS V4) collection (deprecated)
   
5. Data source (WAS Version 4) settings (deprecated)
   
6. Custom property settings
   
7. Custom Properties (Version 4) collection (deprecated)
   
8. Custom property (Version 4) settings (deprecated)
   

Related:

1. Data source lookups for enterprise beans and web modules
2. Data sources
3. JDBC providers
4. Naming
5. Manage Java 2 Connector Architecture authentication data entries for JAAS
6. Data source minimum required settings, by vendor
7. Data source settings