Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "Configuring a Data Source Login (ELUG)"

m (Configuring Properties)
m
 
(22 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 +
[[Image:Elug draft icon.png]] '''For the latest EclipseLink documentation, please see http://www.eclipse.org/eclipselink/documentation/ '''
 +
 +
----
 
<div style="float:right;border:1px solid #000000;padding:5px">__TOC__
 
<div style="float:right;border:1px solid #000000;padding:5px">__TOC__
 
[[Special:Whatlinkshere/Configuring a Data Source Login (ELUG)|Related Topics]]</div>
 
[[Special:Whatlinkshere/Configuring a Data Source Login (ELUG)|Related Topics]]</div>
This section describes how to configure EclipseLink data source logins.
+
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.
 
+
[[#Table 93-1|Configuring EclipseLink Data Source Logins]] lists the types of EclipseLink 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.
+
  
  
 
<span id="Table 93-1"></span>
 
<span id="Table 93-1"></span>
''''' Configuring EclipseLink Data Source Logins'''''
+
'''''Configuring EclipseLink Data Source Logins'''''
  
 
{| class="HRuleFormal" dir="ltr" title="Configuring EclipseLink Data Source Logins" summary="This table provides a cross-reference to additional datasource login configuration options for each type of datasource login." width="100%" border="1" frame="hsides" rules="rows" cellpadding="3" frame="hsides" rules="rows"
 
{| class="HRuleFormal" dir="ltr" title="Configuring EclipseLink Data Source Logins" summary="This table provides a cross-reference to additional datasource login configuration options for each type of datasource login." width="100%" border="1" frame="hsides" rules="rows" cellpadding="3" frame="hsides" rules="rows"
Line 25: Line 26:
 
|}
 
|}
  
 
 
[[#Table 93-2|Common Data Source Login Options]] lists the configurable options shared by two or more EclipseLink data source login types.
 
  
 
When using the <tt>sessions.xml</tt> file to configure login information, EclipseLink will override any login information in the <tt>project.xml</tt> and instead use the information from the <tt>sessions.xml</tt> configuration.
 
When using the <tt>sessions.xml</tt> file to configure login information, EclipseLink will override any login information in the <tt>project.xml</tt> and instead use the information from the <tt>sessions.xml</tt> configuration.
Line 40: Line 38:
 
==Configuring Common Data Source Login Options==
 
==Configuring Common Data Source Login Options==
  
[[#Table 93-2|Common Data Source Login Options]] 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 [[Introduction%20to%20Data%20Access%20(ELUG)#Data Source Login Types|Data Source Login Types]]), as shown in [[#Table 93-1| Configuring EclipseLink Data Source Logins]]
+
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 [[Introduction%20to%20Data%20Access%20(ELUG)#Data Source Login Types|Data Source Login Types]]), as shown in the [[#Table 93-1| Configuring EclipseLink Data Source Logins]] table.
  
  
Line 53: Line 51:
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r2c1-t3" headers="r1c1-t3" align="left" |
 
| id="r2c1-t3" headers="r1c1-t3" align="left" |
User name and password (see [[#Configuring User Name and Password|Configuring User Name and Password]])
+
[[#Configuring User Name and Password|User name and password]]
 
| headers="r2c1-t3 r1c2-t3" align="left" |
 
| headers="r2c1-t3 r1c2-t3" align="left" |
 
[[Image:support.gif|Supported]]
 
[[Image:support.gif|Supported]]
Line 60: Line 58:
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r3c1-t3" headers="r1c1-t3" align="left" |
 
| id="r3c1-t3" headers="r1c1-t3" align="left" |
Password encryption (see [[#Configuring Password Encryption|Configuring Password Encryption]])
+
[[#Configuring Password Encryption|Password encryption]]
 
| headers="r3c1-t3 r1c2-t3" align="left" |
 
| headers="r3c1-t3 r1c2-t3" align="left" |
 
[[Image:unsupport.gif|Unsupported]]
 
[[Image:unsupport.gif|Unsupported]]
Line 67: Line 65:
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r4c1-t3" headers="r1c1-t3" align="left" |
 
| id="r4c1-t3" headers="r1c1-t3" align="left" |
External connection pooling (see [[#Configuring External Connection Pooling|Configuring External Connection Pooling]])
+
[[#Configuring External Connection Pooling|Configuring external connection pooling]]
 
| headers="r4c1-t3 r1c2-t3" align="left" |
 
| headers="r4c1-t3 r1c2-t3" align="left" |
 
[[Image:support.gif|Supported]]
 
[[Image:support.gif|Supported]]
Line 74: Line 72:
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r5c1-t3" headers="r1c1-t3" align="left" |
 
| id="r5c1-t3" headers="r1c1-t3" align="left" |
Properties (see [[#Configuring Properties|Configuring Properties]])
+
[[#Configuring Properties|Configuring properties]]
 
| headers="r5c1-t3 r1c2-t3" align="left" |
 
| headers="r5c1-t3 r1c2-t3" align="left" |
 
[[Image:support.gif|Supported]]
 
[[Image:support.gif|Supported]]
Line 81: Line 79:
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r6c1-t3" headers="r1c1-t3" align="left" |
 
| id="r6c1-t3" headers="r1c1-t3" align="left" |
Default null value (see [[#Configuring a Default Null Value at the Login Level|Configuring a Default Null Value at the Login Level]])
+
[[#Configuring a Default Null Value at the Login Level|Default null value at the login level]]
 
| headers="r6c1-t3 r1c2-t3" align="left" |
 
| headers="r6c1-t3 r1c2-t3" align="left" |
 
[[Image:unsupport.gif|Unsupported]]
 
[[Image:unsupport.gif|Unsupported]]
Line 87: Line 85:
 
[[Image:support.gif|Supported]]
 
[[Image:support.gif|Supported]]
 
|}
 
|}
 +
 +
  
 
==Configuring User Name and Password==
 
==Configuring User Name and Password==
Line 94: Line 94:
 
We recommend that you do not save the password with a deployment login.
 
We recommend that you do not save the password with a deployment login.
  
If you specify a password, using a EclipseLink tool or Java, enter the plain text (not encrypted) value. EclipseLink will encrypt the password using JCE encryption.
+
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 <tt>sessions.xml</tt> file in encrypted form using JCE encryption.
 
By default, EclipseLink writes passwords to and read passwords from the <tt>sessions.xml</tt> file in encrypted form using JCE encryption.
Line 104: Line 104:
 
* [[Configuring%20a%20Relational%20Project%20(ELUG)#Configuring Login Information at the Project Level|Configuring Login Information at the Project Level]]
 
* [[Configuring%20a%20Relational%20Project%20(ELUG)#Configuring Login Information at the Project Level|Configuring Login Information at the Project Level]]
 
* [[#Configuring Password Encryption|Configuring Password Encryption]]
 
* [[#Configuring Password Encryption|Configuring Password Encryption]]
 
  
  
Line 115: Line 114:
 
# Click the '''Connection''' subtab. The Connection subtab appears.<br><span id="Figure 93-1"></span>''''' Login Tab, Connection Subtab, User Name and Password Fields'''''<br>[[Image:unpwlog.gif|Login Tab, Connection Subtab, User Name and Password Fields]]
 
# Click the '''Connection''' subtab. The Connection subtab appears.<br><span id="Figure 93-1"></span>''''' Login Tab, Connection Subtab, User Name and Password Fields'''''<br>[[Image:unpwlog.gif|Login Tab, Connection Subtab, User Name and Password Fields]]
 
# Enter a user name and password in plain text (not encrypted).
 
# Enter a user name and password in plain text (not encrypted).
 +
 +
  
 
==Configuring Password Encryption==
 
==Configuring Password Encryption==
Line 130: Line 131:
 
* [[Configuring%20a%20Relational%20Project%20(ELUG)#Configuring Login Information at the Project Level|Configuring Login Information at the Project Level]]
 
* [[Configuring%20a%20Relational%20Project%20(ELUG)#Configuring Login Information at the Project Level|Configuring Login Information at the Project Level]]
 
* [[#Configuring User Name and Password|Configuring User Name and Password]]
 
* [[#Configuring User Name and Password|Configuring User Name and Password]]
 
  
  
 
===How to Configure Password Encryption Using Java===
 
===How to Configure Password Encryption Using Java===
  
To configure a password encryption class, you use Java.
+
To configure a password encryption class, follow this procedure:
  
 
 
====To Configure Password Encryption Using Java====
 
 
<ol>
 
<ol>
<li> Create your encryption class.Your encryption class must implement the <tt>org.eclipse.persistence.internal.security.Securable</tt> interface, as this example shows.
+
<li> Create your encryption class.<br>Your encryption class must implement the <tt>org.eclipse.persistence.internal.security.Securable</tt> interface, as this example shows.<br><br>
 
<span id="Example 93-1"></span>
 
<span id="Example 93-1"></span>
 +
 
''''' Custom Encryption Class Implementing Securable'''''  
 
''''' Custom Encryption Class Implementing Securable'''''  
 
<div class="pre">
 
<div class="pre">
 
  import org.eclipse.persistence.internal.security.Securable;
 
  import org.eclipse.persistence.internal.security.Securable;
 
   
 
   
  public class MyEncryptor implements Securable
+
  public class MyEncryptor implements Securable {
  {
+
   
     public String encryptPassword(String pswd)
+
     public String encryptPassword(String pswd) {
    {
+
 
     ...
 
     ...
 
     }
 
     }
 
   
 
   
     public String decryptPassword(String encryptedPswd)
+
     public String decryptPassword(String encryptedPswd) {
    {
+
 
     ...
 
     ...
 
     }
 
     }
 
 
  }
 
  }
 
</div>
 
</div>
 
</li>
 
</li>
<li> Create a session event listener class for the <tt>preLogin</tt> event that calls <tt>DatasourceLogin</tt> method <tt>setEncryptionClassName</tt> to configure your session with your encryption class.Use the <tt>SessionEventAdapter</tt> to simplify your session event listener, as this examle shows.
+
<li> Create a session event listener class for the <tt>preLogin</tt> event that calls <tt>DatasourceLogin</tt> method <tt>setEncryptionClassName</tt> to configure your session with your encryption class.<br>Use the <tt>SessionEventAdapter</tt> to simplify your session event listener, as this examle shows.<br><br>
 
<span id="Example 93-2"></span>
 
<span id="Example 93-2"></span>
 +
 +
 
''''' Specifying a Custom Encryption Class in a Session Event Listener'''''  
 
''''' Specifying a Custom Encryption Class in a Session Event Listener'''''  
 
<div class="pre">
 
<div class="pre">
Line 171: Line 168:
 
  import org.eclipse.persistence.sessions.DatasourceLogin;
 
  import org.eclipse.persistence.sessions.DatasourceLogin;
 
   
 
   
  public class MySessionEventListener extends SessionEventAdapter
+
  public class MySessionEventListener extends SessionEventAdapter {
  {
+
   
     public void preLogin(SessionEvent event)  
+
     public void preLogin(SessionEvent event) {
    {
+
 
         Session session = event.getSession();
 
         Session session = event.getSession();
 
         DatasourceLogin login = session.getDatasourceLogin();
 
         DatasourceLogin login = session.getDatasourceLogin();
Line 182: Line 178:
 
</div>
 
</div>
 
</li>
 
</li>
<li> Associate your session event listener class with your session.For more information, see [[Configuring%20a%20Session%20(ELUG)#Configuring Session Event Listeners|Configuring Session Event Listeners]].
+
<li> Associate your session event listener class with your session. For more information, see [[Configuring%20a%20Session%20(ELUG)#Configuring Session Event Listeners|Configuring Session Event Listeners]].
 
</li>
 
</li>
 
</ol>
 
</ol>
 +
 +
  
 
==Configuring External Connection Pooling==
 
==Configuring External Connection Pooling==
  
For non-Java EE applications, you typically use internal connection pools provided by EclipseLink (see [[Introduction%20to%20Data%20Access%20(ELUG)#Internal Connection Pools|Internal Connection Pools]]). 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 non-Java EE applications, you typically use [[Introduction%20to%20Data%20Access%20(ELUG)#Internal Connection Pools|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 (see [[Introduction%20to%20Data%20Access%20(ELUG)#External Connection Pools|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.
+
For Java EE applications, you typically use [[Introduction%20to%20Data%20Access%20(ELUG)#External Connection Pools|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 [[Using%20Advanced%20Unit%20of%20Work%20API%20(ELUG)#Integrating the Unit of Work with an External Transaction Service|Integrating the Unit of Work with an External Transaction Service]]).
 
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 [[Using%20Advanced%20Unit%20of%20Work%20API%20(ELUG)#Integrating the Unit of Work with an External Transaction Service|Integrating the Unit of Work with an External Transaction Service]]).
Line 202: Line 200:
  
 
For more information about connection pools, see [[Introduction%20to%20Data%20Access%20(ELUG)#Connection Pools|Connection Pools]].
 
For more information about connection pools, see [[Introduction%20to%20Data%20Access%20(ELUG)#Connection Pools|Connection Pools]].
 
  
  
Line 209: Line 206:
 
To specify if the session login uses external connection pooling, use this procedure:
 
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%20a%20Session%20(ELUG)#Configuring the Server Platform|Configuring the Server Platform]]), be sure to configure a JTA-enabled data source.For more information, see your Java EE container documentation.
+
# Configure a data source on the application server. <br>If you are using the external connection pool with an external transaction controller (see [[Configuring%20a%20Session%20(ELUG)#Configuring the Server Platform|Configuring the Server Platform]]), be sure to configure a JTA-enabled data source. <br>For more information, see your Java EE container documentation.
 
# Select a server or database session in the '''Navigator'''. Its properties appear in the Editor.
 
# 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 '''Login''' tab. The Login tab appears.
# Click the '''Connection''' subtab. The Connection subtab appears.<br>'''''Login Tab, Connection Subtab, External Connection Pooling Field, Database Driver'''''<br>[[Image:ecpdblog.gif|Login Tab, Connection Subtab, External Connection Pooling Field, Database Driver]]<br>''''' Connection Tab, External Connection Pooling Field, Java EE Data Source'''''<br>[[Image:ecpj2log.gif|Connection Tab, External Connection Pooling Field, Java EE Data Source]]
+
# Click the '''Connection''' subtab. The Connection subtab appears.<br>'''''Login Tab, Connection Subtab, External Connection Pooling Field, Database Driver'''''<br>[[Image:ecpdblog.gif|Login Tab, Connection Subtab, External Connection Pooling Field, Database Driver]]<br><br>''''' Connection Tab, External Connection Pooling Field, Java EE Data Source'''''<br>[[Image:ecpj2log.gif|Connection Tab, External Connection Pooling Field, Java EE Data Source]]
 
# 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.<br>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.
 
# 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.<br>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===
 
===How to Configure External Connection Pooling Using Java===
Line 219: Line 217:
 
To configure the use of an external connection pool in Java, do the following:
 
To configure the use of an external connection pool in Java, do the following:
  
# Configure the data source on the application server.If you are using the external connection pool with an external transaction controller (see [[Configuring%20a%20Session%20(ELUG)#Configuring the Server Platform|Configuring the Server Platform]]), be sure to configure a JTA-enabled data source.For more information, see your Java EE container documentation.
+
# Configure the data source on the application server. <br>If you are using the external connection pool with an external transaction controller (see [[Configuring%20a%20Session%20(ELUG)#Configuring the Server Platform|Configuring the Server Platform]]), be sure to configure a JTA-enabled data source. <br>For more information, see your Java EE container documentation.
# Configure the <tt>Login</tt> to specify the data source and to use an external connection pool by using the <tt>shouldUseExternalConnectionPooling</tt> method.
+
# Configure the <tt>DatasourceLogin</tt> to specify the data source and to use an external connection pool by using the <tt>useExternalConnectionPooling</tt> method.
  
 
==Configuring Properties==
 
==Configuring Properties==
Line 229: Line 227:
  
 
For EIS sessions, properties are always enabled.
 
For EIS sessions, properties are always enabled.
 +
  
 
{| class="Note oac_no_warn" width="80%" border="1" frame="hsides" rules="groups" cellpadding="3" frame="hsides" rules="groups"
 
{| class="Note oac_no_warn" width="80%" border="1" frame="hsides" rules="groups" cellpadding="3" frame="hsides" rules="groups"
Line 234: Line 233:
 
'''Note:''' Do not set a password as a property. Always use the Workbench or <tt>DatabaseLogin</tt> method <tt>setPassword</tt>. For more information on configuring a password, see [[#Configuring User Name and Password|Configuring User Name and Password]].
 
'''Note:''' Do not set a password as a property. Always use the Workbench or <tt>DatabaseLogin</tt> method <tt>setPassword</tt>. For more information on configuring a password, see [[#Configuring User Name and Password|Configuring User Name and Password]].
 
|}
 
|}
 
  
  
Line 240: Line 238:
  
 
When using Java, you can set any <tt>Object</tt> value (see [[#How to Configure Properties Using Java|How to Configure Properties Using Java]]).
 
When using Java, you can set any <tt>Object</tt> value (see [[#How to Configure Properties Using Java|How to Configure Properties Using Java]]).
 
  
  
Line 257: Line 254:
  
 
Use the following information to add or edit a login property on the Add Property dialog box:
 
Use the following information to add or edit a login property on the Add Property dialog box:
 
  
  
Line 272: Line 268:
 
The value EclipseLink retrieves using the <tt>DatasourceLogin</tt> method <tt>getProperty</tt> passing in the corresponding property name. Using Workbench, you can set only character values that EclipseLink returns as <tt>String</tt> objects.
 
The value EclipseLink retrieves using the <tt>DatasourceLogin</tt> method <tt>getProperty</tt> passing in the corresponding property name. Using Workbench, you can set only character values that EclipseLink returns as <tt>String</tt> objects.
 
|}
 
|}
 
  
  
Line 278: Line 273:
  
  
 +
===How to Configure Properties Using Java===
  
 +
Using Java, you can set any <tt>Object</tt> value using <tt>DatasourceLogin</tt> method <tt>setProperty</tt>. To remove a property, use <tt>DatasourceLogin</tt> method <tt>removeProperty</tt>.
  
  
===How to Configure Properties Using Java===
 
 
Using Java, you can set any <tt>Object</tt> value using <tt>DatasourceLogin</tt> method <tt>setProperty</tt>. To remove a property, use <tt>DatasourceLogin</tt> method <tt>removeProperty</tt>.
 
  
 
==Configuring a Default Null Value at the Login Level==
 
==Configuring a Default Null Value at the Login Level==
Line 291: Line 285:
 
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 <tt>null</tt> from the data source, it converts this <tt>null</tt> to the specified type and value.
 
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 <tt>null</tt> from the data source, it converts this <tt>null</tt> to the specified type and value.
  
You can also use EclipseLink to set a default null value on a per-mapping basis (see [Configuring%20a%20Mapping%20(ELUG)#Configuring a Default Null Value at the Mapping Level]).
+
You can also use EclipseLink to set a default null value on a per-mapping basis (see [[Configuring%20a%20Mapping%20(ELUG)#Configuring a Default Null Value at the Mapping Level|Configuring a Default Null Value at the Mapping Level]]).
 
+
  
  
 
{| class="Note oac_no_warn" width="80%" border="1" frame="hsides" rules="groups" cellpadding="3" frame="hsides" rules="groups"
 
{| class="Note oac_no_warn" width="80%" border="1" frame="hsides" rules="groups" cellpadding="3" frame="hsides" rules="groups"
 
| align="left" |
 
| align="left" |
''''''Note'''<nowiki>:</nowiki>''' A default null value must be an <tt>Object</tt>. To specify a primitive value (such as <tt>int</tt>), you must use the corresponding <tt>Object</tt> wrapper (such as <tt>Integer</tt>).
+
'''Note'''<nowiki>:</nowiki> A default null value must be an <tt>Object</tt>. To specify a primitive value (such as <tt>int</tt>), you must use the corresponding <tt>Object</tt> wrapper (such as <tt>Integer</tt>).
 
|}
 
|}
 
  
  
Line 307: Line 299:
  
 
For example:
 
For example:
 
 
 
 
  '''// Defaults all null String values read from the database to empty String'''
 
  '''// Defaults all null String values read from the database to empty String'''
 
  session.getLogin().setDefaultNullValue(String.class, "");
 
  session.getLogin().setDefaultNullValue(String.class, "");
Line 321: Line 310:
  
 
[[Category: EclipseLink User's Guide]]
 
[[Category: EclipseLink User's Guide]]
[[Category: Draft]]
+
[[Category: Release 1]]
 
[[Category: Task]]
 
[[Category: Task]]

Latest revision as of 11:14, 23 July 2012

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


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:


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

Supported

Supported

Password encryption

Unsupported

Supported

Configuring external connection pooling

Supported

Supported

Configuring properties

Supported

Supported

Default null value at the login level

Unsupported

Supported


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:


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
    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:


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
    Login Tab, Connection Subtab, External Connection Pooling Field, Database Driver

    Connection Tab, External Connection Pooling Field, Java EE Data Source
    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
    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

Copyright © Eclipse Foundation, Inc. All Rights Reserved.