View source for Configuring a Session (ELUG)

[[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__
[[Special:Whatlinkshere/Configuring a Session (ELUG)|Related topics]]</div>

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.


<span id="Table 85-1"></span>
{| 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"
! id="r1c1-t2" align="left" valign="bottom" | '''If you are creating...'''
! id="r1c2-t2" align="left" valign="bottom" | '''See...'''
|- align="left" valign="top"
| id="r2c1-t2" headers="r1c1-t2" align="left" |
[[Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Server and Client Sessions|Server and client sessions]]
| headers="r2c1-t2 r1c2-t2" align="left" |
[[Configuring%20Server%20Sessions%20(ELUG)#CHDFCFGA|Configuring Server Sessions]]<br>
|- align="left" valign="top"
| id="r3c1-t2" headers="r1c1-t2" align="left" |
[[Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Unit of Work Sessions|Unit of Work Sessions]]
| headers="r3c1-t2 r1c2-t2" align="left" |
[[Introduction%20to%20EclipseLink%20Transactions (ELUG)|Introduction to EclipseLink Transactions]]<br>
|- align="left" valign="top"
| id="r4c1-t2" headers="r1c1-t2" align="left" |
[[Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Isolated Client Sessions|Isolated Client Sessions]]
| headers="r4c1-t2 r1c2-t2" align="left" |
[[Configuring%20Exclusive%20Isolated%20Client%20Sessions%20for%20Virtual%20Private%20Database%20(ELUG)|Configuring Exclusive Isolated Client Sessions for Virtual Private Database]]<br>
|- align="left" valign="top"
| id="r5c1-t2" headers="r1c1-t2" align="left" |
[[Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Historical Sessions|Historical sessions ]]
| headers="r5c1-t2 r1c2-t2" align="left" |
[[Configuring%20Historical%20Sessions%20(ELUG)#Configuring Historical Sessions|Configuring Historical Sessions]]<br>
|- align="left" valign="top"
| id="r6c1-t2" headers="r1c1-t2" align="left" |
[[Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Session Broker and Client Sessions|Session broker and client sessions]]
| headers="r6c1-t2 r1c2-t2" align="left" |
[[Configuring%20Session%20Broker%20and%20Client%20Sessions%20(ELUG)#Configuring Session Broker and Client Sessions|Configuring Session Broker and Client Sessions]]<br>
|- align="left" valign="top"
| id="r7c1-t2" headers="r1c1-t2" align="left" |
[[Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Database Sessions|Database sessions]]
| headers="r7c1-t2 r1c2-t2" align="left" |
[[Configuring%20Database%20Sessions%20(ELUG)#Configuring Database Sessions|Configuring Database Sessions]]<br>
|}


For more information, see the following:
* [[Introduction%20to%20EclipseLink%20Sessions%20(ELUG)|Introduction to EclipseLink Sessions]]
* [[Creating%20a%20Session%20(ELUG)|Creating a Session]]



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


<span id="Table 85-2"></span>
{| 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"
|- align="left" valign="top"
! id="r1c1-t3" align="left" valign="bottom" | '''Option to Configure'''
! id="r1c2-t3" align="left" valign="bottom" | '''EclipseLink Workbench'''
! id="r1c3-t3" align="left" valign="bottom" | '''Java'''
|- align="left" valign="top"
| id="r2c1-t3" headers="r1c1-t3" align="left" |
[[#Configuring a Primary Mapping Project|Primary mapping project]]
| headers="r2c1-t3 r1c2-t3" align="left" |
[[Image:support.gif|Supported]]<br>
| headers="r2c1-t3 r1c3-t3" align="left" |
[[Image:support.gif|Supported]]<br>
|- align="left" valign="top"
| id="r3c1-t3" headers="r1c1-t3" align="left" |
[[#Configuring a Session Login|Session login ]]
| headers="r3c1-t3 r1c2-t3" align="left" |
[[Image:support.gif|Supported]]<br>
| headers="r3c1-t3 r1c3-t3" align="left" |
[[Image:support.gif|Supported]]<br>
|- align="left" valign="top"
| id="r4c1-t3" headers="r1c1-t3" align="left" |
[[#Configuring Logging|Logging]]
| headers="r4c1-t3 r1c2-t3" align="left" |
[[Image:support.gif|Supported]]<br>
| headers="r4c1-t3 r1c3-t3" align="left" |
[[Image:support.gif|Supported]]<br>
|- align="left" valign="top"
| id="r5c1-t3" headers="r1c1-t3" align="left" |
[[#Configuring Multiple Mapping Projects|Multiple mapping projects]]
| headers="r5c1-t3 r1c2-t3" align="left" |
[[Image:support.gif|Supported]]<br>
| headers="r5c1-t3 r1c3-t3" align="left" |
[[Image:support.gif|Supported]]<br>
|- align="left" valign="top"
| id="r6c1-t3" headers="r1c1-t3" align="left" |
[[#Configuring a Performance Profiler|Performance profiler ]]
| headers="r6c1-t3 r1c2-t3" align="left" |
[[Image:support.gif|Supported]]<br>
| headers="r6c1-t3 r1c3-t3" align="left" |
[[Image:support.gif|Supported]]<br>
|- align="left" valign="top"
| id="r7c1-t3" headers="r1c1-t3" align="left" |
[[#Configuring an Exception Handler|Exception handler ]]
| headers="r7c1-t3 r1c2-t3" align="left" |
[[Image:support.gif|Supported]]<br>
| headers="r7c1-t3 r1c3-t3" align="left" |
[[Image:support.gif|Supported]]<br>
|- align="left" valign="top"
| id="r8c1-t3" headers="r1c1-t3" align="left" |
[[#Configuring a Session Customizer Class|Session customizer class ]]
| headers="r8c1-t3 r1c2-t3" align="left" |
[[Image:support.gif|Supported]]<br>
| headers="r8c1-t3 r1c3-t3" align="left" |
[[Image:support.gif|Supported]]<br>
|- align="left" valign="top"
| id="r9c1-t3" headers="r1c1-t3" align="left" |
[[#Configuring the Server Platform|Server platform ]]
| headers="r9c1-t3 r1c2-t3" align="left" |
[[Image:support.gif|Supported]]<br>
| headers="r9c1-t3 r1c3-t3" align="left" |
[[Image:support.gif|Supported]]<br>
|- align="left" valign="top"
| id="r10c1-t3" headers="r1c1-t3" align="left" |
[[#Configuring Session Event Listeners|Session event listener ]]
| headers="r10c1-t3 r1c2-t3" align="left" |
[[Image:support.gif|Supported]]<br>
| headers="r10c1-t3 r1c3-t3" align="left" |
[[Image:support.gif|Supported]]<br>
|- align="left" valign="top"
| id="r11c1-t3" headers="r1c1-t3" align="left" |
[[Configuring%20a%20Coordinated%20Cache%20(ELUG)|Configuring a Coordinated Cache]]
| headers="r11c1-t3 r1c2-t3" align="left" |
[[Image:support.gif|Supported]]<br>
| headers="r11c1-t3 r1c3-t3" align="left" |
[[Image:support.gif|Supported]]<br>
|- align="left" valign="top"
| id="r12c1-t3" headers="r1c1-t3" align="left" |
[[#Configuring the Integrity Checker|Integrity checker ]]
| headers="r12c1-t3 r1c2-t3" align="left" |
[[Image:unsupport.gif|Unsupported]]<br>
| headers="r12c1-t3 r1c3-t3" align="left" |
[[Image:support.gif|Supported]]<br>
|- align="left" valign="top"
| id="r13c1-t3" headers="r1c1-t3" align="left" |
[[#Configuring Connection Policy|Connection policy ]]
| headers="r13c1-t3 r1c2-t3" align="left" |
[[Image:support.gif|Supported]]<br>
| headers="r13c1-t3 r1c3-t3" align="left" |
[[Image:support.gif|Supported]]<br>
|- align="left" valign="top"
| id="r14c1-t3" headers="r1c1-t3" align="left" |
[[#Configuring Named Queries at the Session Level|Named queries ]]
| headers="r14c1-t3 r1c2-t3" align="left" |
[[Image:unsupport.gif|Unsupported]]<br>
| headers="r14c1-t3 r1c3-t3" align="left" |
[[Image:support.gif|Supported]]<br>
|}



==Configuring a Primary Mapping Project==

The mapping project contains your EclipseLink mapping metadata (see [[Introduction%20to%20Projects (ELUG)|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.


<span id="Table 85-3"></span>

{| 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"
|- align="left" valign="top"
! id="r1c1-t4" align="left" valign="bottom" | '''Session'''
! id="r1c2-t4" align="left" valign="bottom" | '''[[#How to Configure a Primary Mapping Project Using Workbench|Using the Workbench]]<br>'''
! id="r1c3-t4" align="left" valign="bottom" | '''[[#How to Configure a Primary Mapping Project Using Java|Using Java]]<br>'''
|- align="left" valign="top"
| id="r2c1-t4" headers="r1c1-t4" align="left" |
[[Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Server and Client Sessions|Server and Client Sessions]]
| headers="r2c1-t4 r1c2-t4" align="left" |
[[Image:support.gif|Supported.]]<br>
| headers="r2c1-t4 r1c3-t4" align="left" |
[[Image:support.gif|Supported.]]<br>
|- align="left" valign="top"
| id="r3c1-t4" headers="r1c1-t4" align="left" |
[[Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Session Broker and Client Sessions|Session broker and client sessions ]]
| headers="r3c1-t4 r1c2-t4" align="left" |
[[Image:support.gif|Supported.]]<br>
| headers="r3c1-t4 r1c3-t4" align="left" |
[[Image:support.gif|Supported.]]<br>
|- align="left" valign="top"
| id="r4c1-t4" headers="r1c1-t4" align="left" |
[[Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Database Sessions|Database sessions]]
| headers="r4c1-t4 r1c2-t4" align="left" |
[[Image:support.gif|Supported.]]<br>
| headers="r4c1-t4 r1c3-t4" align="left" |
[[Image:support.gif|Supported.]]<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.

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.


{| class="Note oac_no_warn" width="80%" border="1" frame="hsides" rules="groups" cellpadding="3" frame="hsides" rules="groups"
| 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>.
|}


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===
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.
# Click the '''General''' tab. The General tab appears.
# Click the '''Project''' subtab. The Project subtab appears.<br><span id="Figure 85-1"></span>''''' General Tab, Project Subtab, Primary Project Option'''''<br>[[Image:sesgen.gif|General Tab, Project Subtab, Primary Project Option]]<br><br>
# Select the following options:
#* Click '''Edit''' to define the primary project. The Edit PrimaryProject dialog box appears. 
#* 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.

Use this information to enter date in each field of the Edit Primary Project dialog box:
{| class="HRuleInformal" dir="ltr" title="This table identifies each field on the dialog." summary="This table identifies each field on the dialog." width="100%" border="1" frame="hsides" rules="rows" cellpadding="3" frame="hsides" rules="rows"
|- align="left" valign="top"
! id="r1c1-t6" align="left" valign="bottom" | '''Field'''
! id="r1c2-t6" align="left" valign="bottom" | '''Description'''
|- align="left" valign="top"
| id="r2c1-t6" headers="r1c1-t6" align="left" | '''XML'''
| headers="r2c1-t6 r1c2-t6" align="left" | Select '''XML''' to add a mapping project as a deployment XML file. Click '''Browse''' to select the file.
|- align="left" valign="top"
| id="r3c1-t6" headers="r1c1-t6" align="left" | '''Class'''
| 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.
|}


===How to Configure a Primary Mapping Project Using Java===

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


<span id="Table 85-4"></span>
''''' DatabaseSession API for Registering Descriptors'''''

{| class="HRuleFormal" dir="ltr" title="DatabaseSession API for Registering Descriptors" summary="This table summarizes the various methods used to add descriptors." width="100%" border="1" frame="hsides" rules="rows" cellpadding="3" frame="hsides" rules="rows"
|- align="left" valign="top"
! id="r1c1-t7" align="left" valign="bottom" | '''Session Method'''
! id="r1c2-t7" align="left" valign="bottom" | '''Description'''
|- align="left" valign="top"
| id="r2c1-t7" headers="r1c1-t7" align="left" |
<tt>addDescriptors(Project)</tt>
| headers="r2c1-t7 r1c2-t7" align="left" |
Add to the session all the descriptors owned by the passed in <tt>Project</tt>.
|- align="left" valign="top"
| id="r3c1-t7" headers="r1c1-t7" align="left" |
<tt>addDescriptors(Vector)</tt>
| headers="r3c1-t7 r1c2-t7" align="left" |
Add to the session all the descriptors in the passed in <tt>Vector</tt>.
|- align="left" valign="top"
| id="r4c1-t7" headers="r1c1-t7" align="left" |
<tt>addDescriptor(Descriptor)</tt>
| headers="r4c1-t7 r1c2-t7" align="left" |
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.


<span id="Table 85-5"></span>
{| 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"
! id="r1c1-t8" align="left" valign="bottom" | '''Session'''
! id="r1c2-t8" align="left" valign="bottom" | '''Session Login'''
|- align="left" valign="top"
| id="r2c1-t8" headers="r1c1-t8" align="left" |
[[Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Server and Client Sessions|Server and Client Sessions]]<br>
| headers="r2c1-t8 r1c2-t8" align="left" |
[[Image:support.gif|Supported.]]<br>
|- align="left" valign="top"
| id="r3c1-t8" headers="r1c1-t8" align="left" |
[[Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Session Broker and Client Sessions|Session Broker and Client Sessions]]<br>
| headers="r3c1-t8 r1c2-t8" align="left" |
[[Image:support.gif|Supported.]]<br>
|- align="left" valign="top"
| id="r4c1-t8" headers="r1c1-t8" align="left" |
[[Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Database Sessions|Database Sessions]]<br>
| headers="r4c1-t8 r1c2-t8" align="left" |
[[Image:support.gif|Supported.]]<br>
|}

<br>

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:
* [[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 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.

<span id="Table 85-6"></span>

{| 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"
|- align="left" valign="top"
! 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="r1c3-t9" align="left" valign="bottom" | '''[[#How to Configure Logging Using Session API in Java|Using Java]]<br>'''
|- align="left" valign="top"
| id="r2c1-t9" headers="r1c1-t9" align="left" |
[[Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Server and Client Sessions|Server and client sessions ]]
| headers="r2c1-t9 r1c2-t9" align="left" |
[[Image:support.gif|Supported.]]<br>
| headers="r2c1-t9 r1c3-t9" align="left" |
[[Image:support.gif|Supported.]]<br>
|- align="left" valign="top"
| id="r3c1-t9" headers="r1c1-t9" align="left" |
[[Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Unit of Work Sessions|Unit of work sessions ]]
| headers="r3c1-t9 r1c2-t9" align="left" |
[[Image:support.gif|Supported.]]<br>
| headers="r3c1-t9 r1c3-t9" align="left" |
[[Image:support.gif|Supported.]]<br>
|- align="left" valign="top"
| id="r4c1-t9" headers="r1c1-t9" align="left" |
[[Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Session Broker and Client Sessions|Session broker and client sessions ]]
| headers="r4c1-t9 r1c2-t9" align="left" |
[[Image:support.gif|Supported.]]<br>
| headers="r4c1-t9 r1c3-t9" align="left" |
[[Image:support.gif|Supported.]]<br>
|- align="left" valign="top"
| id="r5c1-t9" headers="r1c1-t9" align="left" |
[[Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Database Sessions|Database sessions ]]
| headers="r5c1-t9 r1c2-t9" align="left" |
[[Image:support.gif|Supported.]]<br>
| headers="r5c1-t9 r1c3-t9" align="left" |
[[Image:support.gif|Supported.]]<br>
|}


{| class="Note oac_no_warn" width="80%" border="1" frame="hsides" rules="groups" cellpadding="3" frame="hsides" rules="groups"
| 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.
|}


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


===How to Configure Logging Using Workbench===
To specify the logging information for a session, use this procedure:
# 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>
# 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:
{| class="HRuleInformal" dir="ltr" title="This table identifies each field of the Logging tab" summary="This table identifies each field of the Logging tab" width="100%" border="1" frame="hsides" rules="rows" cellpadding="3" frame="hsides" rules="rows"
|- align="left" valign="top"
! id="r1c1-t11" align="left" valign="bottom" | '''Option'''
! id="r1c2-t11" align="left" valign="bottom" | '''Description'''
|- align="left" valign="top"
| id="r2c1-t11" headers="r1c1-t11" align="left" | '''No Logging'''
| headers="r2c1-t11 r1c2-t11" align="left" | Select this option to specify that nothing is logged for this session.
|- align="left" valign="top"
| id="r3c1-t11" headers="r1c1-t11" align="left" | '''Server'''
| headers="r3c1-t11 r1c2-t11" align="left" | Select this option to use logging capabilities of the application server to which you are deploying this application.
|- align="left" valign="top"
| id="r4c1-t11" headers="r1c1-t11" align="left" | '''Java'''
| headers="r4c1-t11 r1c2-t11" align="left" | Select this option to use <tt>java.util.logging</tt> package.
|- align="left" valign="top"
| id="r5c1-t11" headers="r1c1-t11" align="left" | '''Standard'''
| headers="r5c1-t11 r1c2-t11" align="left" |
Select this option to use the EclipseLink logging framework. When selected, you can optionally configure the following options.
|- align="left" valign="top"
| id="r6c1-t11" headers="r1c1-t11" align="left" | 
:'''Logging Level'''
| headers="r6c1-t11 r1c2-t11" align="left" |
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.
|- align="left" valign="top"
| 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.
|- align="left" valign="top"
| 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.
|- align="left" valign="top"
| id="r9c1-t11" headers="r1c1-t11" align="left" | '''Options'''
| 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"
| id="r10c1-t11" headers="r1c1-t11" align="left" | 
:''' Log Exception Stack Trace'''
| 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.
|- align="left" valign="top"
| id="r11c1-t11" headers="r1c1-t11" align="left" | 
:''' Print Connection'''
| 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.
|- align="left" valign="top"
| id="r12c1-t11" headers="r1c1-t11" align="left" | 
:''' Print Date'''
| 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.
|- align="left" valign="top"
| id="r13c1-t11" headers="r1c1-t11" align="left" | 
:''' Print Session'''
| 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.
|- align="left" valign="top"
| id="r14c1-t11" headers="r1c1-t11" align="left" | 
:''' Print Thread'''
| 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.
|}


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

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>dontLogMessages</tt> – disable logging
* <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>OFF</tt>
** <tt>SEVERE</tt>
** <tt>WARNING</tt>
** <tt>INFO</tt>
** <tt>CONFIG</tt>
** <tt>FINE</tt>
** <tt>FINER</tt>
** <tt>FINEST</tt>
** <tt>ALL</tt>


This example illustrates how to configure a session to use <tt>java.util.logging</tt> package.

<span id="Example 85-1"></span>
''''' 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 [[Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Server Logging|Server Logging]].

<span id="Example 85-2">
''''' Configuring a Session to Use Application Server Logging'''''
 session.setSessionLog(new OjdlLog());


This example illustrates how to configure a session to log to a <tt>java.io.Writer</tt><nowiki>:</nowiki>

<span id="Example 85-3"></span>
''''' 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 <tt>java.util.logging</tt> package, then you configure logging options in the ''<tt><JRE_HOME></tt>''<tt>/lib/logging.properties</tt> file. Messages are written to zero or multiple destinations based on this configuration file.

If you configure a session to use <tt>java.util.logging</tt> package, consider the following:
* [[#logging.properties|logging.properties]]
* [[#Formatters|Formatters]]
* [[#Namespace|Namespace]]


====logging.properties====

Configure the <tt>logging.properties</tt> file as this example illustrates:

<span id="Example 85-4"></span>
''''' java.util.logging Configuration in logging.properties'''''
<source lang="java">
 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
</source>

For information about the types of formatters available, see [[#Formatters|Formatters]].

====Formatters====

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


<span id="Table 85-7"></span>
''''' Logging Property FIle Names'''''

{| class="HRuleFormal" dir="ltr" title="Logging Property FIle Names" summary="This table identifies the name space support for each logging.properties coomponent in the SessionLog." width="100%" border="1" frame="hsides" rules="rows" cellpadding="3" frame="hsides" rules="rows"
|- align="left" valign="top"
! id="r1c1-t12" align="left" valign="bottom" | '''SessionLog'''
! id="r1c2-t12" align="left" valign="bottom" | '''logging.properites'''
|- align="left" valign="top"
| id="r2c1-t12" headers="r1c1-t12" align="left" |
Not Applicable
| headers="r2c1-t12 r1c2-t12" align="left" |
<tt>org.eclipse.persistence</tt>
|- align="left" valign="top"
| id="r3c1-t12" headers="r1c1-t12" align="left" |
Not Applicable
| headers="r3c1-t12 r1c2-t12" align="left" |
<tt>org.eclipse.persistence.<sessionname></tt>
|- align="left" valign="top"
| id="r4c1-t12" headers="r1c1-t12" align="left" |
<tt>SQL</tt>
| headers="r4c1-t12 r1c2-t12" align="left" |
<tt>org.eclipse.persistence.<sessionname>.sql</tt>
|- align="left" valign="top"
| id="r5c1-t12" headers="r1c1-t12" align="left" |
<tt>TRANSACTION</tt>
| headers="r5c1-t12 r1c2-t12" align="left" |
<tt>org.eclipse.persistence.<sessionname>.transaction</tt>
|- align="left" valign="top"
| id="r6c1-t12" headers="r1c1-t12" align="left" |
<tt>EVENT</tt>
| headers="r6c1-t12 r1c2-t12" align="left" |
<tt>org.eclipse.persistence.<sessionname>.event</tt>
|- align="left" valign="top"
| id="r7c1-t12" headers="r1c1-t12" align="left" |
<tt>CONNECTION</tt>
| headers="r7c1-t12 r1c2-t12" align="left" |
<tt>org.eclipse.persistence.<sessionname>.connection</tt>
|- align="left" valign="top"
| id="r8c1-t12" headers="r1c1-t12" align="left" |
<tt>QUERY</tt>
| headers="r8c1-t12 r1c2-t12" align="left" |
<tt>org.eclipse.persistence.<sessionname>.query</tt>
|- align="left" valign="top"
| id="r9c1-t12" headers="r1c1-t12" align="left" |
<tt>CACHE</tt>
| headers="r9c1-t12 r1c2-t12" align="left" |
<tt>org.eclipse.persistence.<sessionname>.cache</tt>
|- align="left" valign="top"
| id="r10c1-t12" headers="r1c1-t12" align="left" |
<tt>PROPAGATION</tt>
| headers="r10c1-t12 r1c2-t12" align="left" |
<tt>org.eclipse.persistence.<sessionname>.propagation</tt>
|- align="left" valign="top"
| id="r11c1-t12" headers="r1c1-t12" align="left" |
<tt>SEQUENCING</tt>
| headers="r11c1-t12 r1c2-t12" align="left" |
<tt>org.eclipse.persistence.<sessionname>.sequencing</tt>
|- align="left" valign="top"
| id="r12c1-t12" headers="r1c1-t12" align="left" |
<tt>EJB</tt>
| headers="r12c1-t12 r1c2-t12" align="left" |
<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>

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



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

This table summarizes which sessions support additional mapping project configuration.

<span id="Table 85-8"></span>

{| 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"
|- align="left" valign="top"
! id="r1c1-t13" align="left" valign="bottom" | '''Session'''
! id="r1c2-t13" align="left" valign="bottom" | '''[[#How to Configure Multiple Mapping Projects Using Workbench|Using the Workbench]]<br>'''
! id="r1c3-t13" align="left" valign="bottom" | '''[[#How to Configure Multiple Mapping Projects Using Java|Using Java]]<br>'''
|- align="left" valign="top"
| id="r2c1-t13" headers="r1c1-t13" align="left" |
[[Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Server and Client Sessions|Server and client sessions ]]
| headers="r2c1-t13 r1c2-t13" align="left" |
[[Image:support.gif|Supported.]]<br>
| headers="r2c1-t13 r1c3-t13" align="left" |
[[Image:support.gif|Supported.]]<br>
|- align="left" valign="top"
| id="r3c1-t13" headers="r1c1-t13" align="left" |
[[Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Session Broker and Client Sessions|Session Broker and Client Sessions]]
| headers="r3c1-t13 r1c2-t13" align="left" |
[[Image:support.gif|Supported.]]<br>
| headers="r3c1-t13 r1c3-t13" align="left" |
[[Image:support.gif|Supported.]]<br>
|- align="left" valign="top"
| id="r4c1-t13" headers="r1c1-t13" align="left" |
[[Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Database Sessions|Database sessions ]]
| headers="r4c1-t13 r1c2-t13" align="left" |
[[Image:support.gif|Supported.]]<br>
| headers="r4c1-t13 r1c3-t13" align="left" |
[[Image:support.gif|Supported.]]<br>
|}


===How to Configure Multiple Mapping Projects Using Workbench===

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.
# Click the '''General''' tab. The General tab appears.
# Click the '''Project''' subtab. The Project subtab appears.<br><span id="Figure 85-4 "></span>'''''General Tab, Project Subtab, Multiple Projects Options'''''<br>[[Image:sesgenad.gif|General Tab, Project Subtab, Multiple Projects Options]]<br><br>
# Select '''Multiple Projects''' option. The Multiple Projects subtab appears.
# 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>
#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'''.


===How to Configure Multiple Mapping Projects Using Java===

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


<span id="Table 85-9"></span>
''''' DatabaseSession API for Registering Descriptors'''''

{| class="HRuleFormal" dir="ltr" title="DatabaseSession API for Registering Descriptors" summary="This table summarizes the various methods used to add descriptors." width="100%" border="1" frame="hsides" rules="rows" cellpadding="3" frame="hsides" rules="rows"
|- align="left" valign="top"
! id="r1c1-t14" align="left" valign="bottom" | '''Session Method'''
! id="r1c2-t14" align="left" valign="bottom" | '''Description'''
|- align="left" valign="top"
| id="r2c1-t14" headers="r1c1-t14" align="left" |
<tt>addDescriptors(Project)</tt>
| headers="r2c1-t14 r1c2-t14" align="left" |
Add additional descriptor to the session in the form of a project.
|- align="left" valign="top"
| id="r3c1-t14" headers="r1c1-t14" align="left" |
<tt>addDescriptors(Vector)</tt>
| headers="r3c1-t14 r1c2-t14" align="left" |
Add a vector of individual descriptor files to the session in the form of a project.
|- align="left" valign="top"
| id="r4c1-t14" headers="r1c1-t14" align="left" |
<tt>addDescriptor(Descriptor)</tt>
| headers="r4c1-t14 r1c2-t14" align="left" |
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.


<span id="Table 85-10"></span>

{| 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"
|- align="left" valign="top"
! id="r1c1-t15" align="left" valign="bottom" | '''Session'''
! id="r1c2-t15" align="left" valign="bottom" | '''[[#How to Configure a Performance Profiler Using Workbench|Using the Workbench]]<br>'''
! id="r1c3-t15" align="left" valign="bottom" | '''[[#How to Configure a Performance Profiler Using Java|Using Java]]<br>'''
|- align="left" valign="top"
| id="r2c1-t15" headers="r1c1-t15" align="left" |
[[Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Server and Client Sessions|Server and client sessions ]]
| headers="r2c1-t15 r1c2-t15" align="left" |
[[Image:support.gif|Supported.]]<br>
| headers="r2c1-t15 r1c3-t15" align="left" |
[[Image:support.gif|Supported.]]<br>
|- align="left" valign="top"
| id="r3c1-t15" headers="r1c1-t15" align="left" |
[[Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Session Broker and Client Sessions|Session broker and client sessions ]]
| headers="r3c1-t15 r1c2-t15" align="left" |
[[Image:support.gif|Supported.]]<br>
| headers="r3c1-t15 r1c3-t15" align="left" |
[[Image:support.gif|Supported.]]<br>
|- align="left" valign="top"
| id="r4c1-t15" headers="r1c1-t15" align="left" |
[[Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Database Sessions|Database sessions ]]
| headers="r4c1-t15 r1c2-t15" align="left" |
[[Image:support.gif|Supported.]]<br>
| headers="r4c1-t15 r1c3-t15" align="left" |
[[Image:support.gif|Supported.]]<br>
|}


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|Measuring EclipseLink Performance with the EclipseLink Profiler]])



===How to Configure a Performance Profiler Using Workbench===

To specify the type of profiler in a session, use this procedure:
# 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>
# Complete the '''Profiler''' field on the tab.

Use the following information to select the profiler option to use with this session:
{| class="HRuleInformal" dir="ltr" title="This table identifies available the Profiler options." summary="This table identifies available the Profiler options." width="100%" border="1" frame="hsides" rules="rows" cellpadding="3" frame="hsides" rules="rows"
|- align="left" valign="top"
! id="r1c1-t16" align="left" valign="bottom" | '''Option'''
! id="r1c2-t16" align="left" valign="bottom" | '''Description'''
|- align="left" valign="top"
| id="r2c1-t16" headers="r1c1-t16" align="left" | '''No Profiler'''
| headers="r2c1-t16 r1c2-t16" align="left" | Disable all profiling.
|- align="left" valign="top"
| id="r4c1-t16" headers="r1c1-t16" align="left" | '''Standard (EclipseLink)'''
| headers="r4c1-t16 r1c2-t16" align="left" |
Enable EclipseLink profiling. For more information, see the following:
* [[Optimizing%20the%20EclipseLink%20Application%20(ELUG)#How to Configure the EclipseLink Performance Profiler|How to Configure the EclipseLink Performance Profiler]]
* [[Optimizing%20the%20EclipseLink%20Application%20(ELUG)#Measuring EclipseLink Performance with the EclipseLink Profiler|Measuring EclipseLink Performance with the EclipseLink Profiler]]
|}


===How to Configure a Performance Profiler Using Java===

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


<span id="Example 85-5"></span>
''''' Configuring a Session with an EclipseLink Profiler'''''
 session.setProfiler(new PerformanceProfiler());


To end a profiling session, use <tt>Session</tt> method <tt>clearProfiler</tt>.



==Configuring an Exception Handler==

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

This table summarizes which sessions support 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"
|- align="left" valign="top"
! id="r1c1-t17" align="left" valign="bottom" | '''Session'''
! id="r1c2-t17" align="left" valign="bottom" | '''[[#How to Configure an Exception Handler Using Workbench|Using the Workbench]]<br>'''
! id="r1c3-t17" align="left" valign="bottom" | '''[[#How to Configure an Exception Handler Using Java|Using Java]]<br>'''
|- align="left" valign="top"
| id="r2c1-t17" headers="r1c1-t17" align="left" |
[[Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Server and Client Sessions|Server and client sessions ]]
| headers="r2c1-t17 r1c2-t17" align="left" |
[[Image:support.gif|Supported.]]<br>
| headers="r2c1-t17 r1c3-t17" align="left" |
[[Image:support.gif|Supported.]]<br>
|- align="left" valign="top"
| id="r3c1-t17" headers="r1c1-t17" align="left" |
[[Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Session Broker and Client Sessions|Session broker and client sessions ]]
| headers="r3c1-t17 r1c2-t17" align="left" |
[[Image:support.gif|Supported.]]<br>
| headers="r3c1-t17 r1c3-t17" align="left" |
[[Image:support.gif|Supported.]]<br>
|- align="left" valign="top"
| id="r4c1-t17" headers="r1c1-t17" align="left" |
[[Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Database Sessions|Database sessions ]]
| headers="r4c1-t17 r1c2-t17" align="left" |
[[Image:support.gif|Supported.]]<br>
| headers="r4c1-t17 r1c3-t17" align="left" |
[[Image:support.gif|Supported.]]<br>
|}


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|Exception Handlers]].


===How to Configure an Exception Handler Using Workbench===

To specify the exception handler class in a session, use this procedure:
# Select a session in the '''Navigator'''. Its properties appear in the Editor.
# 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 '''Exception Handler''' field.
# 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 <tt>ReadQuery</tt>. Note that this exception handler either returns the result of the reexecuted <tt>ReadQuery</tt> or throws an exception.


<span id="Example 85-6"></span>
''''' Implementing an Exception Handler'''''
<source lang="java">
 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;
     }
   }
 );
</source>
<br>

{| class="Note oac_no_warn" width="80%" border="1" frame="hsides" rules="groups" cellpadding="3" frame="hsides" rules="groups"
| align="left" |
'''Note'''<nowiki>:</nowiki> 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 <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]]).

This table summarizes which sessions support 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"
|- align="left" valign="top"
! id="r1c1-t19" align="left" valign="bottom" | '''Session'''
! id="r1c2-t19" align="left" valign="bottom" | '''[[#How to Configure Customizer Class Using Workbench|Using the Workbench]]<br>'''
! id="r1c3-t19" align="left" valign="bottom" | '''How to Use Java'''
|- align="left" valign="top"
| id="r2c1-t19" headers="r1c1-t19" align="left" |
[[Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Server and Client Sessions|Server and client sessions ]]
| headers="r2c1-t19 r1c2-t19" align="left" |
[[Image:support.gif|Supported.]]<br>
| headers="r2c1-t19 r1c3-t19" align="left" |
[[Image:support.gif|Supported.]]<br>
|- align="left" valign="top"
| id="r3c1-t19" headers="r1c1-t19" align="left" |
[[Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Session Broker and Client Sessions|Session broker and client sessions ]]
| headers="r3c1-t19 r1c2-t19" align="left" |
[[Image:support.gif|Supported.]]<br>
| headers="r3c1-t19 r1c3-t19" align="left" |
[[Image:support.gif|Supported.]]<br>
|- align="left" valign="top"
| id="r4c1-t19" headers="r1c1-t19" align="left" |
[[Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Database Sessions|Database sessions ]]
| headers="r4c1-t19 r1c2-t19" align="left" |
[[Image:support.gif|Supported.]]<br>
| headers="r4c1-t19 r1c3-t19" align="left" |
[[Image:support.gif|Supported.]]<br>
|}


For more information, see [[Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Session Customization|Session Customization]].


===How to Configure Customizer Class Using Workbench===

To specify the session customizer class in a session, use this procedure:
# Select a session in the '''Navigator'''. Its properties appear in the Editor.
# 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 '''Session Customizer Class''' field.
#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 <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>
''''' Creating a SessionCustomizer Class'''''
<source lang="java">
 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);
     }
 }
</source>

==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 [[Introduction%20to%20EclipseLink%20Transactions (ELUG)#Unit of Work Transaction Demarcation|Unit of Work Transaction Demarcation]].

This table summarizes which sessions support a server platform.


<span id="Table 85-13"></span>
''''' 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"
|- align="left" valign="top"
! id="r1c1-t20" align="left" valign="bottom" | '''Session'''
! id="r1c2-t20" align="left" valign="bottom" | '''[[#How to Configure the Server Platform Using Workbench|Using the Workbench]]<br>'''
! id="r1c3-t20" align="left" valign="bottom" | '''[[#How to Configure the Server Platform Using Java|Using Java]]<br>'''
|- align="left" valign="top"
| id="r2c1-t20" headers="r1c1-t20" align="left" |
[[Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Server and Client Sessions|Server and client sessions ]]
| headers="r2c1-t20 r1c2-t20" align="left" |
[[Image:support.gif|Supported.]]<br>
| headers="r2c1-t20 r1c3-t20" align="left" |
[[Image:support.gif|Supported.]]<br>
|- align="left" valign="top"
| id="r3c1-t20" headers="r1c1-t20" align="left" |
[[Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Session Broker and Client Sessions|Session broker and client sessions ]]
| headers="r3c1-t20 r1c2-t20" align="left" |
[[Image:support.gif|Supported.]]<br>
| headers="r3c1-t20 r1c3-t20" align="left" |
[[Image:support.gif|Supported.]]<br>
|- align="left" valign="top"
| id="r4c1-t20" headers="r1c1-t20" align="left" |
[[Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Database Sessions|Database sessions ]]
| headers="r4c1-t20 r1c2-t20" align="left" |
[[Image:support.gif|Supported.]]<br>
| headers="r4c1-t20 r1c3-t20" align="left" |
[[Image:support.gif|Supported.]]<br>
|}


===How to Configure the Server Platform Using Workbench===
To specify the server platform options for a session, use this procedure:
# Select a session in the '''Navigator'''. Its properties appear in the Editor.
# Click the '''General''' tab. The General tab appears.
# 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 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"
|- align="left" valign="top"
! id="r1c1-t21" align="left" valign="bottom" | '''Field'''
! id="r1c2-t21" align="left" valign="bottom" | '''Description'''
|- align="left" valign="top"
| id="r2c1-t21" headers="r1c1-t21" align="left" | '''Server Platform'''
| 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'''.
|- align="left" valign="top"
| id="r3c1-t21" headers="r1c1-t21" align="left" | 
:'''Platform'''
| 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:
* OC4J 10.1.3
* SunAS 9
* WebLogic 10.3
* WebLogic 10
* WebLogic 9.0
* WebSphere 6.1
* [[EclipseLink/Examples/JPA/JBoss_Web_Tutorial|JBoss 4.2.2]]
* 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"
| id="r4c1-t21" headers="r1c1-t21" align="left" | 
:'''Enable Runtime Services'''
| 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. 


|- align="left" valign="top"
| id="r5c1-t21" headers="r1c1-t21" align="left" | 
:'''Enable External Transaction Controller (JTA)'''
| 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 (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"
| id="r6c1-t21" headers="r1c1-t21" align="left" | 
:'''Server Platform Class'''
| 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.
|- align="left" valign="top"
| id="r7c1-t21" headers="r1c1-t21" align="left" | 
:'''Transaction Controller Class (JTA)'''
| 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.
|}

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


<span id="Example 85-8"></span>
''''' Configuring a Session with a Server Platform'''''
<source lang="java">
 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)):
    }
 }
</source>

==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]].

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


<span id="Table 85-14"></span>
'''''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"
|- align="left" valign="top"
! id="r1c1-t22" align="left" valign="bottom" | '''Session'''
! id="r1c2-t22" align="left" valign="bottom" | '''[[#How to Configure Session Event Listeners Using Workbench|Using the Workbench]]<br>'''
! id="r1c3-t22" align="left" valign="bottom" | '''[[#How to Configure Session Event Listeners Using Java|Using Java]]<br>'''
|- align="left" valign="top"
| id="r2c1-t22" headers="r1c1-t22" align="left" |
[[Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Server and Client Sessions|Server and client sessions ]]
| headers="r2c1-t22 r1c2-t22" align="left" |
[[Image:support.gif|Supported.]]<br>
| headers="r2c1-t22 r1c3-t22" align="left" |
[[Image:support.gif|Supported.]]<br>
|- align="left" valign="top"
| id="r3c1-t22" headers="r1c1-t22" align="left" |
[[Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Session Broker and Client Sessions|Session broker and client sessions ]]
| headers="r3c1-t22 r1c2-t22" align="left" |
[[Image:support.gif|Supported.]]<br>
| headers="r3c1-t22 r1c3-t22" align="left" |
[[Image:support.gif|Supported.]]<br>
|- align="left" valign="top"
| id="r4c1-t22" headers="r1c1-t22" align="left" |
[[Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Database Sessions|Database sessions ]]
| headers="r4c1-t22 r1c2-t22" align="left" |
[[Image:support.gif|Supported.]]<br>
| headers="r4c1-t22 r1c3-t22" align="left" |
[[Image:support.gif|Supported.]]<br>
|}


===How to Configure Session Event Listeners Using Workbench===

'''Session Event Listeners'''

To specify the event listener class in a session, use this procedure:
# 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>
#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===
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]].


<span id="Example 85-9"></span>
''''' Using the Session Event Adapter to Create a Session Event Listener'''''
<source lang="java">
 ...
 SessionEventAdapter myEventListener = new SessionEventAdapter() {
     // Listen for PostCommitUnitOfWork events
     public void postCommitUnitOfWork(SessionEvent event) {
         // Call the handler routine
         unitOfWorkCommitted();
     }
 };
 mySession.getEventManager().addListener(myEventListener);
 ...
</source>


For information on how to add logging to your listeners, see [[Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Logging|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:
* [[#Check Database|Check Database]]
* [[#Catch All Exceptions|Catch All Exceptions]]
* [[#Catch Instantiation Policy Exceptions|Catch Instantiation Policy Exceptions]]

This table summarizes which sessions support descriptor integrity checking configuration.

<span id="Table 85-15"></span>
''''' Session Support for Checking Descriptor Integrity'''''
{| class="RuleFormal" dir="ltr" title="Session Support for Checking Descriptor Integrity" 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"
! id="r1c1-t23" align="left" valign="bottom" | '''Session'''
! 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>'''
|- align="left" valign="top"
| id="r2c1-t23" headers="r1c1-t23" align="left" |
[[Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Server and Client Sessions|Server and client sessions ]]
| headers="r2c1-t23 r1c2-t23" align="left" |
[[Image:unsupport.gif|Unsupported]]<br>
| headers="r2c1-t23 r1c3-t23" align="left" |
[[Image:support.gif|Supported.]]<br>
|- align="left" valign="top"
| id="r3c1-t23" headers="r1c1-t23" align="left" |
[[Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Session Broker and Client Sessions|Session broker and client sessions ]]
| headers="r3c1-t23 r1c2-t23" align="left" |
[[Image:unsupport.gif|Unsupported]]<br>
| headers="r3c1-t23 r1c3-t23" align="left" |
[[Image:support.gif|Supported.]]<br>
|- align="left" valign="top"
| id="r4c1-t23" headers="r1c1-t23" align="left" |
[[Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Database Sessions|Database sessions ]]
| headers="r4c1-t23 r1c2-t23" align="left" |
[[Image:unsupport.gif|Unsupported]]<br>
| headers="r4c1-t23 r1c3-t23" align="left" |
[[Image:support.gif|Supported.]]<br>
|}


'''Check Database'''

The <tt>IntegrityChecker</tt> method <tt>setShouldCheckDatabase</tt> 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 <tt>IntegrityChecker</tt> method <tt>setShouldCatchExceptions(false)</tt>.


'''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 <tt>IntegrityChecker</tt> method <tt>setShouldCheckInstantiationPolicy(false)</tt>.


===How to Configure the Integrity Checker Using Java===

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

<span id="Example 85-10"></span>
''''' Configuring the Integrity Checker'''''
<source lang="java">
 session.getIntegrityChecker().setShouldCheckDatabase(true);
 session.getIntegrityChecker().setShouldCatchExceptions(false);
 session.getIntegrityChecker().setShouldCheckInstantiationPolicy(false);
 session.login();
</source>


==Configuring Connection Policy==

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]]
* [[#Lazy Connection Acquisition|Lazy Connection Acquisition]]

This table summarizes which sessions support connection policy configuration.


<span id="Table 85-16"></span>
''''' Session Support for Connection Policy'''''

{| class="RuleFormal" dir="ltr" title="Session Support for Connection Policy" 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"
! id="r1c1-t24" align="left" valign="bottom" | '''Session'''
! id="r1c2-t24" align="left" valign="bottom" | '''[[#How to Configure Connection Policy Using Workbench|Using Workbench]]<br>'''
! id="r1c3-t24" align="left" valign="bottom" | '''[[#How to Configure Connection Policy Using Java|Using Java]]<br>'''
|- align="left" valign="top"
| id="r2c1-t24" headers="r1c1-t24" align="left" |
[[Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Server and Client Sessions|Server and client sessions ]]
| headers="r2c1-t24 r1c2-t24" align="left" |
[[Image:support.gif|Supported.]]<br>
| headers="r2c1-t24 r1c3-t24" align="left" |
[[Image:support.gif|Supported.]]<br>
|- align="left" valign="top"
| id="r3c1-t24" headers="r1c1-t24" align="left" |
[[Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Session Broker and Client Sessions|Session broker and client sessions ]]
| headers="r3c1-t24 r1c2-t24" align="left" |
[[Image:unsupport.gif|Unsupported]]<br>
| headers="r3c1-t24 r1c3-t24" align="left" |
[[Image:unsupport.gif|Unsupported]]<br>
|- align="left" valign="top"
| id="r4c1-t24" headers="r1c1-t24" align="left" |
[[Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Database Sessions|Database sessions ]]
| headers="r4c1-t24 r1c2-t24" align="left" |
[[Image:unsupport.gif|Unsupported]]<br>
| headers="r4c1-t24 r1c3-t24" align="left" |
[[Image:unsupport.gif|Unsupported]]<br>
|}


'''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 [[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|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]]).


{| class="Note oac_no_warn" width="80%" border="1" frame="hsides" rules="groups" cellpadding="3" frame="hsides" rules="groups"
| 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. 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 [[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===

To specify the connection policy in a session, use this procedure:
# 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>


===How to Configure Connection Policy Using Java===

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:

* <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>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|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, 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%20a%20Descriptor%20(ELUG)#Configuring Named Queries at the Descriptor Level|Configuring Named Queries at the Descriptor Level]]).

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

This table summarizes which sessions support named query configuration.


<span id="Table 85-17"></span>

{| 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"
! id="r1c1-t26" align="left" valign="bottom" | '''Session'''
! 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>'''
|- align="left" valign="top"
| id="r2c1-t26" headers="r1c1-t26" align="left" |
[[Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Server and Client Sessions|Server and client sessions ]]
| headers="r2c1-t26 r1c2-t26" align="left" |
[[Image:unsupport.gif|Unsupported]]<br>
| headers="r2c1-t26 r1c3-t26" align="left" |
[[Image:support.gif|Supported.]]<br>
|- align="left" valign="top"
| id="r3c1-t26" headers="r1c1-t26" align="left" |
[[Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Session Broker and Client Sessions|Session broker and client sessions ]]
| headers="r3c1-t26 r1c2-t26" align="left" |
[[Image:unsupport.gif|Unsupported]]<br>
| headers="r3c1-t26 r1c3-t26" align="left" |
[[Image:support.gif|Supported.]]<br>
|- align="left" valign="top"
| id="r4c1-t26" headers="r1c1-t26" align="left" |
[[Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Database Sessions|Database sessions ]]
| headers="r4c1-t26 r1c2-t26" align="left" |
[[Image:unsupport.gif|Unsupported]]<br>
| headers="r4c1-t26 r1c3-t26" align="left" |
[[Image:support.gif|Supported.]]<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]]).

For more information about named queries, see [[Introduction%20to%20EclipseLink%20Queries%20(ELUG)#Named Queries|Named Queries]].


===How to Configure Named Queries at the Session Level Using Java===

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




----
''[[EclipseLink User's Guide Copyright Statement|Copyright Statement]]''


[[Category: EclipseLink User's Guide]]
[[Category: Release 1]]
[[Category: Task]]