Jump to: navigation, search

Difference between revisions of "Configuring a Session (ELUG)"

m (Configuring a Performance Profiler)
m
 
(44 intermediate revisions by 6 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 Session (ELUG)|Related topics]]</div>
 
[[Special:Whatlinkshere/Configuring a Session (ELUG)|Related topics]]</div>
 
This section describes how to configure EclipseLink sessions.
 
  
 
This table lists the types of EclipseLink sessions that you can configure and provides a cross-reference to the type-specific chapter that lists the configurable options supported by that type.
 
This table lists the types of EclipseLink sessions that you can configure and provides a cross-reference to the type-specific chapter that lists the configurable options supported by that type.
Line 8: Line 9:
  
 
<span id="Table 85-1"></span>
 
<span id="Table 85-1"></span>
''''' Configuring EclipseLink Sessions'''''
 
 
 
{| class="HRuleFormal" dir="ltr" title="Configuring EclipseLink Sessions" summary="This table provides a cross-reference to additional session configuration options." width="100%" border="1" frame="hsides" rules="rows" cellpadding="3" frame="hsides" rules="rows"
 
{| class="HRuleFormal" dir="ltr" title="Configuring EclipseLink Sessions" summary="This table provides a cross-reference to additional session configuration options." width="100%" border="1" frame="hsides" rules="rows" cellpadding="3" frame="hsides" rules="rows"
 
|- align="left" valign="top"
 
|- align="left" valign="top"
Line 46: Line 45:
 
|}
 
|}
  
<br>
 
 
[[#Table 85-2| Configurable Options for Session]] lists the configurable options shared by two or more EclipseLink sessions types.
 
  
 
For more information, see the following:
 
For more information, see the following:
Line 57: Line 53:
  
 
==Configuring Common Session Options==
 
==Configuring Common Session Options==
 
+
This table lists the configurable options shared by two or more EclipseLink session types. In addition to the configurable options described here, you must also configure the options described for the specific [[Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Session Types|Session Types]], as shown in The [[#Table 85-1|Configuring EclipseLink Sessions]] table.
[[#Table 85-2|Configurable Options for Session]] lists the configurable options shared by two or more EclipseLink session types. In addition to the configurable options described here, you must also configure the options described for the specific [[Introduction%20to%20EclipseLink%20Sessions%20(ELUG)|Session Types]], as shown in [[#Table 85-1|Configuring EclipseLink Sessions]]
+
  
  
 
<span id="Table 85-2"></span>
 
<span id="Table 85-2"></span>
''''' Configurable Options for Session'''''
+
{| class="RuleFormalMax" dir="ltr" title="Configurable Options for Session" summary="This table lists the configurable options common to Session and categorizes them as Basic and Advanced and indicates if the option can be configured with the Workbench, Java, or both." width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
 
+
{| class="RuleFormalMax" dir="ltr" title="Configurable Options for Session" summary="This table lists the configurable options common to Session and categorizes them as Basic and Advanced and indicates if the option can be configured with the TopLink Workbench, Java, or both." width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
+
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
! id="r1c1-t3" align="left" valign="bottom" | '''Option to Configure'''
 
! id="r1c1-t3" align="left" valign="bottom" | '''Option to Configure'''
Line 161: Line 154:
 
[[Image:support.gif|Supported]]<br>
 
[[Image:support.gif|Supported]]<br>
 
|}
 
|}
 
<br>
 
  
  
Line 174: Line 165:
  
 
<span id="Table 85-3"></span>
 
<span id="Table 85-3"></span>
''''' Session Support for Primary Mapping Project'''''
 
  
 
{| class="RuleFormal" dir="ltr" title="Session Support for Primary Mapping Project" summary="This table summarizes which sessions support primary mapping project configuration." width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
 
{| class="RuleFormal" dir="ltr" title="Session Support for Primary Mapping Project" summary="This table summarizes which sessions support primary mapping project configuration." width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
Line 204: Line 194:
 
|}
 
|}
  
<br>
 
  
 
Using the Workbench, you can export your mapping metadata as either a deployment XML file or as a Java class. Consequently, in a session, you can specify the mapping project as an XML file or as a Java class.
 
Using the Workbench, you can export your mapping metadata as either a deployment XML file or as a Java class. Consequently, in a session, you can specify the mapping project as an XML file or as a Java class.
  
If you export your mapping metadata as a Java class, you must compile it and add it to the session configuration classpath (see [[Creating%20a%20Session%20(ELUG)#Configuring a Sessions Configuration|Configuring a Sessions Configuration]]) before adding it to a session.
+
If you export your mapping metadata as a Java class, you must compile it and [[Creating%20a%20Session%20(ELUG)#Configuring a Sessions Configuration|add it to the session configuration classpath]] before adding it to a session.
  
<br>
 
  
 
{| 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:''' When specifying the mapping project using XML, you can specify the Java resource path. In most applications, the <tt>sessions.xml</tt> and <tt>project.xml</tt> files are deployed inside the JAR file, and the project XML path is specified as a Java resource path. When specifying the Java resource path, ensure that you are using the forward slash character ( / ) for directories, not the back slash ( \ ). For example, <tt>com/myapp/mypersistence/my-project.xml</tt>, or <tt>META-INF/my-project.xml</tt>.
+
'''Note:''' When specifying the mapping project using XML, you can specify the Java resource path. In most applications, the <tt>sessions.xml</tt> and <tt>project.xml</tt> files are deployed inside the JAR file, and the project XML path is specified as a Java resource path. When specifying the Java resource path, ensure that you are using the forward slash character ( / ) for directories, not the back slash ( \ ).  
 +
 
 +
For example, <tt>com/myapp/mypersistence/my-project.xml</tt>, or <tt>META-INF/my-project.xml</tt>.
 
|}
 
|}
  
<br>
 
  
 
See [[#Configuring Multiple Mapping Projects|Configuring Multiple Mapping Projects]] for information on configuring additional EclipseLink projects for the session.
 
See [[#Configuring Multiple Mapping Projects|Configuring Multiple Mapping Projects]] for information on configuring additional EclipseLink projects for the session.
 
  
  
 
===How to Configure a Primary Mapping Project Using Workbench===
 
===How to Configure a Primary Mapping Project Using Workbench===
 
 
To specify the primary EclipseLink project metadata for your session, use this procedure:
 
To specify the primary EclipseLink project metadata for your session, use this procedure:
 
 
# 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 '''General''' tab. The General tab appears.
 
# Click the '''General''' tab. The General tab appears.
Line 232: Line 218:
 
# Select the following options:
 
# Select the following options:
 
#* Click '''Edit''' to define the primary project. The Edit PrimaryProject dialog box appears.  
 
#* Click '''Edit''' to define the primary project. The Edit PrimaryProject dialog box appears.  
#* Use the '''Multiple Projects''' option to add additional projects to the session. See [[#Configuring Multiple Mapping Projects|Configuring Multiple Mapping Projects]] for more information.<br><span id="Figure 85-2"></span>''''' Edit Primary Project Dialog Box'''''<br>[[Image:editprj.gif|Edit Primary Project Dialog Box]]<br><br>
+
#* Use the '''Multiple Projects''' option to [[#Configuring Multiple Mapping Projects|add additional projects to the session]].<br><span id="Figure 85-2"></span>''''' Edit Primary Project Dialog Box'''''<br>[[Image:editprj.gif|Edit Primary Project Dialog Box]]<br><br>
 
# Complete each field on the Edit Primary Project dialog box.
 
# Complete each field on the Edit Primary Project dialog box.
  
Line 247: Line 233:
 
| headers="r3c1-t6 r1c2-t6" align="left" | Select '''Class''' to add a mapping project as a ''compiled'' Java class file. Click '''Browse''' to select the file.
 
| headers="r3c1-t6 r1c2-t6" align="left" | Select '''Class''' to add a mapping project as a ''compiled'' Java class file. Click '''Browse''' to select the file.
 
|}
 
|}
 
<br>
 
 
 
  
  
Line 256: Line 238:
  
 
Using Java, you can register descriptors with a session using the following API:
 
Using Java, you can register descriptors with a session using the following API:
 
+
* <tt>Project</tt> API – Read your <tt>project.xml</tt> file (or instantiate your project class) and create your session using <tt>Project</tt> method <tt>createServerSession</tt> or <tt>createDatabaseSession</tt>.
* <tt>Project</tt> API–Read your <tt>project.xml</tt> file (or instantiate your project class) and create your session using <tt>Project</tt> method <tt>createServerSession</tt> or <tt>createDatabaseSession</tt>.
+
* <tt>Session</tt> API – Add a descriptor or set of descriptors to a session using the <tt>DatabaseSession</tt> API that the following table lists. Descriptors should be registered before login, but independent sets of descriptors can be added after login.
* <tt>Session</tt> API–Add a descriptor or set of descriptors to a session using the <tt>DatabaseSession</tt> API that the following table lists. Descriptors should be registered before login, but independent sets of descriptors can be added after login.
+
  
  
Line 284: Line 265:
 
Add an individual descriptor to the session.
 
Add an individual descriptor to the session.
 
|}
 
|}
 
<br>
 
  
  
Line 297: Line 276:
  
 
<span id="Table 85-5"></span>
 
<span id="Table 85-5"></span>
''''' Session Support for Session Login'''''
 
 
 
{| class="RuleFormal" dir="ltr" title="Session Support for Session Login" summary="This table summarizes which sessions support session login configuration." width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
 
{| class="RuleFormal" dir="ltr" title="Session Support for Session Login" summary="This table summarizes which sessions support session login configuration." width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
 
|- align="left" valign="top"
 
|- align="left" valign="top"
Line 329: Line 306:
  
 
For more information, see the following:
 
For more information, see the following:
 
 
* [[Introduction%20to%20Data%20Access%20(ELUG)#Data Source Login Types|Data Source Login Types]]
 
* [[Introduction%20to%20Data%20Access%20(ELUG)#Data Source Login Types|Data Source Login Types]]
 
* [[Configuring%20a%20Data%20Source%20Login%20(ELUG)|Configuring a Data Source Login]]
 
* [[Configuring%20a%20Data%20Source%20Login%20(ELUG)|Configuring a Data Source Login]]
 
 
  
  
  
 
==Configuring Logging==
 
==Configuring Logging==
 
 
Use the EclipseLink logging framework to record EclipseLink behavior to a log file or session console.
 
Use the EclipseLink logging framework to record EclipseLink behavior to a log file or session console.
  
Line 344: Line 317:
  
 
<span id="Table 85-6"></span>
 
<span id="Table 85-6"></span>
'''''Session Support for Logging'''''
 
  
 
{| class="FormalWideMax" dir="ltr" title="Session Support for Logging" summary="This table summarizes which sessions support logging configuration." width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
 
{| class="FormalWideMax" dir="ltr" title="Session Support for Logging" summary="This table summarizes which sessions support logging configuration." width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
Line 350: Line 322:
 
! id="r1c1-t9" align="left" valign="bottom" | '''Session'''
 
! id="r1c1-t9" align="left" valign="bottom" | '''Session'''
 
! id="r1c2-t9" align="left" valign="bottom" | '''[[#How to Configure Logging Using Workbench|Using the Workbench]]<br>'''
 
! id="r1c2-t9" align="left" valign="bottom" | '''[[#How to Configure Logging Using Workbench|Using the Workbench]]<br>'''
! id="r1c3-t9" align="left" valign="bottom" | '''[[#How to Configure Logging Using Session API in Java]]<br>'''
+
! id="r1c3-t9" align="left" valign="bottom" | '''[[#How to Configure Logging Using Session API in Java|Using Java]]<br>'''
! id="r1c4-t9" align="left" valign="bottom" | '''<br>'''
+
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r2c1-t9" headers="r1c1-t9" align="left" |
 
| id="r2c1-t9" headers="r1c1-t9" align="left" |
Line 358: Line 329:
 
[[Image:support.gif|Supported.]]<br>
 
[[Image:support.gif|Supported.]]<br>
 
| headers="r2c1-t9 r1c3-t9" align="left" |
 
| headers="r2c1-t9 r1c3-t9" align="left" |
[[Image:support.gif|Supported.]]<br>
 
| headers="r2c1-t9 r1c4-t9" align="left" |
 
 
[[Image:support.gif|Supported.]]<br>
 
[[Image:support.gif|Supported.]]<br>
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r3c1-t9" headers="r1c1-t9" align="left" |
 
| id="r3c1-t9" headers="r1c1-t9" align="left" |
[[Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Unit of Work Sessions#Unit of work sessions ]]
+
[[Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Unit of Work Sessions|Unit of work sessions ]]
 
| headers="r3c1-t9 r1c2-t9" align="left" |
 
| headers="r3c1-t9 r1c2-t9" align="left" |
 
[[Image:support.gif|Supported.]]<br>
 
[[Image:support.gif|Supported.]]<br>
 
| headers="r3c1-t9 r1c3-t9" align="left" |
 
| headers="r3c1-t9 r1c3-t9" align="left" |
[[Image:support.gif|Supported.]]<br>
 
| headers="r3c1-t9 r1c4-t9" align="left" |
 
 
[[Image:support.gif|Supported.]]<br>
 
[[Image:support.gif|Supported.]]<br>
 
|- align="left" valign="top"
 
|- align="left" valign="top"
Line 377: Line 344:
 
| headers="r4c1-t9 r1c3-t9" align="left" |
 
| headers="r4c1-t9 r1c3-t9" align="left" |
 
[[Image:support.gif|Supported.]]<br>
 
[[Image:support.gif|Supported.]]<br>
| headers="r4c1-t9 r1c4-t9" align="left" |
 
[[Image:unsupport.gif|Unsupported]]<br>
 
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r5c1-t9" headers="r1c1-t9" align="left" |
 
| id="r5c1-t9" headers="r1c1-t9" align="left" |
Line 386: Line 351:
 
| headers="r5c1-t9 r1c3-t9" align="left" |
 
| headers="r5c1-t9 r1c3-t9" align="left" |
 
[[Image:support.gif|Supported.]]<br>
 
[[Image:support.gif|Supported.]]<br>
| headers="r5c1-t9 r1c4-t9" align="left" |
 
[[Image:unsupport.gif|Unsupported]]<br>
 
 
|}
 
|}
  
<br><br>
 
  
 
{| 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> If the session belongs to a session broker, you must specify the logging information in the session broker–not in the session itself.
+
'''Note'''<nowiki>:</nowiki> If the session belongs to a session broker, you must specify the logging information in the session broker – not in the session itself.
 
|}
 
|}
  
<br>
 
  
By default, EclipseLink uses its own native logger. Alternatively, you can configure EclipseLink to use the <tt>java.util.logging</tt> package (see [[#How to Configure a Session to use the java.util.logging Package|How to Configure a Session to use the java.util.logging Package]]).
+
By default, EclipseLink uses its own native logger. Alternatively, you can configure EclipseLink to [[#How to Configure a Session to use the java.util.logging Package|use the <tt>java.util.logging</tt> package]].
  
 
For more information, see [[Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Logging|Logging]].
 
For more information, see [[Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Logging|Logging]].
 
  
  
 
===How to Configure Logging Using Workbench===
 
===How to Configure Logging Using Workbench===
 
 
To specify the logging information for a session, use this procedure:
 
To specify the logging information for a session, use this procedure:
 
 
# Select a database session in the '''Navigator'''. Its properties appear in the Editor.
 
# Select a database session in the '''Navigator'''. Its properties appear in the Editor.
 
# Click the '''Logging''' tab. The Logging tab appears.<br><span id="Figure 85-3"></span>''''' Logging Tab'''''<br>[[Image:seslog.gif|Logging Tab]]<br><br>
 
# Click the '''Logging''' tab. The Logging tab appears.<br><span id="Figure 85-3"></span>''''' Logging Tab'''''<br>[[Image:seslog.gif|Logging Tab]]<br><br>
Line 432: Line 390:
 
Select this option to use the EclipseLink logging framework. When selected, you can optionally configure the following options.
 
Select this option to use the EclipseLink logging framework. When selected, you can optionally configure the following options.
 
|- align="left" valign="top"
 
|- align="left" valign="top"
| id="r6c1-t11" headers="r1c1-t11" align="left" | '''Logging Level'''
+
| id="r6c1-t11" headers="r1c1-t11" align="left" |  
 +
:'''Logging Level'''
 
| headers="r6c1-t11 r1c2-t11" align="left" |
 
| headers="r6c1-t11 r1c2-t11" align="left" |
 
Define the amount of logging information to record (in ascending order of information):
 
Define the amount of logging information to record (in ascending order of information):
* '''Config'''–Log only login, JDBC connection, and database information.
+
* '''Config''' – Log only login, JDBC connection, and database information.
* '''Info''' (default)–Log the login/logout per sever session, with user name. After acquiring the session, detailed information is logged.
+
* '''Info''' (default) – Log the login/logout per sever session, with user name. After acquiring the session, detailed information is logged.
* '''Warning'''–Log exceptions that do not force EclipseLink to stop, including all exceptions not logged with '''Severe''' level. This does not include a stack trace.
+
* '''Warning''' – Log exceptions that do not force EclipseLink to stop, including all exceptions not logged with '''Severe''' level. This does not include a stack trace.
* '''Severe''' –Log exceptions indicating EclipseLink cannot continue, and any exceptions generated during login. This includes a stack trace.
+
* '''Severe''' – Log exceptions indicating EclipseLink cannot continue, and any exceptions generated during login. This includes a stack trace.
* '''Fine'''–Log SQL (including thread information).
+
* '''Fine''' – Log SQL (including thread information).
* '''Finer'''–Similar to warning. Includes stack trace.
+
* '''Finer''' – Similar to warning. Includes stack trace.
* '''Finest'''–Includes additional low-level information.
+
* '''Finest''' – Includes additional low-level information.
* '''All'''–Log everything.
+
* '''All''' – Log everything.
 
|- align="left" valign="top"
 
|- align="left" valign="top"
| id="r7c1-t11" headers="r1c1-t11" align="left" | '''Console'''
+
| id="r7c1-t11" headers="r1c1-t11" align="left" |  
 +
:'''Console'''
 
| headers="r7c1-t11 r1c2-t11" align="left" | Select this option to display logging information to the standard console output.
 
| headers="r7c1-t11 r1c2-t11" align="left" | Select this option to display logging information to the standard console output.
 
|- align="left" valign="top"
 
|- align="left" valign="top"
| id="r8c1-t11" headers="r1c1-t11" align="left" | '''File'''
+
| id="r8c1-t11" headers="r1c1-t11" align="left" |  
 +
:'''File'''
 
| headers="r8c1-t11 r1c2-t11" align="left" | Select this option to record logging information in a file. Click '''Browse''' to specify the name and location of the log file.
 
| headers="r8c1-t11 r1c2-t11" align="left" | Select this option to record logging information in a file. Click '''Browse''' to specify the name and location of the log file.
 
|- align="left" valign="top"
 
|- align="left" valign="top"
Line 453: Line 414:
 
| headers="r9c1-t11 r1c2-t11" align="left" | Select this option to override additional logging option defaults for '''Java''' and '''Standard''' logging only.
 
| headers="r9c1-t11 r1c2-t11" align="left" | Select this option to override additional logging option defaults for '''Java''' and '''Standard''' logging only.
 
|- align="left" valign="top"
 
|- align="left" valign="top"
| id="r10c1-t11" headers="r1c1-t11" align="left" | ''' Log Exception Stack Trace'''
+
| id="r10c1-t11" headers="r1c1-t11" align="left" |  
 +
:''' Log Exception Stack Trace'''
 
| headers="r10c1-t11 r1c2-t11" align="left" |
 
| headers="r10c1-t11 r1c2-t11" align="left" |
Select this option to include the stack trace with any exception written to the log. Default: For <tt>SEVERE</tt> messages, log stack trace. For <tt>WARNING</tt> messages, only log stack trace at log level <tt>FINER</tt> or lower.
+
Select this option to include the stack trace with any exception written to the log.  
 +
 
 +
Default: For <tt>SEVERE</tt> messages, log stack trace. For <tt>WARNING</tt> messages, only log stack trace at log level <tt>FINER</tt> or lower.
 
|- align="left" valign="top"
 
|- align="left" valign="top"
| id="r11c1-t11" headers="r1c1-t11" align="left" | ''' Print Connection'''
+
| id="r11c1-t11" headers="r1c1-t11" align="left" |  
 +
:''' Print Connection'''
 
| headers="r11c1-t11 r1c2-t11" align="left" |
 
| headers="r11c1-t11 r1c2-t11" align="left" |
Select this option to include the connection identifier in any connection related log messages. Default: Enabled for all message and log levels.
+
Select this option to include the connection identifier in any connection related log messages.
 +
 
 +
Default: Enabled for all message and log levels.
 
|- align="left" valign="top"
 
|- align="left" valign="top"
| id="r12c1-t11" headers="r1c1-t11" align="left" | ''' Print Date'''
+
| id="r12c1-t11" headers="r1c1-t11" align="left" |  
 +
:''' Print Date'''
 
| headers="r12c1-t11 r1c2-t11" align="left" |
 
| headers="r12c1-t11 r1c2-t11" align="left" |
Select this option to include the date and time at which the log message was generated. Default: Enabled for all message and log levels.
+
Select this option to include the date and time at which the log message was generated.  
 +
 
 +
Default: Enabled for all message and log levels.
 
|- align="left" valign="top"
 
|- align="left" valign="top"
| id="r13c1-t11" headers="r1c1-t11" align="left" | ''' Print Session'''
+
| id="r13c1-t11" headers="r1c1-t11" align="left" |  
 +
:''' Print Session'''
 
| headers="r13c1-t11 r1c2-t11" align="left" |
 
| headers="r13c1-t11 r1c2-t11" align="left" |
Select this option to include the session name in any session related log messages. Default: Enabled for all message and log levels.
+
Select this option to include the session name in any session related log messages.  
 +
 
 +
Default: Enabled for all message and log levels.
 
|- align="left" valign="top"
 
|- align="left" valign="top"
| id="r14c1-t11" headers="r1c1-t11" align="left" | ''' Print Thread'''
+
| id="r14c1-t11" headers="r1c1-t11" align="left" |  
 +
:''' Print Thread'''
 
| headers="r14c1-t11 r1c2-t11" align="left" |
 
| headers="r14c1-t11 r1c2-t11" align="left" |
Select this option to include the thread name in any thread related log messages. Default: Log only at log level <tt>FINER</tt> or lower.
+
Select this option to include the thread name in any thread related log messages.  
 +
 
 +
Default: Log only at log level <tt>FINER</tt> or lower.
 
|}
 
|}
  
  
 +
===How to Configure Logging Using Session API in Java===
  
<br>
 
 
===How to Configure Logging Using Session API in Java===
 
 
If you use EclipseLink native logging (the default), then at run time, you can configure logging options using <tt>org.eclipse.persistence.sessions.Session</tt> logging API.
 
If you use EclipseLink native logging (the default), then at run time, you can configure logging options using <tt>org.eclipse.persistence.sessions.Session</tt> logging API.
  
 
The <tt>Session</tt> interface defines the following logging methods:
 
The <tt>Session</tt> interface defines the following logging methods:
 
+
* <tt>setSessionLog</tt> – specify the type of logging to use (any implementor of <tt>org.eclipse.persistence.logging.SessionLog</tt>)
* <tt>setSessionLog</tt>–specify the type of logging to use (any implementor of <tt>org.eclipse.persistence.logging.SessionLog</tt>)
+
* <tt>dontLogMessages</tt> – disable logging
* <tt>dontLogMessages</tt>–disable logging
+
* <tt>setLog</tt> – specify the <tt>java.io.Writer</tt> to which the session logs messages
* <tt>setLog</tt>–specify the <tt>java.io.Writer</tt> to which the session logs messages
+
* <tt>setLogLevel</tt> – specify the level at which the session logs using <tt>org.eclipse.persistence.logging.SessionLog</tt> constants:
* <tt>setLogLevel</tt>– specify the level at which the session logs using <tt>org.eclipse.persistence.logging.SessionLog</tt> constants:
+
 
** <tt>OFF</tt>
 
** <tt>OFF</tt>
 
** <tt>SEVERE</tt>
 
** <tt>SEVERE</tt>
Line 503: Line 476:
 
''''' Configuring a Session to Use java.util.logging'''''
 
''''' Configuring a Session to Use java.util.logging'''''
 
  session.setSessionLog(new JavaLog());
 
  session.setSessionLog(new JavaLog());
 
  
  
Line 511: Line 483:
 
''''' Configuring a Session to Use Application Server Logging'''''
 
''''' Configuring a Session to Use Application Server Logging'''''
 
  session.setSessionLog(new OjdlLog());
 
  session.setSessionLog(new OjdlLog());
 
  
  
Line 519: Line 490:
 
''''' Configuring a Session to Log to a java.io.Writer'''''
 
''''' Configuring a Session to Log to a java.io.Writer'''''
 
  session.setLog(myWriter);
 
  session.setLog(myWriter);
 
  
  
Line 527: Line 497:
  
 
If you configure a session to use <tt>java.util.logging</tt> package, consider the following:
 
If you configure a session to use <tt>java.util.logging</tt> package, consider the following:
 
 
* [[#logging.properties|logging.properties]]
 
* [[#logging.properties|logging.properties]]
 
* [[#Formatters|Formatters]]
 
* [[#Formatters|Formatters]]
 
* [[#Namespace|Namespace]]
 
* [[#Namespace|Namespace]]
 
  
  
Line 540: Line 508:
 
<span id="Example 85-4"></span>
 
<span id="Example 85-4"></span>
 
''''' java.util.logging Configuration in logging.properties'''''
 
''''' java.util.logging Configuration in logging.properties'''''
 +
<source lang="java">
 
  handlers = java.util.logging.ConsoleHandler
 
  handlers = java.util.logging.ConsoleHandler
 
  java.util.logging.ConsoleHandler.level = CONFIG
 
  java.util.logging.ConsoleHandler.level = CONFIG
  java.util.logging.ConsoleHandler.formatter = org.eclipse.persistence.logging.EclipseLinkSimpleFormatter
+
  java.util.logging.ConsoleHandler.formatter = org.eclipse.persistence.logging.LogFormatter
 
  org.eclipse.persistence.LoggingSession.connection.level = CONFIG
 
  org.eclipse.persistence.LoggingSession.connection.level = CONFIG
 
+
</source>
 
+
  
 
For information about the types of formatters available, see [[#Formatters|Formatters]].
 
For information about the types of formatters available, see [[#Formatters|Formatters]].
 
 
  
 
====Formatters====
 
====Formatters====
EclipseLink provides two formatters: <tt>EclipseLinkSimpleFormatter</tt> and <tt>SimpleFormatter</tt>. They override the corresponding <tt>java.util.logging</tt> formatters and always log session and connection info when available. They also log thread and exception stack trace information at certain levels as specified by the logging level.
 
  
 +
EclipseLink provides two formatters: <tt>LogFormatter</tt> and <tt>XMLLogFormatter</tt>. They override the <tt>SimpleFormatter</tt> and <tt>XMLFormatter</tt> <tt>java.util.logging</tt> formatters and always log session and connection info when available. They also log thread and exception stack trace information at certain levels as specified by the logging level.
  
  
 
====Namespace====
 
====Namespace====
Namespace is supported for <tt>java.util.logging</tt>. This table lists the static constants defined in <tt>org.eclipse.persistence.logging.SessionLog</tt> for EclipseLink components and the corresponding strings in <tt>logging.properties</tt>.
+
 
 +
Namespace is supported for <tt>java.util.logging</tt>. This table lists the static constants defined in <tt>org.eclipse.persistence.sessions.SessionLog</tt> for EclipseLink components and the corresponding strings in <tt>logging.properties</tt>.
  
  
Line 622: Line 589:
 
| headers="r12c1-t12 r1c2-t12" align="left" |
 
| headers="r12c1-t12 r1c2-t12" align="left" |
 
<tt>org.eclipse.persistence.<sessionname>.ejb</tt>
 
<tt>org.eclipse.persistence.<sessionname>.ejb</tt>
 +
|- align="left" valign="top"
 +
| id="r12c1-t12" headers="r1c1-t12" align="left" |
 +
<tt>EJB_OR_METADATA</tt>
 +
| headers="r12c1-t12 r1c2-t12" align="left" |
 +
<tt>org.eclipse.persistence.<sessionname>.ejb_or_metadata</tt>
 +
|- align="left" valign="top"
 +
| id="r12c1-t12" headers="r1c1-t12" align="left" |
 +
<tt>WEAVER</tt>
 +
| headers="r12c1-t12 r1c2-t12" align="left" |
 +
<tt>org.eclipse.persistence.<sessionname>.weaver</tt>
 +
|- align="left" valign="top"
 +
| id="r12c1-t12" headers="r1c1-t12" align="left" |
 +
<tt>PROPERTIES</tt>
 +
| headers="r12c1-t12 r1c2-t12" align="left" |
 +
<tt>org.eclipse.persistence.<sessionname>.properties</tt>
 +
|- align="left" valign="top"
 +
| id="r12c1-t12" headers="r1c1-t12" align="left" |
 +
<tt>SERVER</tt>
 +
| headers="r12c1-t12 r1c2-t12" align="left" |
 +
<tt>org.eclipse.persistence.<sessionname>.server</tt>
 
|}
 
|}
  
 
<br>
 
<br>
  
In the <tt>logging.properties</tt> names listed in [[#Table 85-7|Logging Property FIle Names]], note that <tt><sessionname></tt> is the name of the session that the application is running in. For example, if the name of the session is <tt>MyApplication</tt>, then you would use <tt>org.eclipse.persistence.MyApplication.sql</tt> for the SQL logging property.
+
In the <tt>logging.properties</tt> names listed in the [[#Table 85-7|Logging Property FIle Names]] table, note that <tt><sessionname></tt> is the name of the session that the application is running in. For example, if the name of the session is <tt>MyApplication</tt>, then you would use <tt>org.eclipse.persistence.MyApplication.sql</tt> for the SQL logging property.
  
 
An application can also define its own namespace and write to it through the logging API, as long as the logger for that namespace is defined in the logging configuration. Otherwise messages are written to the parent logger, <tt>org.eclipse.persistence.<sessionname></tt>.
 
An application can also define its own namespace and write to it through the logging API, as long as the logger for that namespace is defined in the logging configuration. Otherwise messages are written to the parent logger, <tt>org.eclipse.persistence.<sessionname></tt>.
Line 633: Line 620:
  
 
==Configuring Multiple Mapping Projects==
 
==Configuring Multiple Mapping Projects==
 
+
Each session is associated with at least [[#Configuring a Primary Mapping Project|one mapping project]]. You can include additional EclipseLink mapping projects for a session.
Each session is associated with at least one mapping project (see [[#Configuring a Primary Mapping Project|Configuring a Primary Mapping Project]]). You can include additional EclipseLink mapping projects for a session.
+
  
 
This table summarizes which sessions support additional mapping project configuration.
 
This table summarizes which sessions support additional mapping project configuration.
  
 
<span id="Table 85-8"></span>
 
<span id="Table 85-8"></span>
''''' Session Support for Additional Mapping Project'''''
 
  
 
{| class="RuleFormal" dir="ltr" title="Session Support for Additional Mapping Project" summary="This table summarizes which sessions support additional mapping project configuration." width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
 
{| class="RuleFormal" dir="ltr" title="Session Support for Additional Mapping Project" summary="This table summarizes which sessions support additional mapping project configuration." width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
Line 655: Line 640:
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r3c1-t13" headers="r1c1-t13" align="left" |
 
| id="r3c1-t13" headers="r1c1-t13" align="left" |
[[Introduction%20to%20EclipseLink%20Sessions%20(ELUG)|Session Broker and Client Sessions]]
+
[[Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Session Broker and Client Sessions|Session Broker and Client Sessions]]
 
| headers="r3c1-t13 r1c2-t13" align="left" |
 
| headers="r3c1-t13 r1c2-t13" align="left" |
 
[[Image:support.gif|Supported.]]<br>
 
[[Image:support.gif|Supported.]]<br>
Line 668: Line 653:
 
[[Image:support.gif|Supported.]]<br>
 
[[Image:support.gif|Supported.]]<br>
 
|}
 
|}
 
<br>
 
 
  
  
Line 676: Line 658:
  
 
To specify additional EclipseLink projects for your session, use this procedure:
 
To specify additional EclipseLink projects for your session, use this procedure:
 
 
# 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 '''General''' tab. The General tab appears.
 
# Click the '''General''' tab. The General tab appears.
Line 683: Line 664:
 
# Click the '''Multiple Projects''' subtab.
 
# Click the '''Multiple Projects''' subtab.
 
#: <span id="Figure 85-5"><br>''''' General Tab, Multiple Projects Subtab'''''<br>[[Image:sesadv.gif|General Tab, Multiple Projects Subtab]]<br><br>
 
#: <span id="Figure 85-5"><br>''''' General Tab, Multiple Projects Subtab'''''<br>[[Image:sesadv.gif|General Tab, Multiple Projects Subtab]]<br><br>
#To add an additional mapping project to this session, click '''Add'''. For more information, see [[#Configuring a Primary Mapping Project]].
+
#To add an additional mapping project to this session, click '''Add'''. For more information, see [[#Configuring a Primary Mapping Project|Configuring a Primary Mapping Project]]. <br>To remove EclipseLink mapping projects, select the project file and click '''Remove'''.
#:To remove EclipseLink mapping projects, select the project file and click '''Remove'''.
+
 
+
 
+
 
+
  
  
Line 719: Line 696:
 
|}
 
|}
  
<br>
 
  
  
 
==Configuring a Performance Profiler==
 
==Configuring a Performance Profiler==
  
To successfully improve the performance of a EclipseLink application, you must measure performance before and after each optimization. EclipseLink provides a variety of built-in performance measuring features (known as profilers) that you can configure at the session level.
+
To successfully improve the performance of an EclipseLink application, you must measure performance before and after each optimization. EclipseLink provides a variety of built-in performance measuring features (known as profilers) that you can configure at the session level.
  
 
This table summarizes which sessions support performance profiler configuration.
 
This table summarizes which sessions support performance profiler configuration.
Line 730: Line 706:
  
 
<span id="Table 85-10"></span>
 
<span id="Table 85-10"></span>
''''' Session Support for Performance Profiler Configuration'''''
 
  
 
{| class="RuleFormal" dir="ltr" title="Session Support for Performance Profiler Configuration" summary="This table summarizes which sessions support profiler configuration." width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
 
{| class="RuleFormal" dir="ltr" title="Session Support for Performance Profiler Configuration" summary="This table summarizes which sessions support profiler configuration." width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
Line 760: Line 735:
 
|}
 
|}
  
<br>
 
  
 
EclipseLink provides the following profilers:
 
EclipseLink provides the following profilers:
* EclipseLink profiler: logs performance statistics for every executed query in a given session (see [[Optimizing%20the%20EclipseLink%20Application%20(ELUG)|Measuring EclipseLink Performance with the EclipseLink Profiler]])
+
* EclipseLink profiler: logs performance statistics for every executed query in a given session (see [[Optimizing%20the%20EclipseLink%20Application%20(ELUG)#Measuring EclipseLink Performance with the EclipseLink Profiler|Measuring EclipseLink Performance with the EclipseLink Profiler]])
* Oracle Dynamic Monitoring System (DMS): includes DMS instrumentation in essential objects to provide efficient Web browser based monitoring of run-time data in EclipseLink-enabled applications.
+
  
  
Line 771: Line 744:
  
 
To specify the type of profiler in a session, use this procedure:
 
To specify the type of profiler in a session, use this procedure:
 
 
# Select a session in the '''Navigator'''. Its properties appear in the Editor.
 
# Select a session in the '''Navigator'''. Its properties appear in the Editor.
 
# Click the '''Options''' tab. The Options tab appears.<br>''''' Options Tab, Profiler Options'''''<br>[[Image:sespro.gif|Options Tab, Profiler Options]]<br><br>
 
# Click the '''Options''' tab. The Options tab appears.<br>''''' Options Tab, Profiler Options'''''<br>[[Image:sespro.gif|Options Tab, Profiler Options]]<br><br>
Line 784: Line 756:
 
| id="r2c1-t16" headers="r1c1-t16" align="left" | '''No Profiler'''
 
| id="r2c1-t16" headers="r1c1-t16" align="left" | '''No Profiler'''
 
| headers="r2c1-t16 r1c2-t16" align="left" | Disable all profiling.
 
| headers="r2c1-t16 r1c2-t16" align="left" | Disable all profiling.
|- align="left" valign="top"
 
| id="r3c1-t16" headers="r1c1-t16" align="left" | '''DMS'''
 
| headers="r3c1-t16 r1c2-t16" align="left" | Enable Oracle Dynamic Monitoring (DMS) profiling. For more information, see the following:
 
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r4c1-t16" headers="r1c1-t16" align="left" | '''Standard (EclipseLink)'''
 
| id="r4c1-t16" headers="r1c1-t16" align="left" | '''Standard (EclipseLink)'''
Line 794: Line 763:
 
* [[Optimizing%20the%20EclipseLink%20Application%20(ELUG)#Measuring EclipseLink Performance with the EclipseLink Profiler|Measuring EclipseLink Performance with the EclipseLink Profiler]]
 
* [[Optimizing%20the%20EclipseLink%20Application%20(ELUG)#Measuring EclipseLink Performance with the EclipseLink Profiler|Measuring EclipseLink Performance with the EclipseLink Profiler]]
 
|}
 
|}
 
<br>
 
 
 
 
  
  
Line 807: Line 771:
  
 
<span id="Example 85-5"></span>
 
<span id="Example 85-5"></span>
''''' Configuring a Session with a EclipseLink Profiler'''''
+
''''' Configuring a Session with an EclipseLink Profiler'''''
 
  session.setProfiler(new PerformanceProfiler());
 
  session.setProfiler(new PerformanceProfiler());
 
  
  
 
To end a profiling session, use <tt>Session</tt> method <tt>clearProfiler</tt>.
 
To end a profiling session, use <tt>Session</tt> method <tt>clearProfiler</tt>.
 +
 +
  
 
==Configuring an Exception Handler==
 
==Configuring an Exception Handler==
Line 818: Line 783:
 
You can associate a single exception handling class with each session. This class must implement the <tt>org.eclipse.persistence.exceptions.ExceptionHandler</tt> interface.
 
You can associate a single exception handling class with each session. This class must implement the <tt>org.eclipse.persistence.exceptions.ExceptionHandler</tt> interface.
  
[[#Table 85-11] summarizes which sessions support exception handler configuration.
+
This table summarizes which sessions support exception handler configuration.
 
+
  
  
'''''Table 85-11 Session Support for Exception Handler Configuration'''''
+
<span id="Table 85-11"></span>
 +
''''' Session Support for Exception Handler Configuration'''''
  
 
{| class="RuleFormal" dir="ltr" title="Session Support for Exception Handler Configuration" summary="This table summarizes which sessions support exception handler configuration." width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
 
{| class="RuleFormal" dir="ltr" title="Session Support for Exception Handler Configuration" summary="This table summarizes which sessions support exception handler configuration." width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
Line 852: Line 817:
 
|}
 
|}
  
<br>
 
  
 
For an example exception handler implementation, see [[#How to Configure an Exception Handler Using Java|Using Java]].
 
For an example exception handler implementation, see [[#How to Configure an Exception Handler Using Java|Using Java]].
  
For more information, see [[Introduction%20to%20EclipseLink%20Sessions%20(ELUG)|Exception Handlers].
+
For more information, see [[Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Exception Handlers|Exception Handlers]].
 
+
  
  
Line 863: Line 826:
  
 
To specify the exception handler class in a session, use this procedure:
 
To specify the exception handler class in a session, use this procedure:
 
 
# Select a session in the '''Navigator'''. Its properties appear in the Editor.
 
# Select a session in the '''Navigator'''. Its properties appear in the Editor.
# Click the '''Options''' tab. The Options tab appears.<br>'''''Figure 85-7 Options Tab, Exception Handler Field'''''[[Image:sescust.gif|Description of Figure 85-7 follows]]<br>[img_text/sescust Description of "Figure 85-7 Options Tab, Exception Handler Field"]<br><br>
+
# Click the '''Options''' tab. The Options tab appears.<br>''''' Options Tab, Exception Handler Field'''''<br>[[Image:sescust.gif|Options Tab, Exception Handler Field]]<br><br>
# Complete the [topicid:session.options.exceptionHandler '''Exception Handler'''] field.
+
# Complete the '''Exception Handler''' field.
 
+
# Click '''Browse''' and select the exception handler class for this session.
Click '''Browse''' and select the exception handler class for this session.
+
 
+
  
  
 
===How to Configure an Exception Handler Using Java===
 
===How to Configure an Exception Handler Using Java===
  
[[#Example 85-6] shows an example exception handler implementation. In this implementation, the exception handler always tries to reestablish the connection if it has been reset by peer, but only retries a query if it is an instance of <tt>ReadQuery</tt>. Note that this exception handler either returns the result of the reexecuted <tt>ReadQuery</tt> or throws an exception.
+
This example shows an example exception handler implementation. In this implementation, the exception handler always tries to reestablish the connection if it has been reset by peer, but only retries a query if it is an instance of <tt>ReadQuery</tt>. Note that this exception handler either returns the result of the reexecuted <tt>ReadQuery</tt> or throws an exception.
 
+
  
  
'''''Example 85-6 Implementing an Exception Handler'''''
+
<span id="Example 85-6"></span>
 +
''''' Implementing an Exception Handler'''''
 +
<source lang="java">
 
  session.setExceptionHandler(
 
  session.setExceptionHandler(
 
   new ExceptionHandler() {
 
   new ExceptionHandler() {
Line 888: Line 849:
 
             dbex.getAccessor().reestablishConnection(dbex.getSession());
 
             dbex.getAccessor().reestablishConnection(dbex.getSession());
 
             if (dbex.getQuery() instanceof ReadQuery) {
 
             if (dbex.getQuery() instanceof ReadQuery) {
               return dbex.getSession().executeQuery(dbex.getQuery());
+
               return dbex.getSession().executeQuery(dbex.getQuery(), dbex.getQuery().getTranslationRow());
 
             }
 
             }
 
             throw exception;
 
             throw exception;
Line 897: Line 858:
 
   }
 
   }
 
  );
 
  );
 
+
</source>
 
<br>
 
<br>
  
Line 904: Line 865:
 
'''Note'''<nowiki>:</nowiki> Unhandled exceptions must be rethrown by the exception handler code.
 
'''Note'''<nowiki>:</nowiki> Unhandled exceptions must be rethrown by the exception handler code.
 
|}
 
|}
 
<br>
 
  
 
==Configuring a Session Customizer Class==
 
==Configuring a Session Customizer Class==
 +
A session customizer class is a Java class that implements the <tt> org.eclipse.persistence.internal.sessions.factories.SessionCustomizer</tt> interface and provides a default (zero-argument) constructor. You can use a session customizer to customize a session at run time on a loaded session before login occurs, similar to how you can use an [[Configuring%20a%20Descriptor%20(ELUG)#Configuring Amendment Methods|amendment method to customize a descriptor]]) For example, you can use a session customizer class to define and register session event listeners with the session event manager (see [[#Configuring Session Event Listeners|Configuring Session Event Listeners]]).
  
A session customizer class is a Java class that implements the <tt>org.eclipse.persistence.tools.sessionconfiguration.SessionCustomizer</tt> interface and provides a default (zero-argument) constructor. You can use a session customizer to customize a session at run time on a loaded session before login occurs, similar to how you can use an amendment method to customize a descriptor (see [[Configuring%20a%20Descriptor%20(ELUG)|Configuring Amendment Methods]]). For example, you can use a session customizer class to define and register session event listeners with the session event manager (see [[#Configuring Session Event Listeners]]).
+
This table summarizes which sessions support customizer class configuration.
 
+
[[#Table 85-12] summarizes which sessions support customizer class configuration.
+
 
+
  
  
'''''Table 85-12 Session Support for Customizer Class Configuration'''''
+
<span id="Table 85-12"></span>
 +
''''' Session Support for Customizer Class Configuration'''''
  
 
{| class="RuleFormal" dir="ltr" title="Session Support for Customizer Class Configuration" summary="This table summarizes which sessions support exception handler configuration." width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
 
{| class="RuleFormal" dir="ltr" title="Session Support for Customizer Class Configuration" summary="This table summarizes which sessions support exception handler configuration." width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
Line 945: Line 903:
 
|}
 
|}
  
<br>
 
 
For more information, see [[Introduction%20to%20EclipseLink%20Sessions%20(ELUG)|Session Customization]].
 
  
 +
For more information, see [[Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Session Customization|Session Customization]].
  
  
Line 954: Line 910:
  
 
To specify the session customizer class in a session, use this procedure:
 
To specify the session customizer class in a session, use this procedure:
 
 
# Select a session in the '''Navigator'''. Its properties appear in the Editor.
 
# Select a session in the '''Navigator'''. Its properties appear in the Editor.
# Click the '''Options''' tab. The Options tab appears.<br>'''''Figure 85-8 Options Tab, Session Customizer Class Field'''''[[Image:sestran.gif|Description of Figure 85-8 follows]]<br>[img_text/sestran Description of "Figure 85-8 Options Tab, Session Customizer Class Field"]<br><br>
+
# Click the '''Options''' tab. The Options tab appears.<br>'''''Options Tab, Session Customizer Class Field'''''<br>[[Image:sestran.gif|Options Tab, Session Customizer Class Field]]<br><br>
# Complete the [topicid:session.options.sessionCustomizerClass '''Session Customizer Class'''] field.
+
# Complete the '''Session Customizer Class''' field.
 
+
#Click '''Browse''' and select the customizer class for this session.
Click '''Browse''' and select the customizer class for this session.
+
 
+
'''See Also'''
+
 
+
: [[#Configuring a Session Customizer Class]]
+
: [[#Configuring a Session]
+
 
+
  
  
 
===How to Configure Customizer Class Using Java===
 
===How to Configure Customizer Class Using Java===
  
When using Java, create a customize class that implements the <tt>org.eclipse.persistence.tools.sessionconfiguration.SessionCustomizer</tt> interface. [[#Example 85-7] illustrates the creation of the session customizer. The <tt>customize</tt> method contains the configuration of the <tt>Login</tt> owned by the <tt>Session</tt> with the appropriate transaction isolation.
+
When using Java, create a customize class that implements the <tt> org.eclipse.persistence.internal.sessions.factories.SessionCustomizer</tt> interface. This example illustrates the creation of the session customizer. The <tt>customize</tt> method contains the configuration of the <tt>Login</tt> owned by the <tt>Session</tt> with the appropriate transaction isolation.
  
  
 
+
<span id="Example 85-7"></span>
'''''Example 85-7 Creating a SessionCustomizer Class'''''
+
''''' Creating a SessionCustomizer Class'''''
 
+
<source lang="java">
+
  import org.eclipse.persistence.internal.sessions.factories.SessionCustomizer;
  import org.eclipse.persistence.tools.sessionconfiguration.SessionCustomizer;
+
 
  import org.eclipse.persistence.sessions.Session;
 
  import org.eclipse.persistence.sessions.Session;
 
  import org.eclipse.persistence.sessions.DatabaseLogin;
 
  import org.eclipse.persistence.sessions.DatabaseLogin;
Line 988: Line 935:
 
     }
 
     }
 
  }
 
  }
 
+
</source>
 
+
  
 
==Configuring the Server Platform==
 
==Configuring the Server Platform==
  
 
The EclipseLink server platform defines how a session integrates with a Java EE server including the following:
 
The EclipseLink server platform defines how a session integrates with a Java EE server including the following:
 +
* Run-time services: Enables the deployment of a Java Management Extensions (JMX) MBean that allows monitoring of the EclipseLink session.
 +
* External transaction controller: Integrates the EclipseLink session with the server's Java Transaction API (JTA) service. This should always be used when using EJB or JTA transactions. You configure EclipseLink to integrate with the container's external transaction service by specifying an EclipseLink external transaction controller. For more information on external transaction services, see [[Introduction%20to%20EclipseLink%20Transactions (ELUG)#Unit of Work Transaction Demarcation|Unit of Work Transaction Demarcation]].
  
* Run-time services: Enables the deployment of a Java Management Extensions (JMX) MBean that allows monitoring of the EclipseLink session. Currently, this is only supported for OC4J.
+
This table summarizes which sessions support a server platform.
* External transaction controller: Integrates the EclipseLink session with the server's Java Transaction API (JTA) service. This should always be used when using EJB or JTA transactions. You configure EclipseLink to integrate with the container's external transaction service by specifying a EclipseLink external transaction controller. For more information on external transaction services, see [Introduction%20to%20EclipseLink%20Transactions|Unit of Work Transaction Demarcation].
+
  
[[#Table 85-8] summarizes which sessions support a server platform.
 
  
 
+
<span id="Table 85-13"></span>
 
+
''''' Session Support for Server Platform'''''
'''''Table 85-13 Session Support for Server Platform'''''
+
  
 
{| class="RuleFormal" dir="ltr" title="Session Support for Server Platform" summary="This table summarizes which sessions support additional mapping project configuration." width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
 
{| class="RuleFormal" dir="ltr" title="Session Support for Server Platform" summary="This table summarizes which sessions support additional mapping project configuration." width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
Line 1,031: Line 976:
 
[[Image:support.gif|Supported.]]<br>
 
[[Image:support.gif|Supported.]]<br>
 
|}
 
|}
 
<br>
 
 
If the primary mapping project that you associate with a session has a persistence type of bean-managed persistence (BMP) or Java objects, you may configure a server platform using the Workbench. For more information on primary mapping project, see [[#Configuring a Primary Mapping Project]].
 
 
If the primary mapping project you associate with a session has a persistence type of container-managed persistence (CMP), by default, the EclipseLink runtime automatically configures a server platform to accommodate the application server on which it is deployed.
 
 
  
  
 
===How to Configure the Server Platform Using Workbench===
 
===How to Configure the Server Platform Using Workbench===
 
 
To specify the server platform options for a session, use this procedure:
 
To specify the server platform options for a session, use this procedure:
 
 
# Select a session in the '''Navigator'''. Its properties appear in the Editor.
 
# Select a session in the '''Navigator'''. Its properties appear in the Editor.
 
# Click the '''General''' tab. The General tab appears.
 
# Click the '''General''' tab. The General tab appears.
# Click the '''Server Platform''' subtab. The Server Platform subtab appears.<br>'''''Figure 85-9 General Tab, Server Platform Subtab'''''[[Image:sessp.gif|Description of Figure 85-9 follows]]<br>[img_text/sessp Description of "Figure 85-9 General Tab, Server Platform Subtab"]<br><br>
+
# Click the '''Server Platform''' subtab. The Server Platform subtab appears.<br>'''''General Tab, Server Platform Subtab'''''<br>[[Image:sessp.gif|General Tab, Server Platform Subtab]]<br><br>
# Enter complete each field on the [topicid:session.serverPlatform Server Platform subtab].
+
# Enter complete each field on the Server Platform subtab.
  
 
Use the following information to enter data in each field of the Server Platform subtab:
 
Use the following information to enter data in each field of the Server Platform subtab:
 
+
{| class="HRuleInformal" dir="ltr" title="This table defines each field on the New EclipseLink Session dialog." summary="This table defines each field on the New Session dialog." width="100%" border="1" frame="hsides" rules="rows" cellpadding="3" frame="hsides" rules="rows"
 
+
 
+
{| class="HRuleInformal" dir="ltr" title="This table defines each field on the New TopLink Session dialog." summary="This table defines each field on the New TopLink Session dialog." width="100%" border="1" frame="hsides" rules="rows" cellpadding="3" frame="hsides" rules="rows"
+
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
! id="r1c1-t21" align="left" valign="bottom" | '''Field'''
 
! id="r1c1-t21" align="left" valign="bottom" | '''Field'''
Line 1,060: Line 993:
 
| id="r2c1-t21" headers="r1c1-t21" align="left" | '''Server Platform'''
 
| id="r2c1-t21" headers="r1c1-t21" align="left" | '''Server Platform'''
 
| headers="r2c1-t21 r1c2-t21" align="left" |
 
| headers="r2c1-t21 r1c2-t21" align="left" |
Check this field if you intend to deploy your application to a Java EE application server. If you check this field, you must configure the target application server by selecting a '''Platform'''.
+
Check this field if you intend to deploy your application to a Java EE application server.  
 +
 
 +
If you check this field, you must configure the target application server by selecting a '''Platform'''.
 
|- align="left" valign="top"
 
|- align="left" valign="top"
| id="r3c1-t21" headers="r1c1-t21" align="left" | '''Platform'''
+
| id="r3c1-t21" headers="r1c1-t21" align="left" |  
 +
:'''Platform'''
 
| headers="r3c1-t21 r1c2-t21" align="left" |
 
| headers="r3c1-t21 r1c2-t21" align="left" |
Select the Java EE application server to which you will deploy your application. EclipseLink supports the following Java EE application servers:
+
Select the Java EE application server to which you will deploy your application.  
* OC4J 11.1.1
+
 
 +
EclipseLink supports the following Java EE application servers:
 
* OC4J 10.1.3
 
* OC4J 10.1.3
* OC4J 9.0.4
 
* OC4J 9.0.3
 
 
* SunAS 9
 
* SunAS 9
 +
* WebLogic 10.3
 +
* WebLogic 10
 
* WebLogic 9.0
 
* WebLogic 9.0
 
* WebSphere 6.1
 
* WebSphere 6.1
* WebSphere 5.1
+
* [[EclipseLink/Examples/JPA/JBoss_Web_Tutorial|JBoss 4.2.2]]
* CustomFor detailed information about supported application server versions and configuration requirements, see [Integrating%20EclipseLink%20with%20an%20Application%20Server%20(ELUG)|Chapter 7, "Integrating EclipseLink with an Application Server"].Select '''Custom''' if you have created your own <tt>org.eclipse.persistence.platform.server.ServerPlatform</tt> class to use an application server not currently supported by EclipseLink or to override an existing <tt>ServerPlatform</tt>. If you select '''Custom''', you must specify your custom <tt>ServerPlatform</tt> class by selecting a '''Server Platform Class'''.The server platform you select overrides the default server platform set at the sessions configuration level (see [Creating%20a%20Session%20(ELUG)|Creating a Sessions Configuration]).
+
* JBoss 4.2.2
 +
* GlassFish 2.1
 +
* GlassFish 3
 +
* Custom
 +
 
 +
EclipseLink supports the following Java Servlet container servers:
 +
* [[EclipseLink/Examples/JPA/Tomcat_Web_Tutorial|Tomcat 6]]
 +
 
 +
For detailed information about supported application server versions and configuration requirements, see [[Integrating%20EclipseLink%20with%20an%20Application%20Server%20(ELUG)|Integrating EclipseLink with an Application Server]].<br><br>Select '''Custom''' if you have created your own <tt>org.eclipse.persistence.platform.server.ServerPlatform</tt> class to use an application server not currently supported by EclipseLink or to override an existing <tt>ServerPlatform</tt>. If you select '''Custom''', you must specify your custom <tt>ServerPlatform</tt> class by selecting a '''Server Platform Class'''.
 +
 
 +
The server platform you select overrides the default server platform set at the [[Creating%20a%20Session%20(ELUG)#Creating a Sessions Configuration|sessions configuration leve]].
 
|- align="left" valign="top"
 
|- align="left" valign="top"
| id="r4c1-t21" headers="r1c1-t21" align="left" | '''Enable Runtime Services'''
+
| id="r4c1-t21" headers="r1c1-t21" align="left" |  
 +
:'''Enable Runtime Services'''
 
| headers="r4c1-t21 r1c2-t21" align="left" |
 
| headers="r4c1-t21 r1c2-t21" align="left" |
Check this field to configure the EclipseLink runtime to enable the deployment of a JMX MBean that allows monitoring of the EclipseLink session. Currently, this is only supported for OC4J. To use this feature, you must enable DMS data collection.
+
Check this field to configure the EclipseLink runtime to enable the deployment of a JMX MBean that allows monitoring of the EclipseLink session.  
 +
 
 +
 
 
|- align="left" valign="top"
 
|- align="left" valign="top"
| id="r5c1-t21" headers="r1c1-t21" align="left" | '''Enable External Transaction Controller (JTA)'''
+
| id="r5c1-t21" headers="r1c1-t21" align="left" |  
 +
:'''Enable External Transaction Controller (JTA)'''
 
| headers="r5c1-t21 r1c2-t21" align="left" |
 
| headers="r5c1-t21 r1c2-t21" align="left" |
Check this field if you intend to integrate your application with an external transaction controller. For more information, see [Introduction%20to%20EclipseLink%20Transactions|Unit of Work Transaction Demarcation]. If you configure '''Platform''' for a Java EE application server that EclipseLink supports, the EclipseLink runtime will automatically select the appropriate external transaction controller class.If you configure '''Platform''' as '''Custom''', you must specify an external transaction controller class by selecting an '''External Transaction Controller'''.
+
Check this field if you intend to integrate your application with an external transaction controller. For more information, see [[Introduction%20to%20EclipseLink%20Transactions (ELUG)#Unit of Work Transaction Demarcation|Unit of Work Transaction Demarcation]].  
 +
 
 +
If you configure '''Platform''' for a Java EE application server that EclipseLink supports, the EclipseLink runtime will automatically select the appropriate external transaction controller class.
 +
 
 +
If you configure '''Platform''' as '''Custom''', you must specify an external transaction controller class by selecting an '''External Transaction Controller'''.
 
|- align="left" valign="top"
 
|- align="left" valign="top"
| id="r6c1-t21" headers="r1c1-t21" align="left" | '''Server Platform Class'''
+
| id="r6c1-t21" headers="r1c1-t21" align="left" |  
 +
:'''Server Platform Class'''
 
| headers="r6c1-t21 r1c2-t21" align="left" |
 
| headers="r6c1-t21 r1c2-t21" align="left" |
This option is only available if you configure '''Platform''' as '''Custom'''. Click Browse to select your custom <tt>ServerPlatform</tt> class.
+
This option is only available if you configure '''Platform''' as '''Custom'''.  
 +
 
 +
Click Browse to select your custom <tt>ServerPlatform</tt> class.
 
|- align="left" valign="top"
 
|- align="left" valign="top"
| id="r7c1-t21" headers="r1c1-t21" align="left" | '''Transaction Controller Class (JTA)'''
+
| id="r7c1-t21" headers="r1c1-t21" align="left" |  
 +
:'''Transaction Controller Class (JTA)'''
 
| headers="r7c1-t21 r1c2-t21" align="left" |
 
| headers="r7c1-t21 r1c2-t21" align="left" |
This option is only available if you configure '''Platform''' as '''Custom'''. If you checked '''Enable External Transaction Controller (JTA)''', click '''Browse''' to select the transaction controller class that corresponds with your custom <tt>ServerPlatform</tt> class.
+
This option is only available if you configure '''Platform''' as '''Custom'''.  
 +
 
 +
If you checked '''Enable External Transaction Controller (JTA)''', click '''Browse''' to select the transaction controller class that corresponds with your custom <tt>ServerPlatform</tt> class.
 
|}
 
|}
 
<br>
 
  
 
===How to Configure the Server Platform Using Java===
 
===How to Configure the Server Platform Using Java===
 +
When using Java, you must pass the session in a server platform constructor. This example illustrates using a session customizer (see [[Customizing%20the%20EclipseLink%20Application (ELUG)#Using the Session Customizer Class|Using the Session Customizer Class]]) to configure a session with a server platform from the <tt>org.eclipse.persistence.platform.server</tt> package.
  
When using Java, you must pass the session in a server platform constructor. [[#Example 85-8] illustrates using a session event listener (see [[#Configuring Session Event Listeners]) to configure a session with a server platform from the <tt>org.eclipse.persistence.platform.server</tt> package.
 
  
 
+
<span id="Example 85-8"></span>
 
+
''''' Configuring a Session with a Server Platform'''''
'''''Example 85-8 Configuring a Session with a Server Platform'''''
+
<source lang="java">
 
+
  import org.eclipse.persistence.internal.sessions.factories.SessionCustomizer;
   
+
  ...
  public void preLogin(SessionEvent event) {
+
public class MySessionCustomizer implements SessionCustomizer {
  Server server = (Server) event.getSession();
+
    public void customize (Session session) {
  server.setServerPlatform(new Oc4j_11_1_1_Platform((DatabaseSession) server));
+
      Server server = (Server)session;
  }
+
      server.setServerPlatform(new Oc4j_11_1_1_Platform(DatabaseSession)server)):
 +
    }
 +
}
 +
</source>
  
 
==Configuring Session Event Listeners==
 
==Configuring Session Event Listeners==
 +
As you perform persistence operations with a session, the session produces various events (see [[Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Session Event Manager Events|Session Event Manager Events]]) that the EclipseLink runtime uses to coordinate its various components. You can configure a session with one or more [[Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Session Event Listeners|session event listeners]] to customize session behavior and debug session operations. For example, session event listeners play an important role in the [[Configuring%20Exclusive%20Isolated%20Client%20Sessions%20for%20Virtual%20Private%20Database%20(ELUG)#Configuring Exclusive Isolated Client Sessions for Virtual Private Database|configuration of isolated sessions]].
  
As you perform persistence operations with a session, the session produces various events (see [[Introduction%20to%20EclipseLink%20Sessions%20(ELUG)|Session Event Manager Events]]) that the EclipseLink runtime uses to coordinate its various components. You can configure a session with one or more session event listeners (see [[Introduction%20to%20EclipseLink%20Sessions%20(ELUG)|Session Event Listeners]]) to customize session behavior and debug session operations. For example, session event listeners play an important role in the configuration of isolated sessions (see [[Configuring%20Exclusive%20Isolated%20Client%20Sessions%20for%20Virtual%20Private%20Database%20(ELUG)|Configuring Exclusive Isolated Client Sessions for Virtual Private Database]]).
+
This table summarizes which sessions support event listeners (SessionEventListener).
 
+
This table summarizes which sessions support event listeners.
+
  
  
 
<span id="Table 85-14"></span>
 
<span id="Table 85-14"></span>
'''''Session Support for Event LIsteners'''''
+
'''''Session Support for Event Listeners'''''
  
 
{| class="RuleFormal" dir="ltr" title="Session Support for Event LIsteners" summary="This table summarizes which sessions support event listeners." width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
 
{| class="RuleFormal" dir="ltr" title="Session Support for Event LIsteners" summary="This table summarizes which sessions support event listeners." width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
Line 1,145: Line 1,106:
 
[[Image:support.gif|Supported.]]<br>
 
[[Image:support.gif|Supported.]]<br>
 
|}
 
|}
 
 
  
  
Line 1,154: Line 1,113:
  
 
To specify the event listener class in a session, use this procedure:
 
To specify the event listener class in a session, use this procedure:
 
 
# Select a session in the '''Navigator'''. Its properties appear in the Editor.
 
# Select a session in the '''Navigator'''. Its properties appear in the Editor.
 
# Click the '''Options''' tab. The Options tab appears.<br>''''' Options Tab, Event Listeners field'''''<br>[[Image:sesevnt.gif|Options Tab, Event Listeners field]]<br><br>
 
# Click the '''Options''' tab. The Options tab appears.<br>''''' Options Tab, Event Listeners field'''''<br>[[Image:sesevnt.gif|Options Tab, Event Listeners field]]<br><br>
 
#To add a new event listener, click '''Add''', then select the event listener class for this session.<br>To remove an existing event listener, select the '''Event Listener''' and click '''Remove'''.
 
#To add a new event listener, click '''Add''', then select the event listener class for this session.<br>To remove an existing event listener, select the '''Event Listener''' and click '''Remove'''.
 
 
  
  
 
===How to Configure Session Event Listeners Using Java===
 
===How to Configure Session Event Listeners Using Java===
 
+
This example illustrates how to use Java to register a session event listener with a session. EclipseLink provides a <tt>SessionEventAdapter</tt> to simplify creating a <tt>SessionEventListener</tt>. The <tt>SessionEventAdapter</tt> provides a default implementation of all the methods of the <tt>SessionEventListener</tt> interface. You need only override the specific methods of interest. Typically, you would define session event listeners in a [[#Configuring a Session Customizer Class|session customizer class]].
This example illustrates how to use Java to register a session event listener with a session. EclipseLink provides a <tt>SessionEventAdapter</tt> to simplify creating a <tt>SessionEventListener</tt>. The <tt>SessionEventAdapter</tt> provides a default implementation of all the methods of the <tt>SessionEventListener</tt> interface. You need only override the specific methods of interest. Typically, you would define session event listeners in a session customizer class (see [[#Configuring a Session Customizer Class|Configuring a Session Customizer Class]]).
+
  
  
 
<span id="Example 85-9"></span>
 
<span id="Example 85-9"></span>
 
''''' Using the Session Event Adapter to Create a Session Event Listener'''''
 
''''' Using the Session Event Adapter to Create a Session Event Listener'''''
 +
<source lang="java">
 
  ...
 
  ...
 
  SessionEventAdapter myEventListener = new SessionEventAdapter() {
 
  SessionEventAdapter myEventListener = new SessionEventAdapter() {
     '''// Listen for PostCommitUnitOfWork events'''
+
     // Listen for PostCommitUnitOfWork events
 
     public void postCommitUnitOfWork(SessionEvent event) {
 
     public void postCommitUnitOfWork(SessionEvent event) {
         '''// Call the handler routine'''
+
         // Call the handler routine
 
         unitOfWorkCommitted();
 
         unitOfWorkCommitted();
 
     }
 
     }
Line 1,179: Line 1,135:
 
  mySession.getEventManager().addListener(myEventListener);
 
  mySession.getEventManager().addListener(myEventListener);
 
  ...
 
  ...
 
+
</source>
  
  
Line 1,185: Line 1,141:
  
 
==Configuring the Integrity Checker==
 
==Configuring the Integrity Checker==
 +
 
When you log into a session, EclipseLink initializes and validates the descriptors you registered with it. By configuring the integrity checker, you can customize this validation process to do the following:
 
When you log into a session, EclipseLink initializes and validates the descriptors you registered with it. By configuring the integrity checker, you can customize this validation process to do the following:
 
* [[#Check Database|Check Database]]
 
* [[#Check Database|Check Database]]
Line 1,197: Line 1,154:
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
! id="r1c1-t23" align="left" valign="bottom" | '''Session'''
 
! id="r1c1-t23" align="left" valign="bottom" | '''Session'''
! id="r1c2-t23" align="left" valign="bottom" | '''How to Use Workbench'''
+
! id="r1c2-t23" align="left" valign="bottom" | '''Using the Workbench'''
 
! id="r1c3-t23" align="left" valign="bottom" | '''[[#How to Configure the Integrity Checker Using Java|Using Java]]<br>'''
 
! id="r1c3-t23" align="left" valign="bottom" | '''[[#How to Configure the Integrity Checker Using Java|Using Java]]<br>'''
 
|- align="left" valign="top"
 
|- align="left" valign="top"
Line 1,221: Line 1,178:
 
[[Image:support.gif|Supported.]]<br>
 
[[Image:support.gif|Supported.]]<br>
 
|}
 
|}
 
  
  
Line 1,237: Line 1,193:
  
 
By default, the integrity checker tests the default or configured constructor for each descriptor initialized in the session. To disable this feature, use <tt>IntegrityChecker</tt> method <tt>setShouldCheckInstantiationPolicy(false)</tt>.
 
By default, the integrity checker tests the default or configured constructor for each descriptor initialized in the session. To disable this feature, use <tt>IntegrityChecker</tt> method <tt>setShouldCheckInstantiationPolicy(false)</tt>.
 
  
  
Line 1,246: Line 1,201:
 
<span id="Example 85-10"></span>
 
<span id="Example 85-10"></span>
 
''''' Configuring the Integrity Checker'''''
 
''''' Configuring the Integrity Checker'''''
 +
<source lang="java">
 
  session.getIntegrityChecker().setShouldCheckDatabase(true);
 
  session.getIntegrityChecker().setShouldCheckDatabase(true);
 
  session.getIntegrityChecker().setShouldCatchExceptions(false);
 
  session.getIntegrityChecker().setShouldCatchExceptions(false);
 
  session.getIntegrityChecker().setShouldCheckInstantiationPolicy(false);
 
  session.getIntegrityChecker().setShouldCheckInstantiationPolicy(false);
 
  session.login();
 
  session.login();
 +
</source>
 +
  
 
==Configuring Connection Policy==
 
==Configuring Connection Policy==
  
Using a connection policy, you can control how a EclipseLink session acquires and uses read and write connections, including the following:
+
Using a connection policy, you can control how an EclipseLink session acquires and uses read and write connections, including the following:
 
+
 
* [[#Exclusive Write Connections|Exclusive Write Connections]]
 
* [[#Exclusive Write Connections|Exclusive Write Connections]]
 
* [[#Lazy Connection Acquisition|Lazy Connection Acquisition]]
 
* [[#Lazy Connection Acquisition|Lazy Connection Acquisition]]
Line 1,291: Line 1,248:
 
[[Image:unsupport.gif|Unsupported]]<br>
 
[[Image:unsupport.gif|Unsupported]]<br>
 
|}
 
|}
 
 
 
  
  
Line 1,302: Line 1,256:
 
By default, exclusive connections are not used and a client session uses the server session's read connection pool for all non-pessimistic read queries. A connection is obtained from the read connection pool for each read query execution and released back to the pool after the query is executed. A connection is only obtained from the write connection pool for the unit of work commit operation, or, potentially, earlier if data modify queries, or read queries using pessimistic locking are used. The connection will be release back to the write connection pool after the unit of work is committed or released. Exclusive connections are provided for use with database read security or Virtual Private Database (VPD) support. When using an exclusive connection, you will obtain it from the server session's write connection pool. When you acquire the client, the exclusive connection will be used for read queries to isolated classes (see [[Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Isolated Client Sessions|Isolated Client Sessions]]), exclusive read queries, pessimistic read queries, and for the unit of work commit operation. The exclusive connection will only be released when the client session is released. EclipseLink still acquires a shared connection from the read connection pool for reading nonisolated data. If you use a JTA-managed external connection pool with exclusive connections, do not reuse a client session across JTA transaction boundaries, as the physical JTA database connection is released and acquired from the connection pool relative to the JTA transaction life cycle. A new client session, or the active unit of work, should be used for each JTA transaction. For more information, see [[Configuring%20an%20Internal%20Connection%20Pool%20(ELUG)#Configuring Exclusive Read Connections|Configuring Exclusive Read Connections]].
 
By default, exclusive connections are not used and a client session uses the server session's read connection pool for all non-pessimistic read queries. A connection is obtained from the read connection pool for each read query execution and released back to the pool after the query is executed. A connection is only obtained from the write connection pool for the unit of work commit operation, or, potentially, earlier if data modify queries, or read queries using pessimistic locking are used. The connection will be release back to the write connection pool after the unit of work is committed or released. Exclusive connections are provided for use with database read security or Virtual Private Database (VPD) support. When using an exclusive connection, you will obtain it from the server session's write connection pool. When you acquire the client, the exclusive connection will be used for read queries to isolated classes (see [[Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Isolated Client Sessions|Isolated Client Sessions]]), exclusive read queries, pessimistic read queries, and for the unit of work commit operation. The exclusive connection will only be released when the client session is released. EclipseLink still acquires a shared connection from the read connection pool for reading nonisolated data. If you use a JTA-managed external connection pool with exclusive connections, do not reuse a client session across JTA transaction boundaries, as the physical JTA database connection is released and acquired from the connection pool relative to the JTA transaction life cycle. A new client session, or the active unit of work, should be used for each JTA transaction. For more information, see [[Configuring%20an%20Internal%20Connection%20Pool%20(ELUG)#Configuring Exclusive Read Connections|Configuring Exclusive Read Connections]].
  
You can also configure exclusive connections on a client-session-by-client-session basis (see [[Acquiring%20and%20Using%20Sessions%20at%20Run%20Time%20(ELUG)|How to Acquire a Client Session that Uses Exclusive Connections]]) and for named queries (see [[Configuring%20a%20Descriptor%20(ELUG)#Configuring Named Query Advanced Options|Configuring Named Query Advanced Options]]).
+
You can also configure exclusive connections on a client-session-by-client-session basis (see [[Acquiring%20and%20Using%20Sessions%20at%20Run%20Time%20(ELUG)#How to Acquire a Client Session that Uses Exclusive Connections|How to Acquire a Client Session that Uses Exclusive Connections]]) and for named queries (see [[Configuring%20a%20Descriptor%20(ELUG)#Configuring Named Query Advanced Options|Configuring Named Query Advanced Options]]).
  
<br>
 
  
 
{| 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> If any client session contains an exclusive connection, you must release the session (see [[Acquiring%20and%20Using%20Sessions%20at%20Run%20Time%20(ELUG)#Logging Out of a Session|Logging Out of a Session]]) when you are finished using it. Relying on the finalizer to release the connection when the session is garbage collected may cause errors when dealing with JTA transactions.
+
'''Note'''<nowiki>:</nowiki> If any client session contains an exclusive connection, you must release the session (see [[Acquiring%20and%20Using%20Sessions%20at%20Run%20Time%20(ELUG)#Logging Out of a Session|Logging Out of a Session]]) when you are finished using it. We do not recommend relying on the finalizer to release the connection when the session is garbage-collected. If you are using an active unit of work in a JTA transaction, you do not need to release the client session--the unit of work will release it after the JTA transaction completes.
 
|}
 
|}
 
 
 
  
  
Line 1,321: Line 1,271:
 
Alternatively, you can configure EclipseLink to acquire the write connection at the time you acquire a client session, and release the connection when you release the client session.
 
Alternatively, you can configure EclipseLink to acquire the write connection at the time you acquire a client session, and release the connection when you release the client session.
  
You can also configure lazy connection acquisition on a client-session-by-client-session basis (see [[Acquiring%20and%20Using%20Sessions%20at%20Run%20Time%20(ELUG)|How to Acquire a Client Session that Does Not Use Lazy Connection Allocation]]).
+
You can also configure lazy connection acquisition on a client-session-by-client-session basis (see [[Acquiring%20and%20Using%20Sessions%20at%20Run%20Time%20(ELUG)#How to Acquire a Client Session that Does Not Use Lazy Connection Allocation|How to Acquire a Client Session that Does Not Use Lazy Connection Allocation]]).
  
  
 +
===How to Configure Connection Policy Using Workbench===
  
===How to Configure Connection Policy Using Workbench===
 
 
To specify the connection policy in a session, use this procedure:
 
To specify the connection policy in a session, use this procedure:
 
 
# Select a session in the '''Navigator'''. Its properties appear in the Editor.
 
# Select a session in the '''Navigator'''. Its properties appear in the Editor.
 
# Click the '''Connection Policy''' tab. The Connection Policy tab appears.<br>'''''Connection Policy Tab'''''<br>[[Image:sescpol.gif|Connection Policy Tab]]<br><br>
 
# Click the '''Connection Policy''' tab. The Connection Policy tab appears.<br>'''''Connection Policy Tab'''''<br>[[Image:sescpol.gif|Connection Policy Tab]]<br><br>
 
 
 
  
  
 
===How to Configure Connection Policy Using Java===
 
===How to Configure Connection Policy Using Java===
  
To configure whether or not an exclusive connection is allocated to a particular isolated session, use <tt>ConnectionPolicy</tt> method <tt>setShouldUseExclusiveConnection</tt>.
+
To configure whether or not an exclusive connection is allocated to a particular isolated session, use the <tt>org.eclipse.persistence.sessions.server.ConnectionPolicy</tt> method <tt>setExclusiveMode</tt>. You can set the <tt>ExclusiveMode</tt> to one of the following:
 +
* <tt>Transactional</tt> - triggers the creation of a <tt>ClientSession</tt>.<br>You can also enable this option by selecting '''Acquire Connections Lazily''' in [[#How to Configure Connection Policy Using TopLink Workbench|Workbench]].
 +
* <tt>Isolated</tt> - triggers the creation of an <tt>ExclusiveIsolatedClientSession</tt>.<br>You can also enable this option by selecting '''Acquire Exclusive Connection''' in [[#How to Configure Connection Policy Using TopLink Workbench|Workbench]]. 
 +
* <tt>Asways</tt> - also triggers the creation of an <tt>ExclusiveIsolatedClientSession</tt>. Note that this mode allows the usage of an exclusive connection without requiring isolation.<br>You cannot use Workbench to set this option.
  
 
To define a map of properties used to support an isolated session, use the following <tt>ConnectionPolicy</tt> methods:
 
To define a map of properties used to support an isolated session, use the following <tt>ConnectionPolicy</tt> methods:
  
* <tt>setProperty(Object key, Object value)</tt><nowiki>: Adds the property </nowiki><tt>value</tt> to the <tt>Map</tt> under <tt>key</tt>, overwriting the existing value if <tt>key</tt> already exists in the <tt>Map</tt>.
+
* <tt>setProperty(Object key, Object value)</tt><nowiki>: Adds the property </nowiki><tt>value</tt> to the <tt>Map</tt> under <tt>key</tt>, overwriting the existing value if <tt>key</tt> already exists in the <tt>Map</tt>.<br>Note that these properties are not specifically geared toward an isolated client session. EclipseLink runtime makes them available during the creation of a client session in a <tt>PostAcquireExclusiveConnection</tt> event, but does not pass them to any event. Instead, it keeps these properties in the <tt>ConnectionPolicy</tt>, which, in turn, is kept by the client session.
 
* <tt>Object getProperty(Object key)</tt><nowiki>: Returns the value associated with </nowiki><tt>key</tt> as an <tt>Object</tt>.
 
* <tt>Object getProperty(Object key)</tt><nowiki>: Returns the value associated with </nowiki><tt>key</tt> as an <tt>Object</tt>.
 
* <tt>boolean hasProperties</tt><nowiki>: Returns </nowiki><tt>true</tt> if one or more properties exist in the <tt>Map</tt><nowiki>; otherwise returns false.</nowiki>
 
* <tt>boolean hasProperties</tt><nowiki>: Returns </nowiki><tt>true</tt> if one or more properties exist in the <tt>Map</tt><nowiki>; otherwise returns false.</nowiki>
  
The EclipseLink runtime passes this <tt>Map</tt> into <tt>SessionEvent</tt> events <tt>PostAcquireExclusiveConnection</tt> and <tt>PreReleaseExclusiveConnection</tt> so that your implementation can make the appropriate PL/SQL calls to the underlying database platform (see [[Configuring%20Exclusive%20Isolated%20Client%20Sessions%20for%20Virtual%20Private%20Database%20(ELUG)|Using PostAcquireExclusiveConnection Event Handler]] and [[Configuring%20Exclusive%20Isolated%20Client%20Sessions%20for%20Virtual%20Private%20Database%20(ELUG)|Using PreReleaseExclusiveConnection Event Handler]]).
+
The EclipseLink runtime passes this <tt>Map</tt> into <tt>SessionEvent</tt> events <tt>PostAcquireExclusiveConnection</tt> and <tt>PreReleaseExclusiveConnection</tt> so that your implementation can make the appropriate PL/SQL calls to the underlying database platform (see [[Configuring%20Exclusive%20Isolated%20Client%20Sessions%20for%20Virtual%20Private%20Database%20(ELUG)#Using PostAcquireExclusiveConnection Event Handler|Using PostAcquireExclusiveConnection Event Handler]] and [[Configuring%20Exclusive%20Isolated%20Client%20Sessions%20for%20Virtual%20Private%20Database%20(ELUG)#Using PreReleaseExclusiveConnection Event Handler|Using PreReleaseExclusiveConnection Event Handler]]).
  
To configure the session to use a named connection pool, use the <tt>ConnectionPool</tt> constructor that takes a <tt>String</tt> connection pool name as an argument:
+
To configure the session to use a named connection pool, use the <tt>ConnectionPool</tt> constructor that takes a <tt>String</tt> connection pool name as an argument, as follows:
  Session clientSession = server.acquireClientSession(
+
  Session clientSession = server.acquireClientSession(new ConnectionPolicy("myConnectionPool"));
    new ConnectionPolicy("myConnectionPool")
+
);
+
  
 
==Configuring Named Queries at the Session Level==
 
==Configuring Named Queries at the Session Level==
 
+
A '''named query''' is an EclipseLink query that you create and store, by name, in a session for later retrieval and execution. Named queries improve application performance, because they are prepared once and they (and all their associated supporting objects) can be efficiently reused thereafter making them well-suited for frequently executed operations.
A '''named query''' is a EclipseLink query that you create and store, by name, in a session for later retrieval and execution. Named queries improve application performance, because they are prepared once and they (and all their associated supporting objects) can be efficiently reused thereafter making them well-suited for frequently executed operations.
+
  
 
If a named query is global to a project, configure it at the session level. Alternatively, you can configure a named query at the descriptor level (see [[Configuring%20a%20Descriptor%20(ELUG)#Configuring Named Queries at the Descriptor Level|Configuring Named Queries at the Descriptor Level]]).
 
If a named query is global to a project, configure it at the session level. Alternatively, you can configure a named query at the descriptor level (see [[Configuring%20a%20Descriptor%20(ELUG)#Configuring Named Queries at the Descriptor Level|Configuring Named Queries at the Descriptor Level]]).
Line 1,364: Line 1,310:
  
 
<span id="Table 85-17"></span>
 
<span id="Table 85-17"></span>
''''' Session Support for Named Queries'''''
 
  
 
{| class="RuleFormal" dir="ltr" title="Session Support for Named Queries" summary="This table summarizes which sessions support event listeners." width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
 
{| class="RuleFormal" dir="ltr" title="Session Support for Named Queries" summary="This table summarizes which sessions support event listeners." width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
! id="r1c1-t26" align="left" valign="bottom" | '''Session'''
 
! id="r1c1-t26" align="left" valign="bottom" | '''Session'''
! id="r1c2-t26" align="left" valign="bottom" | '''How to Use Workbench'''
+
! id="r1c2-t26" align="left" valign="bottom" | '''Using the Workbench'''
 
! id="r1c3-t26" align="left" valign="bottom" | '''[[#How to Configure Named Queries at the Session Level Using Java|Using Java]]<br>'''
 
! id="r1c3-t26" align="left" valign="bottom" | '''[[#How to Configure Named Queries at the Session Level Using Java|Using Java]]<br>'''
 
|- align="left" valign="top"
 
|- align="left" valign="top"
Line 1,394: Line 1,339:
 
|}
 
|}
  
<br>
 
  
 
After you create a named query, you can execute it by name on the EclipseLink session (see [[Using%20Basic%20Query%20API%20(ELUG)#Using Named Queries|Using Named Queries]]).
 
After you create a named query, you can execute it by name on the EclipseLink session (see [[Using%20Basic%20Query%20API%20(ELUG)#Using Named Queries|Using Named Queries]]).
  
 
For more information about named queries, see [[Introduction%20to%20EclipseLink%20Queries%20(ELUG)#Named Queries|Named Queries]].
 
For more information about named queries, see [[Introduction%20to%20EclipseLink%20Queries%20(ELUG)#Named Queries|Named Queries]].
 
  
  
Line 1,414: Line 1,357:
  
 
[[Category: EclipseLink User's Guide]]
 
[[Category: EclipseLink User's Guide]]
[[Category: Draft]]
+
[[Category: Release 1]]
 
[[Category: Task]]
 
[[Category: Task]]

Latest revision as of 11:13, 23 July 2012

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


Contents

Related topics

This table lists the types of EclipseLink sessions that you can configure and provides a cross-reference to the type-specific chapter that lists the configurable options supported by that type.


If you are creating... See...

Server and client sessions

Configuring Server Sessions

Unit of Work Sessions

Introduction to EclipseLink Transactions

Isolated Client Sessions

Configuring Exclusive Isolated Client Sessions for Virtual Private Database

Historical sessions

Configuring Historical Sessions

Session broker and client sessions

Configuring Session Broker and Client Sessions

Database sessions

Configuring Database Sessions


For more information, see the following:


Configuring Common Session Options

This table lists the configurable options shared by two or more EclipseLink session types. In addition to the configurable options described here, you must also configure the options described for the specific Session Types, as shown in The Configuring EclipseLink Sessions table.


Option to Configure EclipseLink Workbench Java

Primary mapping project

Supported

Supported

Session login

Supported

Supported

Logging

Supported

Supported

Multiple mapping projects

Supported

Supported

Performance profiler

Supported

Supported

Exception handler

Supported

Supported

Session customizer class

Supported

Supported

Server platform

Supported

Supported

Session event listener

Supported

Supported

Configuring a Coordinated Cache

Supported

Supported

Integrity checker

Unsupported

Supported

Connection policy

Supported

Supported

Named queries

Unsupported

Supported


Configuring a Primary Mapping Project

The mapping project contains your EclipseLink mapping metadata (see Introduction to Projects), including descriptors and mappings. Each session is associated with at least one project so that the session can register the descriptors.

This table summarizes which sessions support a primary mapping project configuration.


Session Using the Workbench
Using Java

Server and Client Sessions

Supported.

Supported.

Session broker and client sessions

Supported.

Supported.

Database sessions

Supported.

Supported.


Using the Workbench, you can export your mapping metadata as either a deployment XML file or as a Java class. Consequently, in a session, you can specify the mapping project as an XML file or as a Java class.

If you export your mapping metadata as a Java class, you must compile it and add it to the session configuration classpath before adding it to a session.


Note: When specifying the mapping project using XML, you can specify the Java resource path. In most applications, the sessions.xml and project.xml files are deployed inside the JAR file, and the project XML path is specified as a Java resource path. When specifying the Java resource path, ensure that you are using the forward slash character ( / ) for directories, not the back slash ( \ ).

For example, com/myapp/mypersistence/my-project.xml, or META-INF/my-project.xml.


See Configuring Multiple Mapping Projects for information on configuring additional EclipseLink projects for the session.


How to Configure a Primary Mapping Project Using Workbench

To specify the primary EclipseLink project metadata for your session, use this procedure:

  1. Select a server or database session in the Navigator. Its properties appear in the Editor.
  2. Click the General tab. The General tab appears.
  3. Click the Project subtab. The Project subtab appears.
    General Tab, Project Subtab, Primary Project Option
    General Tab, Project Subtab, Primary Project Option

  4. Select the following options:
  5. Complete each field on the Edit Primary Project dialog box.

Use this information to enter date in each field of the Edit Primary Project dialog box:

Field Description
XML Select XML to add a mapping project as a deployment XML file. Click Browse to select the file.
Class Select Class to add a mapping project as a compiled Java class file. Click Browse to select the file.


How to Configure a Primary Mapping Project Using Java

Using Java, you can register descriptors with a session using the following API:

  • Project API – Read your project.xml file (or instantiate your project class) and create your session using Project method createServerSession or createDatabaseSession.
  • Session API – Add a descriptor or set of descriptors to a session using the DatabaseSession API that the following table lists. Descriptors should be registered before login, but independent sets of descriptors can be added after login.


DatabaseSession API for Registering Descriptors

Session Method Description

addDescriptors(Project)

Add to the session all the descriptors owned by the passed in Project.

addDescriptors(Vector)

Add to the session all the descriptors in the passed in Vector.

addDescriptor(Descriptor)

Add an individual descriptor to the session.


Configuring a Session Login

A session login encapsulates details of data source access for any session that persists to a data source. The session login overrides any other login configuration.

This table summarizes which sessions support session login configuration.


Session Session Login

Server and Client Sessions

Supported.

Session Broker and Client Sessions

Supported.

Database Sessions

Supported.


The session login provides access to a variety of features, including the following:

  • Connection configuration such as whether or not to use external connection pooling.
  • Sequencing configuration (that overrides sequencing configuration made at the project level, if any).
  • Miscellaneous options specific to your chosen data source.
  • Properties (arbitrary, application-specific named values).

For more information, see the following:


Configuring Logging

Use the EclipseLink logging framework to record EclipseLink behavior to a log file or session console.

This table summarizes which sessions support logging configuration.

Session Using the Workbench
Using Java

Server and client sessions

Supported.

Supported.

Unit of work sessions

Supported.

Supported.

Session broker and client sessions

Supported.

Supported.

Database sessions

Supported.

Supported.


Note: If the session belongs to a session broker, you must specify the logging information in the session broker – not in the session itself.


By default, EclipseLink uses its own native logger. Alternatively, you can configure EclipseLink to use the java.util.logging package.

For more information, see Logging.


How to Configure Logging Using Workbench

To specify the logging information for a session, use this procedure:

  1. Select a database session in the Navigator. Its properties appear in the Editor.
  2. Click the Logging tab. The Logging tab appears.
    Logging Tab
    Logging Tab

  3. Complete the Logging fields on the tab.

Use the following information to enter data in each field of the Logging tab to select the profiler option to use with this session:

Option Description
No Logging Select this option to specify that nothing is logged for this session.
Server Select this option to use logging capabilities of the application server to which you are deploying this application.
Java Select this option to use java.util.logging package.
Standard

Select this option to use the EclipseLink logging framework. When selected, you can optionally configure the following options.

Logging Level

Define the amount of logging information to record (in ascending order of information):

  • Config – Log only login, JDBC connection, and database information.
  • Info (default) – Log the login/logout per sever session, with user name. After acquiring the session, detailed information is logged.
  • Warning – Log exceptions that do not force EclipseLink to stop, including all exceptions not logged with Severe level. This does not include a stack trace.
  • Severe – Log exceptions indicating EclipseLink cannot continue, and any exceptions generated during login. This includes a stack trace.
  • Fine – Log SQL (including thread information).
  • Finer – Similar to warning. Includes stack trace.
  • Finest – Includes additional low-level information.
  • All – Log everything.
Console
Select this option to display logging information to the standard console output.
File
Select this option to record logging information in a file. Click Browse to specify the name and location of the log file.
Options Select this option to override additional logging option defaults for Java and Standard logging only.
Log Exception Stack Trace

Select this option to include the stack trace with any exception written to the log.

Default: For SEVERE messages, log stack trace. For WARNING messages, only log stack trace at log level FINER or lower.

Print Connection

Select this option to include the connection identifier in any connection related log messages.

Default: Enabled for all message and log levels.

Print Date

Select this option to include the date and time at which the log message was generated.

Default: Enabled for all message and log levels.

Print Session

Select this option to include the session name in any session related log messages.

Default: Enabled for all message and log levels.

Print Thread

Select this option to include the thread name in any thread related log messages.

Default: Log only at log level FINER or lower.


How to Configure Logging Using Session API in Java

If you use EclipseLink native logging (the default), then at run time, you can configure logging options using org.eclipse.persistence.sessions.Session logging API.

The Session interface defines the following logging methods:

  • setSessionLog – specify the type of logging to use (any implementor of org.eclipse.persistence.logging.SessionLog)
  • dontLogMessages – disable logging
  • setLog – specify the java.io.Writer to which the session logs messages
  • setLogLevel – specify the level at which the session logs using org.eclipse.persistence.logging.SessionLog constants:
    • OFF
    • SEVERE
    • WARNING
    • INFO
    • CONFIG
    • FINE
    • FINER
    • FINEST
    • ALL


This example illustrates how to configure a session to use java.util.logging package.

Configuring a Session to Use java.util.logging

session.setSessionLog(new JavaLog());


This example illustrates how to configure a session to use the server log that OC4J provides. For more information about server logging, see Server Logging.

Configuring a Session to Use Application Server Logging

session.setSessionLog(new OjdlLog());


This example illustrates how to configure a session to log to a java.io.Writer:

Configuring a Session to Log to a java.io.Writer

session.setLog(myWriter);


How to Configure a Session to use the java.util.logging Package

If you use java.util.logging package, then you configure logging options in the <JRE_HOME>/lib/logging.properties file. Messages are written to zero or multiple destinations based on this configuration file.

If you configure a session to use java.util.logging package, consider the following:


logging.properties

Configure the logging.properties file as this example illustrates:

java.util.logging Configuration in logging.properties

 handlers = java.util.logging.ConsoleHandler
 java.util.logging.ConsoleHandler.level = CONFIG
 java.util.logging.ConsoleHandler.formatter = org.eclipse.persistence.logging.LogFormatter
 org.eclipse.persistence.LoggingSession.connection.level = CONFIG

For information about the types of formatters available, see Formatters.

Formatters

EclipseLink provides two formatters: LogFormatter and XMLLogFormatter. They override the SimpleFormatter and XMLFormatter java.util.logging formatters and always log session and connection info when available. They also log thread and exception stack trace information at certain levels as specified by the logging level.


Namespace

Namespace is supported for java.util.logging. This table lists the static constants defined in org.eclipse.persistence.sessions.SessionLog for EclipseLink components and the corresponding strings in logging.properties.


Logging Property FIle Names

SessionLog logging.properites

Not Applicable

org.eclipse.persistence

Not Applicable

org.eclipse.persistence.<sessionname>

SQL

org.eclipse.persistence.<sessionname>.sql

TRANSACTION

org.eclipse.persistence.<sessionname>.transaction

EVENT

org.eclipse.persistence.<sessionname>.event

CONNECTION

org.eclipse.persistence.<sessionname>.connection

QUERY

org.eclipse.persistence.<sessionname>.query

CACHE

org.eclipse.persistence.<sessionname>.cache

PROPAGATION

org.eclipse.persistence.<sessionname>.propagation

SEQUENCING

org.eclipse.persistence.<sessionname>.sequencing

EJB

org.eclipse.persistence.<sessionname>.ejb

EJB_OR_METADATA

org.eclipse.persistence.<sessionname>.ejb_or_metadata

WEAVER

org.eclipse.persistence.<sessionname>.weaver

PROPERTIES

org.eclipse.persistence.<sessionname>.properties

SERVER

org.eclipse.persistence.<sessionname>.server


In the logging.properties names listed in the Logging Property FIle Names table, note that <sessionname> is the name of the session that the application is running in. For example, if the name of the session is MyApplication, then you would use org.eclipse.persistence.MyApplication.sql for the SQL logging property.

An application can also define its own namespace and write to it through the logging API, as long as the logger for that namespace is defined in the logging configuration. Otherwise messages are written to the parent logger, org.eclipse.persistence.<sessionname>.


Configuring Multiple Mapping Projects

Each session is associated with at least one mapping project. You can include additional EclipseLink mapping projects for a session.

This table summarizes which sessions support additional mapping project configuration.

Session Using the Workbench
Using Java

Server and client sessions

Supported.

Supported.

Session Broker and Client Sessions

Supported.

Supported.

Database sessions

Supported.

Supported.


How to Configure Multiple Mapping Projects Using Workbench

To specify additional EclipseLink projects for your session, use this procedure:

  1. Select a server or database session in the Navigator. Its properties appear in the Editor.
  2. Click the General tab. The General tab appears.
  3. Click the Project subtab. The Project subtab appears.
    General Tab, Project Subtab, Multiple Projects Options
    General Tab, Project Subtab, Multiple Projects Options

  4. Select Multiple Projects option. The Multiple Projects subtab appears.
  5. Click the Multiple Projects subtab.

    General Tab, Multiple Projects Subtab
    General Tab, Multiple Projects Subtab

  6. To add an additional mapping project to this session, click Add. For more information, see Configuring a Primary Mapping Project.
    To remove EclipseLink mapping projects, select the project file and click Remove.


How to Configure Multiple Mapping Projects Using Java

Using Java, you can register descriptors from more than one project with a session using the DatabaseSession API that this table lists. You can register descriptors before login, but you can add independent sets of descriptors after login.


DatabaseSession API for Registering Descriptors

Session Method Description

addDescriptors(Project)

Add additional descriptor to the session in the form of a project.

addDescriptors(Vector)

Add a vector of individual descriptor files to the session in the form of a project.

addDescriptor(Descriptor)

Add individual descriptor to the session.


Configuring a Performance Profiler

To successfully improve the performance of an EclipseLink application, you must measure performance before and after each optimization. EclipseLink provides a variety of built-in performance measuring features (known as profilers) that you can configure at the session level.

This table summarizes which sessions support performance profiler configuration.


Session Using the Workbench
Using Java

Server and client sessions

Supported.

Supported.

Session broker and client sessions

Supported.

Supported.

Database sessions

Supported.

Supported.


EclipseLink provides the following profilers:


How to Configure a Performance Profiler Using Workbench

To specify the type of profiler in a session, use this procedure:

  1. Select a session in the Navigator. Its properties appear in the Editor.
  2. Click the Options tab. The Options tab appears.
    Options Tab, Profiler Options
    Options Tab, Profiler Options

  3. Complete the Profiler field on the tab.

Use the following information to select the profiler option to use with this session:

Option Description
No Profiler Disable all profiling.
Standard (EclipseLink)

Enable EclipseLink profiling. For more information, see the following:


How to Configure a Performance Profiler Using Java

You can use Java to configure a session with a profiler using Session method setProfiler, as this example shows.


Configuring a Session with an EclipseLink Profiler

session.setProfiler(new PerformanceProfiler());


To end a profiling session, use Session method clearProfiler.


Configuring an Exception Handler

You can associate a single exception handling class with each session. This class must implement the org.eclipse.persistence.exceptions.ExceptionHandler interface.

This table summarizes which sessions support exception handler configuration.


Session Support for Exception Handler Configuration

Session Using the Workbench
Using Java

Server and client sessions

Supported.

Supported.

Session broker and client sessions

Supported.

Supported.

Database sessions

Supported.

Supported.


For an example exception handler implementation, see Using Java.

For more information, see Exception Handlers.


How to Configure an Exception Handler Using Workbench

To specify the exception handler class in a session, use this procedure:

  1. Select a session in the Navigator. Its properties appear in the Editor.
  2. Click the Options tab. The Options tab appears.
    Options Tab, Exception Handler Field
    Options Tab, Exception Handler Field

  3. Complete the Exception Handler field.
  4. Click Browse and select the exception handler class for this session.


How to Configure an Exception Handler Using Java

This example shows an example exception handler implementation. In this implementation, the exception handler always tries to reestablish the connection if it has been reset by peer, but only retries a query if it is an instance of ReadQuery. Note that this exception handler either returns the result of the reexecuted ReadQuery or throws an exception.


Implementing an Exception Handler

 session.setExceptionHandler(
   new ExceptionHandler() {
     public Object handleException(RuntimeException exception) {
       if (exception instanceof DatabaseException) {
         DatabaseException dbex = (DatabaseException) exception;
         if ((dbex.getInternalException() instanceof SQLException) && 
            (((SQLException) dbex.getInternalException()).getErrorCode() == MyDriver.CONNECTION_RESET_BY_PEER)) {
            dbex.getAccessor().reestablishConnection(dbex.getSession());
            if (dbex.getQuery() instanceof ReadQuery) {
              return dbex.getSession().executeQuery(dbex.getQuery(), dbex.getQuery().getTranslationRow());
            }
            throw exception;
         }
       }
       throw exception;
     }
   }
 );


Note: Unhandled exceptions must be rethrown by the exception handler code.

Configuring a Session Customizer Class

A session customizer class is a Java class that implements the org.eclipse.persistence.internal.sessions.factories.SessionCustomizer interface and provides a default (zero-argument) constructor. You can use a session customizer to customize a session at run time on a loaded session before login occurs, similar to how you can use an amendment method to customize a descriptor) For example, you can use a session customizer class to define and register session event listeners with the session event manager (see Configuring Session Event Listeners).

This table summarizes which sessions support customizer class configuration.


Session Support for Customizer Class Configuration

Session Using the Workbench
How to Use Java

Server and client sessions

Supported.

Supported.

Session broker and client sessions

Supported.

Supported.

Database sessions

Supported.

Supported.


For more information, see Session Customization.


How to Configure Customizer Class Using Workbench

To specify the session customizer class in a session, use this procedure:

  1. Select a session in the Navigator. Its properties appear in the Editor.
  2. Click the Options tab. The Options tab appears.
    Options Tab, Session Customizer Class Field
    Options Tab, Session Customizer Class Field

  3. Complete the Session Customizer Class field.
  4. Click Browse and select the customizer class for this session.


How to Configure Customizer Class Using Java

When using Java, create a customize class that implements the org.eclipse.persistence.internal.sessions.factories.SessionCustomizer interface. This example illustrates the creation of the session customizer. The customize method contains the configuration of the Login owned by the Session with the appropriate transaction isolation.


Creating a SessionCustomizer Class

 import  org.eclipse.persistence.internal.sessions.factories.SessionCustomizer;
 import org.eclipse.persistence.sessions.Session;
 import org.eclipse.persistence.sessions.DatabaseLogin;
 
 public class EmployeeSessionCustomizer implements SessionCustomizer {
 
     public void customize(Sesssion session) {
         DatabaseLogin login = (DatabaseLogin)session.getDatasourceLogin();
         login.setTransactionIsolation(DatabaseLogin.TRANSACTION_READ_UNCOMMITTED);
     }
 }

Configuring the Server Platform

The EclipseLink server platform defines how a session integrates with a Java EE server including the following:

  • Run-time services: Enables the deployment of a Java Management Extensions (JMX) MBean that allows monitoring of the EclipseLink session.
  • External transaction controller: Integrates the EclipseLink session with the server's Java Transaction API (JTA) service. This should always be used when using EJB or JTA transactions. You configure EclipseLink to integrate with the container's external transaction service by specifying an EclipseLink external transaction controller. For more information on external transaction services, see Unit of Work Transaction Demarcation.

This table summarizes which sessions support a server platform.


Session Support for Server Platform

Session Using the Workbench
Using Java

Server and client sessions

Supported.

Supported.

Session broker and client sessions

Supported.

Supported.

Database sessions

Supported.

Supported.


How to Configure the Server Platform Using Workbench

To specify the server platform options for a session, use this procedure:

  1. Select a session in the Navigator. Its properties appear in the Editor.
  2. Click the General tab. The General tab appears.
  3. Click the Server Platform subtab. The Server Platform subtab appears.
    General Tab, Server Platform Subtab
    General Tab, Server Platform Subtab

  4. Enter complete each field on the Server Platform subtab.

Use the following information to enter data in each field of the Server Platform subtab:

Field Description
Server Platform

Check this field if you intend to deploy your application to a Java EE application server.

If you check this field, you must configure the target application server by selecting a Platform.

Platform

Select the Java EE application server to which you will deploy your application.

EclipseLink supports the following Java EE application servers:

  • OC4J 10.1.3
  • SunAS 9
  • WebLogic 10.3
  • WebLogic 10
  • WebLogic 9.0
  • WebSphere 6.1
  • JBoss 4.2.2
  • JBoss 4.2.2
  • GlassFish 2.1
  • GlassFish 3
  • Custom

EclipseLink supports the following Java Servlet container servers:

For detailed information about supported application server versions and configuration requirements, see Integrating EclipseLink with an Application Server.

Select Custom if you have created your own org.eclipse.persistence.platform.server.ServerPlatform class to use an application server not currently supported by EclipseLink or to override an existing ServerPlatform. If you select Custom, you must specify your custom ServerPlatform class by selecting a Server Platform Class.

The server platform you select overrides the default server platform set at the sessions configuration leve.

Enable Runtime Services

Check this field to configure the EclipseLink runtime to enable the deployment of a JMX MBean that allows monitoring of the EclipseLink session.


Enable External Transaction Controller (JTA)

Check this field if you intend to integrate your application with an external transaction controller. For more information, see Unit of Work Transaction Demarcation.

If you configure Platform for a Java EE application server that EclipseLink supports, the EclipseLink runtime will automatically select the appropriate external transaction controller class.

If you configure Platform as Custom, you must specify an external transaction controller class by selecting an External Transaction Controller.

Server Platform Class

This option is only available if you configure Platform as Custom.

Click Browse to select your custom ServerPlatform class.

Transaction Controller Class (JTA)

This option is only available if you configure Platform as Custom.

If you checked Enable External Transaction Controller (JTA), click Browse to select the transaction controller class that corresponds with your custom ServerPlatform class.

How to Configure the Server Platform Using Java

When using Java, you must pass the session in a server platform constructor. This example illustrates using a session customizer (see Using the Session Customizer Class) to configure a session with a server platform from the org.eclipse.persistence.platform.server package.


Configuring a Session with a Server Platform

 import org.eclipse.persistence.internal.sessions.factories.SessionCustomizer; 
 ...
 public class MySessionCustomizer implements SessionCustomizer {
    public void customize (Session session) {
       Server server = (Server)session;
       server.setServerPlatform(new Oc4j_11_1_1_Platform(DatabaseSession)server)):
    }
 }

Configuring Session Event Listeners

As you perform persistence operations with a session, the session produces various events (see Session Event Manager Events) that the EclipseLink runtime uses to coordinate its various components. You can configure a session with one or more session event listeners to customize session behavior and debug session operations. For example, session event listeners play an important role in the configuration of isolated sessions.

This table summarizes which sessions support event listeners (SessionEventListener).


Session Support for Event Listeners

Session Using the Workbench
Using Java

Server and client sessions

Supported.

Supported.

Session broker and client sessions

Supported.

Supported.

Database sessions

Supported.

Supported.


How to Configure Session Event Listeners Using Workbench

Session Event Listeners

To specify the event listener class in a session, use this procedure:

  1. Select a session in the Navigator. Its properties appear in the Editor.
  2. Click the Options tab. The Options tab appears.
    Options Tab, Event Listeners field
    Options Tab, Event Listeners field

  3. To add a new event listener, click Add, then select the event listener class for this session.
    To remove an existing event listener, select the Event Listener and click Remove.


How to Configure Session Event Listeners Using Java

This example illustrates how to use Java to register a session event listener with a session. EclipseLink provides a SessionEventAdapter to simplify creating a SessionEventListener. The SessionEventAdapter provides a default implementation of all the methods of the SessionEventListener interface. You need only override the specific methods of interest. Typically, you would define session event listeners in a session customizer class.


Using the Session Event Adapter to Create a Session Event Listener

 ...
 SessionEventAdapter myEventListener = new SessionEventAdapter() {
     // Listen for PostCommitUnitOfWork events
     public void postCommitUnitOfWork(SessionEvent event) {
         // Call the handler routine
         unitOfWorkCommitted();
     }
 };
 mySession.getEventManager().addListener(myEventListener);
 ...


For information on how to add logging to your listeners, see Logging.

Configuring the Integrity Checker

When you log into a session, EclipseLink initializes and validates the descriptors you registered with it. By configuring the integrity checker, you can customize this validation process to do the following:

This table summarizes which sessions support descriptor integrity checking configuration.

Session Support for Checking Descriptor Integrity

Session Using the Workbench Using Java

Server and client sessions

Unsupported

Supported.

Session broker and client sessions

Unsupported

Supported.

Database sessions

Unsupported

Supported.


Check Database

The IntegrityChecker method setShouldCheckDatabase specifies whether or not the integrity checker should verify the descriptor's metadata against the database metadata. This will report any errors due to missing or incorrect table or fields specified in the descriptors. This is turned off by default as it adds a significant overhead to connecting a session.


Catch All Exceptions

By default, the integrity checker catches all exceptions that occur during initialization, and throws a single exception at the end of initialization reporting all of the errors detected. If you only want the first exception encountered, you can disable this feature using IntegrityChecker method setShouldCatchExceptions(false).


Catch Instantiation Policy Exceptions

By default, the integrity checker tests the default or configured constructor for each descriptor initialized in the session. To disable this feature, use IntegrityChecker method setShouldCheckInstantiationPolicy(false).


How to Configure the Integrity Checker Using Java

As this example shows, you can configure the integrity checker validation process.

Configuring the Integrity Checker

 session.getIntegrityChecker().setShouldCheckDatabase(true);
 session.getIntegrityChecker().setShouldCatchExceptions(false);
 session.getIntegrityChecker().setShouldCheckInstantiationPolicy(false);
 session.login();


Configuring Connection Policy

Using a connection policy, you can control how an EclipseLink session acquires and uses read and write connections, including the following:

This table summarizes which sessions support connection policy configuration.


Session Support for Connection Policy

Session Using Workbench
Using Java

Server and client sessions

Supported.

Supported.

Session broker and client sessions

Unsupported

Unsupported

Database sessions

Unsupported

Unsupported


Exclusive Write Connections

An exclusive connection is one that EclipseLink allocates to a client session for reading (of isolated data) and writing for the duration of the client session's life cycle.

By default, exclusive connections are not used and a client session uses the server session's read connection pool for all non-pessimistic read queries. A connection is obtained from the read connection pool for each read query execution and released back to the pool after the query is executed. A connection is only obtained from the write connection pool for the unit of work commit operation, or, potentially, earlier if data modify queries, or read queries using pessimistic locking are used. The connection will be release back to the write connection pool after the unit of work is committed or released. Exclusive connections are provided for use with database read security or Virtual Private Database (VPD) support. When using an exclusive connection, you will obtain it from the server session's write connection pool. When you acquire the client, the exclusive connection will be used for read queries to isolated classes (see Isolated Client Sessions), exclusive read queries, pessimistic read queries, and for the unit of work commit operation. The exclusive connection will only be released when the client session is released. EclipseLink still acquires a shared connection from the read connection pool for reading nonisolated data. If you use a JTA-managed external connection pool with exclusive connections, do not reuse a client session across JTA transaction boundaries, as the physical JTA database connection is released and acquired from the connection pool relative to the JTA transaction life cycle. A new client session, or the active unit of work, should be used for each JTA transaction. For more information, see Configuring Exclusive Read Connections.

You can also configure exclusive connections on a client-session-by-client-session basis (see How to Acquire a Client Session that Uses Exclusive Connections) and for named queries (see Configuring Named Query Advanced Options).


Note: If any client session contains an exclusive connection, you must release the session (see Logging Out of a Session) when you are finished using it. We do not recommend relying on the finalizer to release the connection when the session is garbage-collected. If you are using an active unit of work in a JTA transaction, you do not need to release the client session--the unit of work will release it after the JTA transaction completes.


Lazy Connection Acquisition

By default, EclipseLink acquires write connections lazily, when you perform the first unit of work commit operation, exclusive read query, or pessimistic read query with your client session. The write connection will also be released after each unit of work it committed or released.

Alternatively, you can configure EclipseLink to acquire the write connection at the time you acquire a client session, and release the connection when you release the client session.

You can also configure lazy connection acquisition on a client-session-by-client-session basis (see How to Acquire a Client Session that Does Not Use Lazy Connection Allocation).


How to Configure Connection Policy Using Workbench

To specify the connection policy in a session, use this procedure:

  1. Select a session in the Navigator. Its properties appear in the Editor.
  2. Click the Connection Policy tab. The Connection Policy tab appears.
    Connection Policy Tab
    Connection Policy Tab


How to Configure Connection Policy Using Java

To configure whether or not an exclusive connection is allocated to a particular isolated session, use the org.eclipse.persistence.sessions.server.ConnectionPolicy method setExclusiveMode. You can set the ExclusiveMode to one of the following:

  • Transactional - triggers the creation of a ClientSession.
    You can also enable this option by selecting Acquire Connections Lazily in Workbench.
  • Isolated - triggers the creation of an ExclusiveIsolatedClientSession.
    You can also enable this option by selecting Acquire Exclusive Connection in Workbench.
  • Asways - also triggers the creation of an ExclusiveIsolatedClientSession. Note that this mode allows the usage of an exclusive connection without requiring isolation.
    You cannot use Workbench to set this option.

To define a map of properties used to support an isolated session, use the following ConnectionPolicy methods:

  • setProperty(Object key, Object value): Adds the property value to the Map under key, overwriting the existing value if key already exists in the Map.
    Note that these properties are not specifically geared toward an isolated client session. EclipseLink runtime makes them available during the creation of a client session in a PostAcquireExclusiveConnection event, but does not pass them to any event. Instead, it keeps these properties in the ConnectionPolicy, which, in turn, is kept by the client session.
  • Object getProperty(Object key): Returns the value associated with key as an Object.
  • boolean hasProperties: Returns true if one or more properties exist in the Map; otherwise returns false.

The EclipseLink runtime passes this Map into SessionEvent events PostAcquireExclusiveConnection and PreReleaseExclusiveConnection so that your implementation can make the appropriate PL/SQL calls to the underlying database platform (see Using PostAcquireExclusiveConnection Event Handler and Using PreReleaseExclusiveConnection Event Handler).

To configure the session to use a named connection pool, use the ConnectionPool constructor that takes a String connection pool name as an argument, as follows:

Session clientSession = server.acquireClientSession(new ConnectionPolicy("myConnectionPool"));

Configuring Named Queries at the Session Level

A named query is an EclipseLink query that you create and store, by name, in a session for later retrieval and execution. Named queries improve application performance, because they are prepared once and they (and all their associated supporting objects) can be efficiently reused thereafter making them well-suited for frequently executed operations.

If a named query is global to a project, configure it at the session level. Alternatively, you can configure a named query at the descriptor level (see Configuring Named Queries at the Descriptor Level).

Use named queries to specify SQL, EJB QL, or EclipseLink Expression queries to access your data source.

This table summarizes which sessions support named query configuration.


Session Using the Workbench Using Java

Server and client sessions

Unsupported

Supported.

Session broker and client sessions

Unsupported

Supported.

Database sessions

Unsupported

Supported.


After you create a named query, you can execute it by name on the EclipseLink session (see Using Named Queries).

For more information about named queries, see Named Queries.


How to Configure Named Queries at the Session Level Using Java

You can store a query by name in a Session using Session method addQuery(String name, DatabaseQuery query).




Copyright Statement