Configuring a Data Source Login (ELUG)

For the latest EclipseLink documentation, please see http://www.eclipse.org/eclipselink/documentation/

---

Related Topics

This table lists the types of EclipseLink data source logins that you can configure, and provides a cross-reference to the type-specific section that lists the configurable options supported by that type.

Configuring EclipseLink Data Source Logins

If you are configuring a...	See...
DatabaseLogin	Configuring a Database Login
EISLogin	Configuring an EIS Login

When using the sessions.xml file to configure login information, EclipseLink will override any login information in the project.xml and instead use the information from the sessions.xml configuration.

For more information, see the following:

• Introduction to Data Access
• Configuring Login Information at the Project Level

Configuring Common Data Source Login Options

The following table lists the configurable options shared by two or more EclipseLink 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 (see Data Source Login Types), as shown in the Configuring EclipseLink Data Source Logins table.

Common Data Source Login Options

Option to Configure	Workbench	Java
User name and password
Password encryption
Configuring external connection pooling
Configuring properties
Default null value at the login level

Configuring User Name and Password

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

We recommend that you do not save the password with a deployment login.

If you specify a password, using an EclipseLink tool or Java, enter the plain text (not encrypted) value. EclipseLink will encrypt the password using JCE encryption.

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

By default, EclipseLink does not write passwords to and read passwords from the project.xml file unless you configure your project-level data source login accordingly. When you configure EclipseLink to write passwords and read passwords from the project.xml file, by default, it does so in encrypted form using JCE encryption.

For more information, see the following:

• Configuring Login Information at the Project Level
• Configuring Password Encryption

How to Configure User Name and Password Using Workbench

To specify a user name and password, use this procedure:

1. Select a server or database session in the Navigator. Its properties appear in the Editor.
2. Click the Login tab. The Login tab appears.
3. Click the Connection subtab. The Connection subtab appears.
   Login Tab, Connection Subtab, User Name and Password Fields
   
4. Enter a user name and password in plain text (not encrypted).

Configuring Password Encryption

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

By default, EclipseLink does not write passwords to and read passwords from the project.xml file unless you configure your project-level data source login accordingly. When you configure EclipseLink to write passwords and read passwords from the project.xml file, by default, it does so in encrypted form using JCE encryption.

You can implement your own encryption class and configure your session DatasourceLogin to use it.

Currently, the Workbench does not support specifying the encryption class used. To change the encryption class used, you must modify the login in Java.

For more information, see the following:

• Configuring Login Information at the Project Level
• Configuring User Name and Password

How to Configure Password Encryption Using Java

To configure a password encryption class, follow this procedure:

1. Create your encryption class.
   Your encryption class must implement the org.eclipse.persistence.internal.security.Securable interface, as this example shows.
   
   Custom Encryption Class Implementing Securable

   import org.eclipse.persistence.internal.security.Securable;
   
   public class MyEncryptor implements Securable {
   
       public String encryptPassword(String pswd) {
       ...
       }
   
       public String decryptPassword(String encryptedPswd) {
       ...
       }
   }
   

2. Create a session event listener class for the preLogin event that calls DatasourceLogin method setEncryptionClassName to configure your session with your encryption class.
   Use the SessionEventAdapter to simplify your session event listener, as this examle shows.
   
   Specifying a Custom Encryption Class in a Session Event Listener

   import org.eclipse.persistence.tools.sessionconfiguration.SessionEventAdapter;
   import org.eclipse.persistence.sessions.SessionEvent;
   import org.eclipse.persistence.sessions.Session;
   import org.eclipse.persistence.sessions.DatasourceLogin;
   
   public class MySessionEventListener extends SessionEventAdapter {
   
       public void preLogin(SessionEvent event) {
           Session session = event.getSession();
           DatasourceLogin login = session.getDatasourceLogin();
           login.setEncryptionClassName(MyEncryptor.class.getName());
       }
   }
   

3. Associate your session event listener class with your session. For more information, see Configuring Session Event Listeners.

Configuring External Connection Pooling

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

For Java EE applications, you typically use External Connection Pools provided by a JDBC driver or Java EE container. 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 EclipseLink 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 EclipseLink application to do the following:

• Integrate into a Java EE-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.

How to Configure External Connection Pooling Using Workbench

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

1. 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 Java EE container documentation.
2. Select a server or database session in the Navigator. Its properties appear in the Editor.
3. Click the Login tab. The Login tab appears.
4. Click the Connection subtab. The Connection subtab appears.
   Login Tab, Connection Subtab, External Connection Pooling Field, Database Driver
   
   
   Connection Tab, External Connection Pooling Field, Java EE Data Source
   
5. Select the External Connection Pooling option. For a database driver, external connection pooling is optional. For a Java EE data source, external connection pooling is mandatory.
   Specify if this login uses External Connection Pooling. For a database driver, external connection pooling is optional. For a Java EE data source, external connection pooling is mandatory.

How to Configure External Connection Pooling Using Java

To configure the use of an external connection pool in Java, do the following:

1. Configure the 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 Java EE container documentation.
2. Configure the DatasourceLogin to specify the data source and to use an external connection pool by using the useExternalConnectionPooling method.

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 How to Optimize JDBC Driver Properties). Add these properties to the DatasourceLogin so that EclipseLink 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 the Workbench or DatabaseLogin method setPassword. For more information on configuring a password, see Configuring User Name and Password.

When using Workbench, you can only set character values, which EclipseLink returns as String objects (see How to Configure Properties Using Workbench).

When using Java, you can set any Object value (see How to Configure Properties Using Java).

How to Configure Properties Using Workbench

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

1. Select a server or database session in the Navigator. Its properties appear in the Editor.
2. Click the Login tab. The Login tab appears.
3. If necessary, enable support for properties:
   • for relational sessions, you must first enable advanced option Use Properties (see Configuring Advanced Options);
   • for EIS sessions, properties are always enabled.
4. Click the Properties subtab. The Properties subtab appears.
   Login Tab, Properties Subtab
   
5. You can add, edit, or remove properties using Add Property dialog box.
6. 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 EclipseLink retrieves the property value using the DatasourceLogin method getProperty.
Value	The value EclipseLink retrieves using the DatasourceLogin method getProperty passing in the corresponding property name. Using Workbench, you can set only character values that EclipseLink returns as String objects.

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

How to Configure Properties 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 EclipseLink uses instead of null when EclipseLink 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, EclipseLink uses it to translate in one direction only: when EclipseLink reads null from the data source, it converts this null to the specified type and value.

You can also use EclipseLink 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).

How to Configure a Default Null Value at the Login Level 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, "");

---

Copyright Statement