82 Configuring a Data Source Login

This chapter describes how to configure TopLink data source logins.

Table 82-1 lists the types of TopLink data source logins that you can configure and provides a cross-reference to the type-specific chapter that lists the configurable options supported by that type.

Table 82-1 Configuring TopLink Data Source Logins

If you are configuring a...	See...
DatabaseLogin	Chapter 83, "Configuring a Database Login"
EISLogin	Chapter 84, "Configuring an EIS Login"

Table 82-2 lists the configurable options shared by two or more TopLink data source login types.

When using the sessions.xml file to configure login information, TopLink will override any login information in the project.xml and instead use the information from the sessions.xml configuration. For more information, see "Understanding Data Access".

Configuring Common Data Source Login Options

Table 82-2 lists the configurable options shared by two or more TopLink data source login types. In addition to the configurable options described here, you must also configure the options described for the specific Data Source Login Types, as shown in Table 82-1

Table 82-2 Common Data Source Login Options

Option	Type	TopLink Workbench	Java
"Configuring User Name and Password"	Basic
"Configuring Password Encryption"	Advanced
"Configuring External Connection Pooling"	Advanced
"Configuring Properties"	Advanced
"Configuring a Default Null Value at the Login Level"	Advanced

Configuring User Name and Password

Optionally, you can specify the user name and password of a login.

If you specify a password using TopLink Workbench, enter the plain text (not encrypted) value. By default, TopLink Workbench writes passwords to and reads passwords from the sessions.xml file in encrypted form using JCE encryption. For information on configuring password encryption, see "Configuring Password Encryption".

Configuring Password Encryption

By default, passwords are written to and read from the sessions.xml file in encrypted form using JCE encryption.

Currently, TopLink Workbench does not support specifying the encryption class used. To change the encryption class used, you must modify the login in Java using a preLogin event listener.

Using Java

To specify the encryption class that TopLink should use to write a password to or read a password from the sessions.xml file, use DatasourceLogin method setEncryptionClassName, passing in the name of the encryption class as a String.

To configure a DatasourceLogin with an encrypted password, use DatasourceLogin method setEncryptedPassword, passing in the encrypted password as a String.

Configuring External Connection Pooling

For non-J2EE applications, you typically use internal connection pools provided by TopLink (see "Internal Connection Pools"). In this case, you can use TopLink Workbench to configure connection pool options and to create a sequence connection pool and application-specific (named) connection pools.

For J2EE applications, you typically use external connection pools provided by a JDBC driver or J2EE container (see "External Connection Pools"). Optionally, you can configure a read connection pool to use a nontransactional login, and you can configure a sequence connection pool to use a separate (preferably nontransactional) login of its own.

Because JTA external transaction controllers are dependent upon the external transaction service that the application server provides, you must configure TopLink to use external connection pools if you are using an external transaction controller (see "Integrating the Unit of Work With an External Transaction Service").

External connection pools enable your TopLink application to do the following:

Integrate into a J2EE-enabled system.
Integrate with JTA transactions (JTA transactions require a JTA-enabled data source).
Leverage a shared connection pool in which multiple applications use the same data source.
Use a data source configured and managed directly on the server.

For more information about connection pools, see "Connection Pools".

Using TopLink Workbench

To specify if the session login uses external connection pooling, use this procedure:

Configure a data source on the application server.

If you are using the external connection pool with an external transaction controller (see "Configuring the Server Platform"), be sure to configure a JTA-enabled data source.

For more information, see your J2EE container documentation.
Select a server or database session in the Navigator. Its properties appear in the Editor.
Click the Login tab. The Login tab appears.
Click the Connection subtab. The Connection subtab appears.

Figure 82-1 Login Tab, Connection Subtab, External Connection Pooling Field, Database Driver

Description of "Figure 82-1 Login Tab, Connection Subtab, External Connection Pooling Field, Database Driver"

Figure 82-2 Connection Tab, External Connection Pooling Field, J2EE Data Source

Description of "Figure 82-2 Connection Tab, External Connection Pooling Field, J2EE Data Source"

Specify if this login uses External Connection Pooling. For a database driver, external connection pooling is optional. For a J2EE data source, external connection pooling is mandatory.

Configuring Properties

For all DatasourceLogin types, you can specify custom named values, called properties. Some data sources require additional, driver-specific properties not supported in the DatasourceLogin API (for example, see "JDBC Driver Properties Optimization"). Add these properties to the DatasourceLogin so that TopLink can pass them to the driver.

For relational sessions, you must first enable advanced option Use Properties (see "Configuring Advanced Options").

For EIS sessions, properties are always enabled.

Note:

Do not set a password as a property. Always use TopLink Workbench or DatabaseLogin method setPassword. For more information on configuring a password, see "Configuring User Name and Password".

When using TopLink Workbench, you can only set character values, which TopLink returns as String objects (see "Using TopLink Workbench").

When using Java, you can set any Object value (see "Using Java").

Using TopLink Workbench

To specify arbitrary named value pairs that TopLink associates with a DatasourceLogin, use this procedure:

To add (or change) a new Name/Value property, click Add (or Edit). Add Property dialog box appears.

Use the following information to add or edit a login property on the Add Property dialog box:

Option	Description
Name	The name by which TopLink retrieves the property value using the `DatasourceLogin` method `getProperty`.
Value	The value TopLink retrieves using the `DatasourceLogin` method `getProperty` passing in the corresponding property name. Using TopLink Workbench, you can set only character values that TopLink returns as `String` objects.

To delete an existing property, select the Name/Value row and click Remove.

Using Java

Using Java, you can set any Object value using DatasourceLogin method setProperty. To remove a property, use DatasourceLogin method removeProperty.

Configuring a Default Null Value at the Login Level

A default null value is the Java Object type and value that TopLink uses instead of null when TopLink reads a null value from a data source.

When you configure a default null value at the login level, it applies to all mappings used in a session. In this case, TopLink uses it to translate in one direction only: when TopLink reads null from the data source, it converts this null to the specified type and value.

You can also use TopLink to set a default null value on a per-mapping basis (see "Configuring a Default Null Value at the Mapping Level").

Note:

A default null value must be an Object. To specify a primitive value (such as int), you must use the corresponding Object wrapper (such as Integer).

Using Java

Using Java API, you can configure a default null value for all mappings used in a session with the DatabaseLogin method setDefaultNullValue(Class,Object).

For example:

// Defaults all null String values read from the database to empty String
session.getLogin().setDefaultNullValue(String.class, "");