Skip to main content
Jump to: navigation, search

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

m (How to Configure Inheritance for a Parent (Root) Descriptor Using Java)
m (How to Configure Query Keys Using Java)
 
(48 intermediate revisions by 6 users not shown)
Line 2: Line 2:
 
[[Special:Whatlinkshere/Configuring a Descriptor (ELUG)|Related Topics]]</div>This section describes how to configure EclipseLink project options common to two or more project types.
 
[[Special:Whatlinkshere/Configuring a Descriptor (ELUG)|Related Topics]]</div>This section describes how to configure EclipseLink project options common to two or more project types.
  
[[#Table 115-1|Configuring EclipseLink Descriptor]] lists the types of EclipseLink descriptors that you can configure and provides a cross-reference to the type-specific chapter that lists the configurable options supported by that type.
+
The following table lists the types of EclipseLink descriptors 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 115-1"></span>
 
<span id="Table 115-1"></span>
''''' Configuring EclipseLink Descriptor'''''
 
 
{| class="RuleFormal" dir="ltr" title="Configuring EclipseLink Descriptor" summary="This table provides a cross-reference to additional descriptor configuration options." width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
 
{| class="RuleFormal" dir="ltr" title="Configuring EclipseLink Descriptor" summary="This table provides a cross-reference to additional descriptor configuration options." width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
 
|- align="left" valign="top"
 
|- align="left" valign="top"
Line 35: Line 34:
 
<br>
 
<br>
  
[[#Table 115-2|Common Descriptor Options]] lists the configurable options shared by two or more EclipseLink descriptor types.
+
The [[#Table 115-2|Common Descriptor Options]] table lists the configurable options shared by two or more EclipseLink descriptor types.
 
+
For more information, see the following:
+
  
 +
For more information, see:
 
* [[Creating%20a%20Descriptor%20(ELUG)|Introduction to Descriptor Creation]]
 
* [[Creating%20a%20Descriptor%20(ELUG)|Introduction to Descriptor Creation]]
 
* [[Introduction%20to%20Descriptors%20(ELUG)|Introduction to Descriptors]]
 
* [[Introduction%20to%20Descriptors%20(ELUG)|Introduction to Descriptors]]
Line 45: Line 43:
  
 
==Configuring Common Descriptor Options==
 
==Configuring Common Descriptor Options==
 
+
This table lists the configurable options shared by two or more EclipseLink descriptor types. In addition to the configurable options described here, you must also configure the options described for the specific [[Introduction%20to%20Descriptors%20(ELUG)#Descriptor Types|Descriptor Types]], as shown in the [[#Table 115-1|Configuring EclipseLink Descriptor]] table.
[[#Table 115-2|Common Descriptor Options]] lists the configurable options shared by two or more EclipseLink descriptor types. In addition to the configurable options described here, you must also configure the options described for the specific [[Introduction%20to%20Descriptors%20(ELUG)|Descriptor Types]], as shown in [[#Table 115-1|Configuring EclipseLink Descriptor]].
+
  
  
 
<span id="Table 115-2"></span>
 
<span id="Table 115-2"></span>
''''' Common Descriptor Options'''''
 
 
 
{| class="RuleFormalMax" dir="ltr" title="Common Descriptor Options" summary="This table lists the configurable options common to descriptors" width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
 
{| class="RuleFormalMax" dir="ltr" title="Common Descriptor Options" summary="This table lists the configurable options common to descriptors" width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
 
|- align="left" valign="top"
 
|- align="left" valign="top"
Line 59: Line 54:
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r2c1-t3" headers="r1c1-t3" align="left" |
 
| id="r2c1-t3" headers="r1c1-t3" align="left" |
Primary keys (see [[#Configuring Primary Keys]])
+
[[#Configuring Primary Keys|Primary keys]]
 
| headers="r2c1-t3 r1c2-t3" align="left" |
 
| headers="r2c1-t3 r1c2-t3" align="left" |
 
[[Image:support.gif|Supported]]<br>
 
[[Image:support.gif|Supported]]<br>
Line 66: Line 61:
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r3c1-t3" headers="r1c1-t3" align="left" |
 
| id="r3c1-t3" headers="r1c1-t3" align="left" |
Read-only (see [[#Configuring Read-Only Descriptors]])
+
[[#Configuring Read-Only Descriptors|Read-only ]]
 
| headers="r3c1-t3 r1c2-t3" align="left" |
 
| headers="r3c1-t3 r1c2-t3" align="left" |
 
[[Image:support.gif|Supported]]<br>
 
[[Image:support.gif|Supported]]<br>
Line 73: Line 68:
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r4c1-t3" headers="r1c1-t3" align="left" |
 
| id="r4c1-t3" headers="r1c1-t3" align="left" |
Unit of work conforming (see [[#Configuring Unit of Work Conforming at the Descriptor Level]])
+
[[#Configuring Unit of Work Conforming at the Descriptor Level|Unit of work conforming ]]
 
| headers="r4c1-t3 r1c2-t3" align="left" |
 
| headers="r4c1-t3 r1c2-t3" align="left" |
 
[[Image:support.gif|Supported]]<br>
 
[[Image:support.gif|Supported]]<br>
Line 80: Line 75:
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r5c1-t3" headers="r1c1-t3" align="left" |
 
| id="r5c1-t3" headers="r1c1-t3" align="left" |
Alias (see [[#Configuring Descriptor Alias]])
+
[[#Configuring Descriptor Alias|Alias ]]
 
| headers="r5c1-t3 r1c2-t3" align="left" |
 
| headers="r5c1-t3 r1c2-t3" align="left" |
 
[[Image:support.gif|Supported]]<br>
 
[[Image:support.gif|Supported]]<br>
Line 87: Line 82:
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r6c1-t3" headers="r1c1-t3" align="left" |
 
| id="r6c1-t3" headers="r1c1-t3" align="left" |
Comments (see [[#Configuring Descriptor Comments]])
+
[[#Configuring Descriptor Comments|Comments ]]
 
| headers="r6c1-t3 r1c2-t3" align="left" |
 
| headers="r6c1-t3 r1c2-t3" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
| headers="r6c1-t3 r1c3-t3" align="left" |
 
| headers="r6c1-t3 r1c3-t3" align="left" |
Unsupported<br>
+
[[Image:unsupport.gif|Unsupported]]<br>
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r7c1-t3" headers="r1c1-t3" align="left" |
 
| id="r7c1-t3" headers="r1c1-t3" align="left" |
Classes (see [[Using%20Workbench%20(ELUG)|How to Configure Classes]])
+
[[Using%20Workbench%20(ELUG)#How to Configure Classes|Classes]]
 
| headers="r7c1-t3 r1c2-t3" align="left" |
 
| headers="r7c1-t3 r1c2-t3" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
| headers="r7c1-t3 r1c3-t3" align="left" |
 
| headers="r7c1-t3 r1c3-t3" align="left" |
Unsupported<br>
+
[[Image:unsupport.gif|Unsupported]]<br>
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r8c1-t3" headers="r1c1-t3" align="left" |
 
| id="r8c1-t3" headers="r1c1-t3" align="left" |
Named queries (see [[#Configuring Named Queries at the Descriptor Level]])
+
[[#Configuring Named Queries at the Descriptor Level|Named queries ]]
 
| headers="r8c1-t3 r1c2-t3" align="left" |
 
| headers="r8c1-t3 r1c2-t3" align="left" |
 
[[Image:support.gif|Supported]]<br>
 
[[Image:support.gif|Supported]]<br>
Line 108: Line 103:
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r9c1-t3" headers="r1c1-t3" align="left" |
 
| id="r9c1-t3" headers="r1c1-t3" align="left" |
Query timeout (see [[#Configuring Query Timeout at the Descriptor Level]])
+
[[#Configuring Query Timeout at the Descriptor Level|Query timeout ]]
 
| headers="r9c1-t3 r1c2-t3" align="left" |
 
| headers="r9c1-t3 r1c2-t3" align="left" |
 
[[Image:support.gif|Supported]]<br>
 
[[Image:support.gif|Supported]]<br>
Line 115: Line 110:
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r10c1-t3" headers="r1c1-t3" align="left" |
 
| id="r10c1-t3" headers="r1c1-t3" align="left" |
Cache refreshing (see [[#Configuring Cache Refreshing]])
+
[[#Configuring Cache Refreshing|Cache refreshing ]]
 
| headers="r10c1-t3 r1c2-t3" align="left" |
 
| headers="r10c1-t3 r1c2-t3" align="left" |
 
[[Image:support.gif|Supported]]<br>
 
[[Image:support.gif|Supported]]<br>
Line 122: Line 117:
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r11c1-t3" headers="r1c1-t3" align="left" |
 
| id="r11c1-t3" headers="r1c1-t3" align="left" |
Query keys (see [[#Configuring Query Keys]])
+
[[#Configuring Query Keys|Query keys ]]
 
| headers="r11c1-t3 r1c2-t3" align="left" |
 
| headers="r11c1-t3 r1c2-t3" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
| headers="r11c1-t3 r1c3-t3" align="left" |
 
| headers="r11c1-t3 r1c3-t3" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r12c1-t3" headers="r1c1-t3" align="left" |
 
| id="r12c1-t3" headers="r1c1-t3" align="left" |
Interface query keys (see [[#Configuring Interface Query Keys]])
+
[[#Configuring Interface Query Keys|Interface query keys ]]
 
| headers="r12c1-t3 r1c2-t3" align="left" |
 
| headers="r12c1-t3 r1c2-t3" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
| headers="r12c1-t3 r1c3-t3" align="left" |
 
| headers="r12c1-t3 r1c3-t3" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r13c1-t3" headers="r1c1-t3" align="left" |
 
| id="r13c1-t3" headers="r1c1-t3" align="left" |
Cache type and size (see [[#Configuring Cache Type and Size at the Descriptor Level]])
+
[[#Configuring Cache Type and Size at the Descriptor Level|Cache type and size ]]
 
| headers="r13c1-t3 r1c2-t3" align="left" |
 
| headers="r13c1-t3 r1c2-t3" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
| headers="r13c1-t3 r1c3-t3" align="left" |
 
| headers="r13c1-t3 r1c3-t3" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r14c1-t3" headers="r1c1-t3" align="left" |
 
| id="r14c1-t3" headers="r1c1-t3" align="left" |
Cache isolation (see [[#Configuring Cache Isolation at the Descriptor Level]])
+
[[#Configuring Cache Isolation at the Descriptor Level|Cache isolation ]]
 
| headers="r14c1-t3 r1c2-t3" align="left" |
 
| headers="r14c1-t3 r1c2-t3" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
| headers="r14c1-t3 r1c3-t3" align="left" |
 
| headers="r14c1-t3 r1c3-t3" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r15c1-t3" headers="r1c1-t3" align="left" |
 
| id="r15c1-t3" headers="r1c1-t3" align="left" |
Unit of work cache isolation (see [[#Configuring Unit of Work Cache Isolation at the Descriptor Level]])
+
[[#Configuring Unit of Work Cache Isolation at the Descriptor Level|Unit of work cache isolation ]]
 
| headers="r15c1-t3 r1c2-t3" align="left" |
 
| headers="r15c1-t3 r1c2-t3" align="left" |
Unsupported<br>
+
[[Image:unsupport.gif|Unsupported]]<br>
 
| headers="r15c1-t3 r1c3-t3" align="left" |
 
| headers="r15c1-t3 r1c3-t3" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r16c1-t3" headers="r1c1-t3" align="left" |
 
| id="r16c1-t3" headers="r1c1-t3" align="left" |
Cache coordination change propagation (see [[#Configuring Cache Coordination Change Propagation at the Descriptor Level]])
+
[[#Configuring Cache Coordination Change Propagation at the Descriptor Level|Cache coordination change propagation ]]
 
| headers="r16c1-t3 r1c2-t3" align="left" |
 
| headers="r16c1-t3 r1c2-t3" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
| headers="r16c1-t3 r1c3-t3" align="left" |
 
| headers="r16c1-t3 r1c3-t3" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r17c1-t3" headers="r1c1-t3" align="left" |
 
| id="r17c1-t3" headers="r1c1-t3" align="left" |
Cache expiration (see [[#Configuring Cache Expiration at the Descriptor Level]])
+
[[#Configuring Cache Expiration at the Descriptor Level|Cache expiration ]]
 
| headers="r17c1-t3 r1c2-t3" align="left" |
 
| headers="r17c1-t3 r1c2-t3" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
| headers="r17c1-t3 r1c3-t3" align="left" |
 
| headers="r17c1-t3 r1c3-t3" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r18c1-t3" headers="r1c1-t3" align="left" |
 
| id="r18c1-t3" headers="r1c1-t3" align="left" |
Cache existence checking (see [[#Configuring Cache Existence Checking at the Descriptor Level]])
+
[[#Configuring Cache Existence Checking at the Descriptor Level|Cache existence checking ]]
 
| headers="r18c1-t3 r1c2-t3" align="left" |
 
| headers="r18c1-t3 r1c2-t3" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
| headers="r18c1-t3 r1c3-t3" align="left" |
 
| headers="r18c1-t3 r1c3-t3" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r19c1-t3" headers="r1c1-t3" align="left" |
 
| id="r19c1-t3" headers="r1c1-t3" align="left" |
Reading subclasses on queries (see [[#Configuring Reading Subclasses on Queries]])
+
[[#Configuring Reading Subclasses on Queries|Reading subclasses on queries ]]
 
| headers="r19c1-t3 r1c2-t3" align="left" |
 
| headers="r19c1-t3 r1c2-t3" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
| headers="r19c1-t3 r1c3-t3" align="left" |
 
| headers="r19c1-t3 r1c3-t3" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r20c1-t3" headers="r1c1-t3" align="left" |
 
| id="r20c1-t3" headers="r1c1-t3" align="left" |
Inheritance for a child class descriptor (see [[#Configuring Inheritance for a Child (Branch or Leaf) Class Descriptor]])
+
[[#Configuring Inheritance for a Child (Branch or Leaf) Class Descriptor|Inheritance for a child class descriptor ]]
 
| headers="r20c1-t3 r1c2-t3" align="left" |
 
| headers="r20c1-t3 r1c2-t3" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
| headers="r20c1-t3 r1c3-t3" align="left" |
 
| headers="r20c1-t3 r1c3-t3" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r21c1-t3" headers="r1c1-t3" align="left" |
 
| id="r21c1-t3" headers="r1c1-t3" align="left" |
Inheritance for a parent class descriptor (see [[#Configuring Inheritance for a Parent (Root) Descriptor]])
+
[[#Configuring Inheritance for a Parent (Root) Descriptor|Inheritance for a parent class descriptor ]]
 
| headers="r21c1-t3 r1c2-t3" align="left" |
 
| headers="r21c1-t3 r1c2-t3" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
| headers="r21c1-t3 r1c3-t3" align="left" |
 
| headers="r21c1-t3 r1c3-t3" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r22c1-t3" headers="r1c1-t3" align="left" |
 
| id="r22c1-t3" headers="r1c1-t3" align="left" |
Inheritance expressions for a parent class descriptor (see [[#Configuring Inheritance Expressions for a Parent (Root) Class Descriptor]])
+
[[#Configuring Inheritance Expressions for a Parent (Root) Class Descriptor|Inheritance expressions for a parent class descriptor ]]
 
| headers="r22c1-t3 r1c2-t3" align="left" |
 
| headers="r22c1-t3 r1c2-t3" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
| headers="r22c1-t3 r1c3-t3" align="left" |
 
| headers="r22c1-t3 r1c3-t3" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r23c1-t3" headers="r1c1-t3" align="left" |
 
| id="r23c1-t3" headers="r1c1-t3" align="left" |
Inherited attribute mapping in a subclass (see [[#Configuring Inherited Attribute Mapping in a Subclass]])
+
[[#Configuring Inherited Attribute Mapping in a Subclass|Inherited attribute mapping in a subclass ]]
 
| headers="r23c1-t3 r1c2-t3" align="left" |
 
| headers="r23c1-t3 r1c2-t3" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
| headers="r23c1-t3 r1c3-t3" align="left" |
 
| headers="r23c1-t3 r1c3-t3" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r24c1-t3" headers="r1c1-t3" align="left" |
 
| id="r24c1-t3" headers="r1c1-t3" align="left" |
Domain object method as an event handler (see [[#Configuring a Domain Object Method as an Event Handler]])
+
[[#Configuring a Domain Object Method as an Event Handler|Domain object method as an event handler ]]
 
| headers="r24c1-t3 r1c2-t3" align="left" |
 
| headers="r24c1-t3 r1c2-t3" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
| headers="r24c1-t3 r1c3-t3" align="left" |
 
| headers="r24c1-t3 r1c3-t3" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r25c1-t3" headers="r1c1-t3" align="left" |
 
| id="r25c1-t3" headers="r1c1-t3" align="left" |
Descriptor event listener as an event handler (see [[#Configuring a Descriptor Event Listener as an Event Handler]])
+
[[#Configuring a Descriptor Event Listener as an Event Handler|Descriptor event listener as an event handler ]]
 
| headers="r25c1-t3 r1c2-t3" align="left" |
 
| headers="r25c1-t3 r1c2-t3" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
| headers="r25c1-t3 r1c3-t3" align="left" |
 
| headers="r25c1-t3 r1c3-t3" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r26c1-t3" headers="r1c1-t3" align="left" |
 
| id="r26c1-t3" headers="r1c1-t3" align="left" |
Locking policy (see [[#Configuring Locking Policy]])
+
[[#Configuring Locking Policy|Locking policy ]]
 
| headers="r26c1-t3 r1c2-t3" align="left" |
 
| headers="r26c1-t3 r1c2-t3" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
| headers="r26c1-t3 r1c3-t3" align="left" |
 
| headers="r26c1-t3 r1c3-t3" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r27c1-t3" headers="r1c1-t3" align="left" |
 
| id="r27c1-t3" headers="r1c1-t3" align="left" |
Returning policy (see [[#Configuring Returning Policy]])
+
[[#Configuring Returning Policy|Returning policy ]]
 
| headers="r27c1-t3 r1c2-t3" align="left" |
 
| headers="r27c1-t3 r1c2-t3" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
| headers="r27c1-t3 r1c3-t3" align="left" |
 
| headers="r27c1-t3 r1c3-t3" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r28c1-t3" headers="r1c1-t3" align="left" |
 
| id="r28c1-t3" headers="r1c1-t3" align="left" |
Instantiation policy (see [[#Configuring Instantiation Policy]])
+
[[#Configuring Instantiation Policy|Instantiation policy ]]
 
| headers="r28c1-t3 r1c2-t3" align="left" |
 
| headers="r28c1-t3 r1c2-t3" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
| headers="r28c1-t3 r1c3-t3" align="left" |
 
| headers="r28c1-t3 r1c3-t3" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r29c1-t3" headers="r1c1-t3" align="left" |
 
| id="r29c1-t3" headers="r1c1-t3" align="left" |
Copy policy (see [[#Configuring Copy Policy]])
+
[[#Configuring Copy Policy|Copy policy ]]
 
| headers="r29c1-t3 r1c2-t3" align="left" |
 
| headers="r29c1-t3 r1c2-t3" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
| headers="r29c1-t3 r1c3-t3" align="left" |
 
| headers="r29c1-t3 r1c3-t3" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r30c1-t3" headers="r1c1-t3" align="left" |
 
| id="r30c1-t3" headers="r1c1-t3" align="left" |
Change policy (see [[#Configuring Change Policy]])
+
[[#Configuring Change Policy|Change policy ]]
 
| headers="r30c1-t3 r1c2-t3" align="left" |
 
| headers="r30c1-t3 r1c2-t3" align="left" |
Unsupported<br>
+
[[Image:unsupport.gif|Unsupported]]<br>
 
| headers="r30c1-t3 r1c3-t3" align="left" |
 
| headers="r30c1-t3 r1c3-t3" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r31c1-t3" headers="r1c1-t3" align="left" |
 
| id="r31c1-t3" headers="r1c1-t3" align="left" |
History policy (see [[#Configuring a History Policy]])
+
[[#Configuring a History Policy|History policy ]]
 
| headers="r31c1-t3 r1c2-t3" align="left" |
 
| headers="r31c1-t3 r1c2-t3" align="left" |
Unsupported<br>
+
[[Image:unsupport.gif|Unsupported]]<br>
 
| headers="r31c1-t3 r1c3-t3" align="left" |
 
| headers="r31c1-t3 r1c3-t3" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r32c1-t3" headers="r1c1-t3" align="left" |
 
| id="r32c1-t3" headers="r1c1-t3" align="left" |
Wrapper policy (see [[#Configuring Wrapper Policy]])
+
[[#Configuring Wrapper Policy|Wrapper policy ]]
 
| headers="r32c1-t3 r1c2-t3" align="left" |
 
| headers="r32c1-t3 r1c2-t3" align="left" |
Unsupported<br>
+
[[Image:unsupport.gif|Unsupported]]<br>
 
| headers="r32c1-t3 r1c3-t3" align="left" |
 
| headers="r32c1-t3 r1c3-t3" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r33c1-t3" headers="r1c1-t3" align="left" |
 
| id="r33c1-t3" headers="r1c1-t3" align="left" |
Fetch groups (see [[#Configuring Fetch Groups]])
+
[[#Configuring Fetch Groups|Fetch groups ]]
 
| headers="r33c1-t3 r1c2-t3" align="left" |
 
| headers="r33c1-t3 r1c2-t3" align="left" |
Unsupported<br>
+
[[Image:unsupport.gif|Unsupported]]<br>
 
| headers="r33c1-t3 r1c3-t3" align="left" |
 
| headers="r33c1-t3 r1c3-t3" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r34c1-t3" headers="r1c1-t3" align="left" |
 
| id="r34c1-t3" headers="r1c1-t3" align="left" |
Amendment methods (see [[#Configuring Amendment Methods]])
+
[[#Configuring Amendment Methods|Amendment methods ]]
 
| headers="r34c1-t3 r1c2-t3" align="left" |
 
| headers="r34c1-t3 r1c2-t3" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
| headers="r34c1-t3 r1c3-t3" align="left" |
 
| headers="r34c1-t3 r1c3-t3" align="left" |
Unsupported<br>
+
[[Image:unsupport.gif|Unsupported]]<br>
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r35c1-t3" headers="r1c1-t3" align="left" |
 
| id="r35c1-t3" headers="r1c1-t3" align="left" |
Mapping (see [[Configuring%20a%20Mapping%20(ELUG)|Configuring a Mapping]])
+
[[Configuring%20a%20Mapping%20(ELUG)#Configuring a Mapping|Mappings ]]
 
| headers="r35c1-t3 r1c2-t3" align="left" |
 
| headers="r35c1-t3 r1c2-t3" align="left" |
 
[[Image:support.gif|Supported]]<br>
 
[[Image:support.gif|Supported]]<br>
Line 297: Line 292:
 
|}
 
|}
  
<br>
 
  
==Configuring Primary Keys==
 
  
 +
 +
==Configuring Primary Keys==
 
A '''primary key''' is a unique identifier (made up of one or more persistent attributes) that distinguishes one instance of a class from all other instances of the same type. You use primary keys to define relationships and to define queries.
 
A '''primary key''' is a unique identifier (made up of one or more persistent attributes) that distinguishes one instance of a class from all other instances of the same type. You use primary keys to define relationships and to define queries.
  
For the descriptors shown in [[#Table 115-3|Descriptor Support for Primary Keys]], you must configure a primary key and you must ensure that your class contains one or more persistent fields suitable for this purpose.
+
For the descriptors shown in the [[#Table 115-3|Descriptor Support for Primary Keys]] table, you must configure a primary key and you must ensure that your class contains one or more persistent fields suitable for this purpose.
  
 
This table summarizes which descriptors support primary keys.
 
This table summarizes which descriptors support primary keys.
Line 309: Line 304:
  
 
<span id="Table 115-3"></span>
 
<span id="Table 115-3"></span>
''''' Descriptor Support for Primary Keys'''''
 
  
 
{| class="RuleFormal" dir="ltr" title="Descriptor Support for Primary Keys" summary="This table summarizes which descriptors support primary keys." width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
 
{| class="RuleFormal" dir="ltr" title="Descriptor Support for Primary Keys" summary="This table summarizes which descriptors support primary keys." width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
! id="r1c1-t4" align="left" valign="bottom" | '''Descriptor'''
 
! id="r1c1-t4" align="left" valign="bottom" | '''Descriptor'''
! id="r1c2-t4" align="left" valign="bottom" | '''[[#How to Configure Primary Keys Using Workbench]]<br>'''
+
! id="r1c2-t4" align="left" valign="bottom" | '''[[#How to Configure Primary Keys Using Workbench|Using the Workbench]]<br>'''
! id="r1c3-t4" align="left" valign="bottom" | '''[[#How to Configure Primary Keys Using Java]]<br>'''
+
! id="r1c3-t4" align="left" valign="bottom" | '''[[#How to Configure Primary Keys Using Java|Using Java]]<br>'''
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r2c1-t4" headers="r1c1-t4" align="left" |
 
| id="r2c1-t4" headers="r1c1-t4" align="left" |
Relational Descriptors  <sup>Foot 1 </sup>
+
Relational Descriptors  <sup> 1 </sup>
 
| headers="r2c1-t4 r1c2-t4" align="left" |
 
| headers="r2c1-t4 r1c2-t4" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
| headers="r2c1-t4 r1c3-t4" align="left" |
 
| headers="r2c1-t4 r1c3-t4" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r3c1-t4" headers="r1c1-t4" align="left" |
 
| id="r3c1-t4" headers="r1c1-t4" align="left" |
 
Object-Relational Data Type Descriptors
 
Object-Relational Data Type Descriptors
 
| headers="r3c1-t4 r1c2-t4" align="left" |
 
| headers="r3c1-t4 r1c2-t4" align="left" |
Unsupported<br>
+
[[Image:unsupport.gif|Unsupported]]<br>
 
| headers="r3c1-t4 r1c3-t4" align="left" |
 
| headers="r3c1-t4 r1c3-t4" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r4c1-t4" headers="r1c1-t4" align="left" |
 
| id="r4c1-t4" headers="r1c1-t4" align="left" |
EIS Descriptors  <sup>Foot 2 </sup>
+
EIS Descriptors  <sup> 2 </sup>
 
| headers="r4c1-t4 r1c2-t4" align="left" |
 
| headers="r4c1-t4 r1c2-t4" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
| headers="r4c1-t4 r1c3-t4" align="left" |
 
| headers="r4c1-t4 r1c3-t4" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r5c1-t4" headers="r1c1-t4" align="left" |
 
| id="r5c1-t4" headers="r1c1-t4" align="left" |
 
XML Descriptors
 
XML Descriptors
 
| headers="r5c1-t4 r1c2-t4" align="left" |
 
| headers="r5c1-t4 r1c2-t4" align="left" |
Unsupported<br>
+
[[Image:unsupport.gif|Unsupported]]<br>
 
| headers="r5c1-t4 r1c3-t4" align="left" |
 
| headers="r5c1-t4 r1c3-t4" align="left" |
Unsupported<br>
+
[[Image:unsupport.gif|Unsupported]]<br>
 
|}
 
|}
  
<br><sup>Footnote 1 </sup>Relational class descriptors only (see [[Creating%20a%20Relational%20Descriptor%20(ELUG)|Creating Relational Class Descriptors]]).<br><sup>Footnote 2 </sup>EIS root descriptors only (see [[Creating%20an%20EIS%20Descriptor%20(ELUG)|EIS Root Descriptors]]).<br>
+
<br><sup> 1 </sup>[[Creating%20a%20Relational%20Descriptor%20(ELUG)#Creating Relational Class Descriptors|Relational class descriptors]] only.<br><sup> 2 </sup> [[Creating%20an%20EIS%20Descriptor%20(ELUG)#EIS Root Descriptors|EIS root descriptors]] only.<br>
  
For a relational class (non-aggregate) descriptor, choose any unique database field or set of unique database fields from the descriptor's associated table (see [[Configuring%20a%20Relational%20Descriptor%20(ELUG)|Configuring Associated Tables]]).
+
For a relational class (non-aggregate) descriptor, choose any unique database field or set of unique database fields from the descriptor's [[Configuring%20a%20Relational%20Descriptor%20(ELUG)#Configuring Associated Tables|associated table]].
  
For an EIS root descriptor (see [[Configuring%20an%20EIS%20Descriptor%20(ELUG)|Configuring an EIS Descriptor as a Root or Composite Type]]), choose any unique attribute or text node or set of unique attributes or text nodes from the descriptor's schema context (see [[Configuring%20an%20EIS%20Descriptor%20(ELUG)|Configuring Schema Context for an EIS Descriptor]]).
+
For an [[Configuring%20an%20EIS%20Descriptor%20(ELUG)#Configuring an EIS Descriptor as a Root or Composite Type|EIS root descriptor]], choose any unique attribute or text node or set of unique attributes or text nodes from [[Configuring%20an%20EIS%20Descriptor%20(ELUG)#Configuring Schema Context for an EIS Descriptor|the descriptor's schema context]].
  
  
  
 
===How to Configure Primary Keys Using Workbench===
 
===How to Configure Primary Keys Using Workbench===
 
 
To associate a descriptor with one or more primary keys, use this procedure:
 
To associate a descriptor with one or more primary keys, use this procedure:
 
 
# Select a descriptor in the '''Navigator'''. Its properties appear in the Editor.
 
# Select a descriptor in the '''Navigator'''. Its properties appear in the Editor.
 
# Click the '''Descriptor Info''' tab. The Descriptor Info tab appears.<br>''''' Descriptor Info Tab, Primary Key Options'''''<br>[[Image:desinpk.gif|Descriptor Info Tab, Primary Key Options]]<br><br>
 
# Click the '''Descriptor Info''' tab. The Descriptor Info tab appears.<br>''''' Descriptor Info Tab, Primary Key Options'''''<br>[[Image:desinpk.gif|Descriptor Info Tab, Primary Key Options]]<br><br>
 
# Complete the Primary Keys options on the tab.
 
# Complete the Primary Keys options on the tab.
 +
  
 
Use this table to enter data in Primary Keys field on the descriptor's '''Descriptor Info''' tab to specify the primary key(s):
 
Use this table to enter data in Primary Keys field on the descriptor's '''Descriptor Info''' tab to specify the primary key(s):
 
  
  
Line 374: Line 366:
 
| headers="r2c1-t5 r1c2-t5" align="left" |
 
| headers="r2c1-t5 r1c2-t5" align="left" |
 
To specify the primary keys for the table, click '''Add''' in order to do the following:
 
To specify the primary keys for the table, click '''Add''' in order to do the following:
* For a relational class descriptor, select a database field from the descriptor's associated table (see [[Configuring%20a%20Relational%20Descriptor%20(ELUG)#Configuring Associated Tables|Configuring Associated Tables]]).
+
* For a relational class descriptor, select a database field from the descriptor's [[Configuring%20a%20Relational%20Descriptor%20(ELUG)#Configuring Associated Tables|associated table]].
* For an EIS root descriptor, select an attribute or text node from the descriptor's schema context (see [[Configuring%20an%20EIS%20Descriptor%20(ELUG)#Configuring Schema Context for an EIS Descriptor|Configuring Schema Context for an EIS Descriptor]]). For more information on choosing an element or attribute, see [[Configuring%20an%20EIS%20Descriptor%20(ELUG)#Choosing a Schema Context|Choosing a Schema Context]].To remove a primary key, select the key and click '''Remove'''.
+
* For an EIS root descriptor, select an attribute or text node from the descriptor's [[Configuring%20an%20EIS%20Descriptor%20(ELUG)#Configuring Schema Context for an EIS Descriptor|schema context]]. For more information on choosing an element or attribute, see [[Configuring%20an%20EIS%20Descriptor%20(ELUG)#Choosing a Schema Context|Choosing a Schema Context]].
 +
 
 +
To remove a primary key, select the key and click '''Remove'''.
 
|}
 
|}
  
<br>
 
  
'''See Also'''
 
: [[#Configuring Primary Keys|Configuring Primary Keys]]
 
: [[#Configuring a Descriptor|Configuring a Descriptor]]
 
  
 
===How to Configure Primary Keys Using Java===
 
===How to Configure Primary Keys Using Java===
 
 
You can use Java to configure primary keys for the following:
 
You can use Java to configure primary keys for the following:
 
+
* [[#Relational Projects|Relational Projects]]
* [[#Relational Projects]]
+
* [[#EIS Projects|EIS Projects]]
* [[#EIS Projects]]
+
  
  
Line 415: Line 403:
  
 
<span id="Table 115-4"></span>
 
<span id="Table 115-4"></span>
''''' Descriptor Support for Read Only'''''
 
 
{| class="RuleFormal" dir="ltr" title="Descriptor Support for Read Only" summary="This table summarizes which descriptors support for read only." width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
 
{| class="RuleFormal" dir="ltr" title="Descriptor Support for Read Only" summary="This table summarizes which descriptors support for read only." width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
! id="r1c1-t6" align="left" valign="bottom" | '''Descriptor'''
 
! id="r1c1-t6" align="left" valign="bottom" | '''Descriptor'''
! id="r1c2-t6" align="left" valign="bottom" | '''[[#How to Configure Read-Only Descriptors Using Workbench]]<br>'''
+
! id="r1c2-t6" align="left" valign="bottom" | '''[[#How to Configure Read-Only Descriptors Using Workbench|Using the Workbench]]<br>'''
! id="r1c3-t6" align="left" valign="bottom" | '''[[#How to Configure Read-Only Descriptors Using Java]]<br>'''
+
! id="r1c3-t6" align="left" valign="bottom" | '''[[#How to Configure Read-Only Descriptors Using Java|Using Java]]<br>'''
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r2c1-t6" headers="r1c1-t6" align="left" |
 
| id="r2c1-t6" headers="r1c1-t6" align="left" |
Relational Descriptors <sup>Foot 1 </sup>
+
Relational Descriptors <sup> 1 </sup>
 
| headers="r2c1-t6 r1c2-t6" align="left" |
 
| headers="r2c1-t6 r1c2-t6" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
| headers="r2c1-t6 r1c3-t6" align="left" |
 
| headers="r2c1-t6 r1c3-t6" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r3c1-t6" headers="r1c1-t6" align="left" |
 
| id="r3c1-t6" headers="r1c1-t6" align="left" |
 
Object-Relational Data Type Descriptors
 
Object-Relational Data Type Descriptors
 
| headers="r3c1-t6 r1c2-t6" align="left" |
 
| headers="r3c1-t6 r1c2-t6" align="left" |
Unsupported<br>
+
[[Image:unsupport.gif|Unsupported]]<br>
 
| headers="r3c1-t6 r1c3-t6" align="left" |
 
| headers="r3c1-t6 r1c3-t6" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r4c1-t6" headers="r1c1-t6" align="left" |
 
| id="r4c1-t6" headers="r1c1-t6" align="left" |
EIS Descriptor <sup>Foot 2 </sup>
+
EIS Descriptor <sup> 2 </sup>
 
| headers="r4c1-t6 r1c2-t6" align="left" |
 
| headers="r4c1-t6 r1c2-t6" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
| headers="r4c1-t6 r1c3-t6" align="left" |
 
| headers="r4c1-t6 r1c3-t6" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r5c1-t6" headers="r1c1-t6" align="left" |
 
| id="r5c1-t6" headers="r1c1-t6" align="left" |
 
XML Descriptors
 
XML Descriptors
 
| headers="r5c1-t6 r1c2-t6" align="left" |
 
| headers="r5c1-t6 r1c2-t6" align="left" |
Unsupported<br>
+
[[Image:unsupport.gif|Unsupported]]<br>
 
| headers="r5c1-t6 r1c3-t6" align="left" |
 
| headers="r5c1-t6 r1c3-t6" align="left" |
Unsupported<br>
+
[[Image:unsupport.gif|Unsupported]]<br>
 
|}
 
|}
  
<br><sup>Footnote 1 </sup>Relational class descriptors only (see [[Creating%20a%20Relational%20Descriptor%20(ELUG)|Creating Relational Class Descriptors]]).<br><sup>Footnote 2 </sup>EIS root descriptors only (see [[Creating%20an%20EIS%20Descriptor%20(ELUG)|EIS Root Descriptors]])<br><br>
+
<br><sup> 1 </sup>[[Creating%20a%20Relational%20Descriptor%20(ELUG)#Creating Relational Class Descriptors|Relational class descriptors]] only.<br><sup> 2 </sup>[[Creating%20an%20EIS%20Descriptor%20(ELUG)#EIS Root Descriptors|EIS root descriptors]] only.<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"
Line 458: Line 445:
 
|}
 
|}
  
<br>
 
  
  
===How to Configure Read-Only Descriptors Using Workbench===
 
  
 +
===How to Configure Read-Only Descriptors Using Workbench===
 
To configure a descriptor as read-only use this procedure:
 
To configure a descriptor as read-only use this procedure:
 
 
# Select a descriptor in the '''Navigator'''. Its properties appear in the Editor.
 
# Select a descriptor in the '''Navigator'''. Its properties appear in the Editor.
 
# Click the '''Descriptor Info''' tab. The Descriptor Info tab appears.<br><span id="Figure 115-2"></span>''''' Descriptor Info Tab, Read Only Option'''''<br>[[Image:desread.gif|Descriptor Info Tab, Read Only Option]]<br><br>
 
# Click the '''Descriptor Info''' tab. The Descriptor Info tab appears.<br><span id="Figure 115-2"></span>''''' Descriptor Info Tab, Read Only Option'''''<br>[[Image:desread.gif|Descriptor Info Tab, Read Only Option]]<br><br>
Line 476: Line 461:
  
 
===How to Configure Read-Only Descriptors Using Java===
 
===How to Configure Read-Only Descriptors Using Java===
 
 
Use <tt>ClassDescriptor</tt> method <tt>setReadOnly</tt>.
 
Use <tt>ClassDescriptor</tt> method <tt>setReadOnly</tt>.
  
==Configuring Unit of Work Conforming at the Descriptor Level==
 
  
 +
 +
==Configuring Unit of Work Conforming at the Descriptor Level==
 
Conforming is a query feature that lets you include new, changed, or deleted objects in queries within a unit of work prior to committing the transaction. This feature enables you to query against your relative logical or transaction view of a data source.
 
Conforming is a query feature that lets you include new, changed, or deleted objects in queries within a unit of work prior to committing the transaction. This feature enables you to query against your relative logical or transaction view of a data source.
  
 
This table summarizes which descriptors support descriptor level unit of work conforming.
 
This table summarizes which descriptors support descriptor level unit of work conforming.
 
  
 
<span id="Table 115-5"></span>
 
<span id="Table 115-5"></span>
''''' Descriptor Support for Unit of Work Conforming'''''
 
 
 
{| class="RuleFormal" dir="ltr" title="Descriptor Support for Unit of Work Conforming" summary="This table summarizes which descriptors support unit of work conforming." width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
 
{| class="RuleFormal" dir="ltr" title="Descriptor Support for Unit of Work Conforming" summary="This table summarizes which descriptors support unit of work conforming." width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
! id="r1c1-t8" align="left" valign="bottom" | '''Descriptor'''
 
! id="r1c1-t8" align="left" valign="bottom" | '''Descriptor'''
! id="r1c2-t8" align="left" valign="bottom" | '''[[#How to Configure Unit of Work Conforming at the Descriptor Level Using Workbench]]<br>'''
+
! id="r1c2-t8" align="left" valign="bottom" | '''[[#How to Configure Unit of Work Conforming at the Descriptor Level Using Workbench|Using the Workbench]]<br>'''
! id="r1c3-t8" align="left" valign="bottom" | '''[[#How to Configure Unit of Work Conforming at the Descriptor Level Using Java]]<br>'''
+
! id="r1c3-t8" align="left" valign="bottom" | '''[[#How to Configure Unit of Work Conforming at the Descriptor Level Using Java|Using Java]]<br>'''
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r2c1-t8" headers="r1c1-t8" align="left" |
 
| id="r2c1-t8" headers="r1c1-t8" align="left" |
Relational Descriptors <sup>Foot 1 </sup>
+
Relational Descriptors <sup> 1 </sup>
 
| headers="r2c1-t8 r1c2-t8" align="left" |
 
| headers="r2c1-t8 r1c2-t8" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
| headers="r2c1-t8 r1c3-t8" align="left" |
 
| headers="r2c1-t8 r1c3-t8" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r3c1-t8" headers="r1c1-t8" align="left" |
 
| id="r3c1-t8" headers="r1c1-t8" align="left" |
 
Object-Relational Data Type Descriptors
 
Object-Relational Data Type Descriptors
 
| headers="r3c1-t8 r1c2-t8" align="left" |
 
| headers="r3c1-t8 r1c2-t8" align="left" |
Unsupported<br>
+
[[Image:unsupport.gif|Unsupported]]<br>
 
| headers="r3c1-t8 r1c3-t8" align="left" |
 
| headers="r3c1-t8 r1c3-t8" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r4c1-t8" headers="r1c1-t8" align="left" |
 
| id="r4c1-t8" headers="r1c1-t8" align="left" |
EIS Descriptors <sup>Foot 2 </sup>
+
EIS Descriptors <sup> 2 </sup>
 
| headers="r4c1-t8 r1c2-t8" align="left" |
 
| headers="r4c1-t8 r1c2-t8" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
| headers="r4c1-t8 r1c3-t8" align="left" |
 
| headers="r4c1-t8 r1c3-t8" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r5c1-t8" headers="r1c1-t8" align="left" |
 
| id="r5c1-t8" headers="r1c1-t8" align="left" |
 
XML Descriptors
 
XML Descriptors
 
| headers="r5c1-t8 r1c2-t8" align="left" |
 
| headers="r5c1-t8 r1c2-t8" align="left" |
Unsupported<br>
+
[[Image:unsupport.gif|Unsupported]]<br>
 
| headers="r5c1-t8 r1c3-t8" align="left" |
 
| headers="r5c1-t8 r1c3-t8" align="left" |
Unsupported<br>
+
[[Image:unsupport.gif|Unsupported]]<br>
 
|}
 
|}
  
<br><sup>Footnote 1 </sup>Relational class descriptors only (see [[Creating%20a%20Relational%20Descriptor%20(ELUG)|Creating Relational Class Descriptors]]).<br><sup>Footnote 2 </sup>EIS root descriptors only (see [[Creating%20an%20EIS%20Descriptor%20(ELUG)|EIS Root Descriptors]])<br>
+
<br><sup> 1 </sup>[[Creating%20a%20Relational%20Descriptor%20(ELUG)#Creating Relational Class Descriptors|Relational Class Descriptors]] only.<br><sup> 2 </sup>[[Creating%20an%20EIS%20Descriptor%20(ELUG)#EIS Root Descriptors|EIS Root Descriptors]] only.<br>
  
 
When you configure a descriptor to conform results in a unit of work, when you execute a query in the unit of work, EclipseLink filters the data source result set to the changes currently made in the unit of work. EclipseLink adds new or changed objects that correspond to the query's selection criteria and removes changed objects that no longer correspond to the query's selection criteria.
 
When you configure a descriptor to conform results in a unit of work, when you execute a query in the unit of work, EclipseLink filters the data source result set to the changes currently made in the unit of work. EclipseLink adds new or changed objects that correspond to the query's selection criteria and removes changed objects that no longer correspond to the query's selection criteria.
Line 537: Line 519:
 
<br>
 
<br>
  
Conforming can reduce performance. Before you enable a descriptor for conforming, be aware of its limitations (see [[Using%20Advanced%20Unit%20of%20Work%20API%20(ELUG)|How to Use Conforming]]) and make sure that conforming is actually necessary.
+
Conforming can reduce performance. Before you enable a descriptor for conforming, be aware of its limitations (see [[Using%20Advanced%20Unit%20of%20Work%20API%20(ELUG)#How to Use Conforming|How to Use Conforming]]) and make sure that conforming is actually necessary.
  
 
For examples, see the following:
 
For examples, see the following:
 
+
* [[Using%20Advanced%20Unit%20of%20Work%20API%20(ELUG)#Using Conforming Queries and Descriptors|Using Conforming Queries and Descriptors]]
* [[Using%20Advanced%20Unit%20of%20Work%20API%20(ELUG)|Using Conforming Queries and Descriptors]]
+
* [[Using%20Advanced%20Unit%20of%20Work%20API%20(ELUG)#What You May Need to Know About Conforming Query Alternatives|What You May Need to Know About Conforming Query Alternatives]]
* [[Using%20Advanced%20Unit%20of%20Work%20API%20(ELUG)|What You May Need to Know About Conforming Query Alternatives]]
+
  
  
  
 
===How to Configure Unit of Work Conforming at the Descriptor Level Using Workbench===
 
===How to Configure Unit of Work Conforming at the Descriptor Level Using Workbench===
 
 
To conform a descriptor's results in a unit of work, use this procedure:
 
To conform a descriptor's results in a unit of work, use this procedure:
 
 
# Select a descriptor in the '''Navigator'''. Its properties appear in the Editor.
 
# Select a descriptor in the '''Navigator'''. Its properties appear in the Editor.
# Click the '''Descriptor Info''' tab. The Descriptor Info tab appears.<br>'''''Figure 115-3 Descriptor Info Tab, Conform Results in Unit of Work Option'''''[[Image:desconform.gif|Descriptor Info Tab, Conform Results in Unit of Work Option]]<br><br>
+
# Click the '''Descriptor Info''' tab. The Descriptor Info tab appears.<br>'''''Descriptor Info Tab, Conform Results in Unit of Work Option'''''<br>[[Image:desconform.gif|Descriptor Info Tab, Conform Results in Unit of Work Option]]<br><br>
# Select the [topicid:descriptor.descriptorInfo.conform Conform Results in Unit of Work option] on the tab.
+
# Select the Conform Results in Unit of Work option on the tab.
  
Enable or disable conforming: when enabled, this feature ensures that any queries for this descriptor will conform the data source result with the current changes in the unit of work. For more information, see [[Using%20Advanced%20Unit%20of%20Work%20API%20(ELUG)|How to Use Conforming]].
+
Enable or disable conforming: when enabled, this feature ensures that any queries for this descriptor will conform the data source result with the current changes in the unit of work. For more information, see [[Using%20Advanced%20Unit%20of%20Work%20API%20(ELUG)#How to Use Conforming|How to Use Conforming]].
  
 
'''See Also'''
 
'''See Also'''
: [[#Configuring Unit of Work Conforming at the Descriptor Level]]
+
: [[#Configuring Unit of Work Conforming at the Descriptor Level|Configuring Unit of Work Conforming at the Descriptor Level]]
: [[#Configuring a Descriptor]]
+
: [[#Configuring a Descriptor|Configuring a Descriptor]]
  
  
  
 
===How to Configure Unit of Work Conforming at the Descriptor Level Using Java===
 
===How to Configure Unit of Work Conforming at the Descriptor Level Using Java===
 
 
Use <tt>ClassDescriptor</tt> method <tt>setShouldAlwaysConformResultsInUnitOfWork(true)</tt>.
 
Use <tt>ClassDescriptor</tt> method <tt>setShouldAlwaysConformResultsInUnitOfWork(true)</tt>.
  
==Configuring Descriptor Alias==
 
  
 +
 +
==Configuring Descriptor Alias==
 
This table summarizes which descriptors support descriptor alias configuration.
 
This table summarizes which descriptors support descriptor alias configuration.
  
  
 
<span id="Table 115-6"></span>
 
<span id="Table 115-6"></span>
''''' Descriptor Support for Descriptor Alias Configuration'''''
 
 
 
{| class="RuleFormal" dir="ltr" title="Descriptor Support for Descriptor Alias Configuration" summary="This table summarizes which descriptors support descriptor alias configuration." width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
 
{| class="RuleFormal" dir="ltr" title="Descriptor Support for Descriptor Alias Configuration" summary="This table summarizes which descriptors support descriptor alias configuration." width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
! id="r1c1-t10" align="left" valign="bottom" | '''Descriptor'''
 
! id="r1c1-t10" align="left" valign="bottom" | '''Descriptor'''
! id="r1c2-t10" align="left" valign="bottom" | '''[[#How to Configure Descriptor Alias Using Workbench]]<br>'''
+
! id="r1c2-t10" align="left" valign="bottom" | '''[[#How to Configure Descriptor Alias Using Workbench|Using the Workbench]]<br>'''
! id="r1c3-t10" align="left" valign="bottom" | '''[[#How to Configure Descriptor Alias Using Java]]<br>'''
+
! id="r1c3-t10" align="left" valign="bottom" | '''[[#How to Configure Descriptor Alias Using Java|Using Java]]<br>'''
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r2c1-t10" headers="r1c1-t10" align="left" |
 
| id="r2c1-t10" headers="r1c1-t10" align="left" |
 
Relational Descriptors
 
Relational Descriptors
 
| headers="r2c1-t10 r1c2-t10" align="left" |
 
| headers="r2c1-t10 r1c2-t10" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
| headers="r2c1-t10 r1c3-t10" align="left" |
 
| headers="r2c1-t10 r1c3-t10" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r3c1-t10" headers="r1c1-t10" align="left" |
 
| id="r3c1-t10" headers="r1c1-t10" align="left" |
 
Object-Relational Data Type Descriptors
 
Object-Relational Data Type Descriptors
 
| headers="r3c1-t10 r1c2-t10" align="left" |
 
| headers="r3c1-t10 r1c2-t10" align="left" |
Unsupported<br>
+
[[Image:unsupport.gif|Unsupported]]<br>
 
| headers="r3c1-t10 r1c3-t10" align="left" |
 
| headers="r3c1-t10 r1c3-t10" align="left" |
Unsupported<br>
+
[[Image:unsupport.gif|Unsupported]]<br>
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r4c1-t10" headers="r1c1-t10" align="left" |
 
| id="r4c1-t10" headers="r1c1-t10" align="left" |
EIS Descriptors <sup>Foot 1 </sup>
+
EIS Descriptors <sup> 1 </sup>
 
| headers="r4c1-t10 r1c2-t10" align="left" |
 
| headers="r4c1-t10 r1c2-t10" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
| headers="r4c1-t10 r1c3-t10" align="left" |
 
| headers="r4c1-t10 r1c3-t10" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r5c1-t10" headers="r1c1-t10" align="left" |
 
| id="r5c1-t10" headers="r1c1-t10" align="left" |
 
XML Descriptors
 
XML Descriptors
 
| headers="r5c1-t10 r1c2-t10" align="left" |
 
| headers="r5c1-t10 r1c2-t10" align="left" |
Unsupported<br>
+
[[Image:unsupport.gif|Unsupported]]<br>
 
| headers="r5c1-t10 r1c3-t10" align="left" |
 
| headers="r5c1-t10 r1c3-t10" align="left" |
Unsupported<br>
+
[[Image:unsupport.gif|Unsupported]]<br>
 
|}
 
|}
  
<br><sup>Footnote 1 </sup>EIS root descriptors only (see [[Creating%20an%20EIS%20Descriptor%20(ELUG)|EIS Root Descriptors]]).<br>
+
<br><sup> 1 </sup>[[Creating%20an%20EIS%20Descriptor%20(ELUG)#EIS Root Descriptors|EIS Root Descriptors]] only.<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:''' The alias is also used in JPA–it is the entity name. This is the logical name referenced in JP QL queries. It defaults to the class name without a path information.  
+
'''Note:''' The alias is also used in JPA – it is the entity name. This is the logical name referenced in JP QL queries. It defaults to the class name without a path information.  
 
For more information, see [[Introduction%20to%20Java%20Persistence%20API%20(ELUG)|Introduction to Java Persistence API ]]
 
For more information, see [[Introduction%20to%20Java%20Persistence%20API%20(ELUG)|Introduction to Java Persistence API ]]
 
|}
 
|}
Line 620: Line 597:
  
 
===How to Configure Descriptor Alias Using Workbench===
 
===How to Configure Descriptor Alias Using Workbench===
 
 
To specify a descriptor alias, use this procedure:
 
To specify a descriptor alias, use this procedure:
 
 
# In the '''Navigator''', select a descriptor.
 
# In the '''Navigator''', select a descriptor.
# Click the '''Descriptor Info''' tab in the Property window.
+
# Click the '''Descriptor Info''' tab in the Property window.<br>'''''Descriptor Info Tab, Descriptor Alias Field'''''<br>[[Image:desalias.gif|Descriptor Info Tab, Descriptor Alias Field]]<br><br>
# <br>'''''Figure 115-4 Descriptor Info Tab, Descriptor Alias Field'''''[[Image:desalias.gif|Descriptor Info Tab, Descriptor Alias Field]]<br><br>
+
# In the '''Descriptor Alias''' field, enter an alias for this descriptor. The default is the class name.
 
+
In the '''Descriptor Alias''' field, enter an alias for this descriptor. The default is the class name.
+
  
  
  
 
===How to Configure Descriptor Alias Using Java===
 
===How to Configure Descriptor Alias Using Java===
 
 
Use <tt>ClassDescriptor</tt> method <tt>setAlias</tt> passing in the descriptor alias as a <tt>String</tt>. The descriptor alias defaults to the class name.
 
Use <tt>ClassDescriptor</tt> method <tt>setAlias</tt> passing in the descriptor alias as a <tt>String</tt>. The descriptor alias defaults to the class name.
 +
 +
  
 
==Configuring Descriptor Comments==
 
==Configuring Descriptor Comments==
 
 
You can define a free-form textual comment for each descriptor. You can use these comments however you whish: for example, to record important project implementation details such as the purpose or importance of a descriptor.
 
You can define a free-form textual comment for each descriptor. You can use these comments however you whish: for example, to record important project implementation details such as the purpose or importance of a descriptor.
  
Line 645: Line 618:
  
 
<span id="Table 115-7"></span>
 
<span id="Table 115-7"></span>
''''' Descriptor Support for Descriptor Comment Configuration'''''
 
  
 
{| class="RuleFormal" dir="ltr" title="Descriptor Support for Descriptor Comment Configuration" summary="This table summarizes which descriptors support descriptor comment configuration." width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
 
{| class="RuleFormal" dir="ltr" title="Descriptor Support for Descriptor Comment Configuration" summary="This table summarizes which descriptors support descriptor comment configuration." width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
! id="r1c1-t11" align="left" valign="bottom" | '''Descriptor'''
 
! id="r1c1-t11" align="left" valign="bottom" | '''Descriptor'''
! id="r1c2-t11" align="left" valign="bottom" | '''[[#How to Configure Descriptor Comments Using Workbench]]<br>'''
+
! id="r1c2-t11" align="left" valign="bottom" | '''[[#How to Configure Descriptor Comments Using Workbench|Using the Workbench]]<br>'''
 
! id="r1c3-t11" align="left" valign="bottom" | '''How to Use Java'''
 
! id="r1c3-t11" align="left" valign="bottom" | '''How to Use Java'''
 
|- align="left" valign="top"
 
|- align="left" valign="top"
Line 656: Line 628:
 
Relational Descriptors
 
Relational Descriptors
 
| headers="r2c1-t11 r1c2-t11" align="left" |
 
| headers="r2c1-t11 r1c2-t11" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
| headers="r2c1-t11 r1c3-t11" align="left" |
 
| headers="r2c1-t11 r1c3-t11" align="left" |
Unsupported<br>
+
[[Image:unsupport.gif|Unsupported]]<br>
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r3c1-t11" headers="r1c1-t11" align="left" |
 
| id="r3c1-t11" headers="r1c1-t11" align="left" |
 
Object-Relational Data Type Descriptors
 
Object-Relational Data Type Descriptors
 
| headers="r3c1-t11 r1c2-t11" align="left" |
 
| headers="r3c1-t11 r1c2-t11" align="left" |
Unsupported<br>
+
[[Image:unsupport.gif|Unsupported]]<br>
 
| headers="r3c1-t11 r1c3-t11" align="left" |
 
| headers="r3c1-t11 r1c3-t11" align="left" |
Unsupported<br>
+
[[Image:unsupport.gif|Unsupported]]<br>
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r4c1-t11" headers="r1c1-t11" align="left" |
 
| id="r4c1-t11" headers="r1c1-t11" align="left" |
 
EIS Descriptors
 
EIS Descriptors
 
| headers="r4c1-t11 r1c2-t11" align="left" |
 
| headers="r4c1-t11 r1c2-t11" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
| headers="r4c1-t11 r1c3-t11" align="left" |
 
| headers="r4c1-t11 r1c3-t11" align="left" |
Unsupported<br>
+
[[Image:unsupport.gif|Unsupported]]<br>
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r5c1-t11" headers="r1c1-t11" align="left" |
 
| id="r5c1-t11" headers="r1c1-t11" align="left" |
 
XML Descriptors
 
XML Descriptors
 
| headers="r5c1-t11 r1c2-t11" align="left" |
 
| headers="r5c1-t11 r1c2-t11" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
| headers="r5c1-t11 r1c3-t11" align="left" |
 
| headers="r5c1-t11 r1c3-t11" align="left" |
Unsupported<br>
+
[[Image:unsupport.gif|Unsupported]]<br>
 
|}
 
|}
  
<br>
+
 
  
 
===How to Configure Descriptor Comments Using Workbench===
 
===How to Configure Descriptor Comments Using Workbench===
 
 
To create a comment for a descriptor, use this procedure:
 
To create a comment for a descriptor, use this procedure:
 
 
# In the '''Navigator''', select a descriptor.
 
# In the '''Navigator''', select a descriptor.
# Click the '''Descriptor Info''' tab in the Property window.
+
# Click the '''Descriptor Info''' tab in the Property window.<br>'''''Descriptor Info Tab, Comment Field'''''<br>[[Image:descomment.gif|Descriptor Info Tab, Comment Field]]<br><br>
# <br>'''''Figure 115-5 Descriptor Info Tab, Comment Field'''''[[Image:descomment.gif|Descriptor Info Tab, Comment Field]]<br><br>
+
# In the '''Comment''' field, enter a description of this descriptor.
 
+
In the '''Comment''' field, enter a description of this descriptor.
+
  
  
  
 
==Configuring Named Queries at the Descriptor Level==
 
==Configuring Named Queries at the Descriptor Level==
 +
A named query is an EclipseLink query that you create and store, by name, in a descriptor's <tt>DescriptorQueryManager</tt> 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 descriptor's <tt>DescriptorQueryManager</tt> 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 <tt>Class</tt>, configure it at the descriptor level. Alternatively, you can [[Configuring%20a%20Session%20(ELUG)#Configuring Named Queries at the Session Level|configure a named query at the session level]].
 
+
If a named query is global to a <tt>Class</tt>, configure it at the descriptor level. Alternatively, you can configure a named query at the session level (see [[Configuring%20a%20Session%20(ELUG)|Configuring Named Queries at the Session Level]]).
+
  
 
Use named queries to specify SQL or EclipseLink <tt>Expression</tt> queries to access your data source.
 
Use named queries to specify SQL or EclipseLink <tt>Expression</tt> queries to access your data source.
Line 713: Line 680:
 
<br />
 
<br />
  
Using the Workbench, you can configure named queries for a subset of query types and store them in a descriptor's <tt>DescriptorQueryManager</tt> (see [[#How to Configure Named Queries at the Descriptor Level Using Workbench]]).
+
[[#How to Configure Named Queries at the Descriptor Level Using Workbench|Using the Workbench]], you can configure named queries for a subset of query types and store them in a descriptor's <tt>DescriptorQueryManager</tt>.
  
Using Java, you can create named queries for all query types and store them in a descriptor's <tt>DescriptorQueryManager</tt> (see [[#How to Configure Named Queries at the Descriptor Level Using Java]]).
+
[[#How to Configure Named Queries at the Descriptor Level Using Java|Using Java]], you can create named queries for all query types and store them in a descriptor's <tt>DescriptorQueryManager</tt>.
  
 
This table summarizes which descriptors support named query configuration.
 
This table summarizes which descriptors support named query configuration.
Line 721: Line 688:
  
 
<span id="Table 115-8"></span>
 
<span id="Table 115-8"></span>
''''' Descriptor Support for Named Queries'''''
 
  
 
{| class="RuleFormal" dir="ltr" title="Descriptor Support for Named Queries" summary="This table summarizes which descriptors support for named queries." width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
 
{| class="RuleFormal" dir="ltr" title="Descriptor Support for Named Queries" summary="This table summarizes which descriptors support for named queries." width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
! id="r1c1-t12" align="left" valign="bottom" | '''Descriptor'''
 
! id="r1c1-t12" align="left" valign="bottom" | '''Descriptor'''
! id="r1c2-t12" align="left" valign="bottom" | '''[[#How to Configure Named Queries at the Descriptor Level Using Workbench]]<br>'''
+
! id="r1c2-t12" align="left" valign="bottom" | '''[[#How to Configure Named Queries at the Descriptor Level Using Workbench|Using the Workbench]]<br>'''
! id="r1c3-t12" align="left" valign="bottom" | '''[[#How to Configure Named Queries at the Descriptor Level Using Java]]<br>'''
+
! id="r1c3-t12" align="left" valign="bottom" | '''[[#How to Configure Named Queries at the Descriptor Level Using Java|Using Java]]<br>'''
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r2c1-t12" headers="r1c1-t12" align="left" |
 
| id="r2c1-t12" headers="r1c1-t12" align="left" |
Relational Descriptors<sup>Foot 1 </sup>
+
Relational Descriptors<sup> 1 </sup>
 
| headers="r2c1-t12 r1c2-t12" align="left" |
 
| headers="r2c1-t12 r1c2-t12" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
| headers="r2c1-t12 r1c3-t12" align="left" |
 
| headers="r2c1-t12 r1c3-t12" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r3c1-t12" headers="r1c1-t12" align="left" |
 
| id="r3c1-t12" headers="r1c1-t12" align="left" |
 
Object-Relational Data Type Descriptors
 
Object-Relational Data Type Descriptors
 
| headers="r3c1-t12 r1c2-t12" align="left" |
 
| headers="r3c1-t12 r1c2-t12" align="left" |
Unsupported<br>
+
[[Image:unsupport.gif|Unsupported]]<br>
 
| headers="r3c1-t12 r1c3-t12" align="left" |
 
| headers="r3c1-t12 r1c3-t12" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r4c1-t12" headers="r1c1-t12" align="left" |
 
| id="r4c1-t12" headers="r1c1-t12" align="left" |
EIS Descriptor<sup>Foot 2 </sup>
+
EIS Descriptor<sup> 2 </sup>
 
| headers="r4c1-t12 r1c2-t12" align="left" |
 
| headers="r4c1-t12 r1c2-t12" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
| headers="r4c1-t12 r1c3-t12" align="left" |
 
| headers="r4c1-t12 r1c3-t12" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r5c1-t12" headers="r1c1-t12" align="left" |
 
| id="r5c1-t12" headers="r1c1-t12" align="left" |
 
XML Descriptors
 
XML Descriptors
 
| headers="r5c1-t12 r1c2-t12" align="left" |
 
| headers="r5c1-t12 r1c2-t12" align="left" |
Unsupported<br>
+
[[Image:unsupport.gif|Unsupported]]<br>
 
| headers="r5c1-t12 r1c3-t12" align="left" |
 
| headers="r5c1-t12 r1c3-t12" align="left" |
Unsupported<br>
+
[[Image:unsupport.gif|Unsupported]]<br>
 
|}
 
|}
  
<br><sup>Footnote 1 </sup>Relational class descriptors only (see [[Creating%20a%20Relational%20Descriptor%20(ELUG)|Creating Relational Class Descriptors]]).<br><sup>Footnote 2 </sup>EIS root descriptors only (see [[Creating%20an%20EIS%20Descriptor%20(ELUG)|EIS Root Descriptors]]).<br>
+
<br><sup> 1 </sup>[[Creating%20a%20Relational%20Descriptor%20(ELUG)#Creating Relational Class Descriptors|Relational Class Descriptors]] only.<br><sup> 2 </sup>[[Creating%20an%20EIS%20Descriptor%20(ELUG)#EIS Root Descriptors|EIS Root Descriptors]] only.<br>
  
After you create a named query, you can execute it by name and class on the EclipseLink session (see [[Using%20Basic%20Query%20API%20(ELUG)|Using Named Queries]]).
+
After you create a named query, you can execute it by name and class 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]].
+
For more information about named queries, see [[Introduction%20to%20EclipseLink%20Queries%20(ELUG)#Named Queries|Named Queries]].
  
  
  
 
===How to Configure Named Queries at the Descriptor Level Using Workbench===
 
===How to Configure Named Queries at the Descriptor Level Using Workbench===
 
 
To create a named query, use this procedure
 
To create a named query, use this procedure
 
 
# In the '''Navigator''', select a descriptor. Its properties appear in the Editor.
 
# In the '''Navigator''', select a descriptor. Its properties appear in the Editor.
 
# Click the '''Queries''' tab in the '''Editor'''. The Queries tab appear with three additional tabs.
 
# Click the '''Queries''' tab in the '''Editor'''. The Queries tab appear with three additional tabs.
# Click the '''Named Queries''' tab in the Queries tab. The Named Queries tab appears.<br>'''''Figure 115-6 Queries Tab–Named Queries Subtab'''''[[Image:qrnmdfnd.gif|Queries Tab–Named Queries Subtab]]<br><br>
+
# Click the '''Named Queries''' tab in the Queries tab. The Named Queries tab appears.<br>'''''Queries Tab – Named Queries Subtab'''''<br>[[Image:qrnmdfnd.gif|Queries Tab – Named Queries Subtab]]<br><br>
# Complete each field on the [topicid:descriptor.queryManager Named Queries tab].
+
# Complete each field on the Named Queries tab.
  
 
Use the following information to complete each field on this tab:
 
Use the following information to complete each field on this tab:
Line 790: Line 754:
 
| id="r3c1-t13" headers="r1c1-t13" align="left" | '''Query Variety'''
 
| id="r3c1-t13" headers="r1c1-t13" align="left" | '''Query Variety'''
 
| headers="r3c1-t13 r1c2-t13" align="left" |
 
| headers="r3c1-t13 r1c2-t13" align="left" |
Displays the variety of the currently selected query (see [[#Adding Named Queries]]).
+
Displays the variety of the currently selected query (see [[#Adding Named Queries|Adding Named Queries]]).
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r4c1-t13" headers="r1c1-t13" align="left" | '''Quick View'''
 
| id="r4c1-t13" headers="r1c1-t13" align="left" | '''Quick View'''
Line 797: Line 761:
 
|}
 
|}
  
<br>
 
  
The Named Queries tab includes the following subtabs:
 
  
* '''General'''–See [[#Configuring Named Query Type and Parameters]].
+
The Named Queries tab includes the following subtabs:
* '''Selection Criteria'''–See [[#Configuring Named Query Selection Criteria]].
+
* '''General''' – See [[#Configuring Named Query Type and Parameters|Configuring Named Query Type and Parameters]].
* '''Order'''–This tab appears for <tt>ReadAllQuery</tt> queries only. See [[#Configuring Read All Query Order]].
+
* '''Selection Criteria''' – See [[#Configuring Named Query Selection Criteria|Configuring Named Query Selection Criteria]].
* '''Optimization'''–See [[#Configuring Named Query Optimization]].
+
* '''Order''' – This tab appears for <tt>ReadAllQuery</tt> queries only. See [[#Configuring Read All Query Order|Configuring Read All Query Order]].
* '''Attributes'''–This tab appears for <tt>ReportQuery</tt> queries only. See [[#Configuring Named Query Attributes]].
+
* '''Optimization''' – See [[#Configuring Named Query Optimization|Configuring Named Query Optimization]].
* '''Group/Order'''–This tab appears for <tt>ReportQuery</tt> queries only. [[#Configuring Named Query Group/Order Options]].
+
* '''Attributes''' – This tab appears for <tt>ReportQuery</tt> queries only. See [[#Configuring Named Query Attributes|Configuring Named Query Attributes]].
* '''Calls'''–This tab appears for EIS root descriptors only (for <tt>ReadAllQuery</tt> and <tt>ReadObjectQuery</tt> queries). See [[#Creating an EIS Interaction for a Named Query]].
+
* '''Group/Order''' – This tab appears for <tt>ReportQuery</tt> queries only. [[#Configuring Named Query Group/Order Options|Configuring Named Query Group/Order Options]].
* '''Options'''–See [[#Configuring Named Query Options]].
+
* '''Calls''' – This tab appears for EIS root descriptors only (for <tt>ReadAllQuery</tt> and <tt>ReadObjectQuery</tt> queries). See [[#Creating an EIS Interaction for a Named Query|Creating an EIS Interaction for a Named Query]].
 +
* '''Options''' – See [[#Configuring Named Query Options|Configuring Named Query Options]].
  
 
'''See Also'''
 
'''See Also'''
: [[#Configuring Named Queries at the Descriptor Level]]
+
: [[#Configuring Named Queries at the Descriptor Level|Configuring Named Queries at the Descriptor Level]]
  
  
  
 
====Configuring Named Query Type and Parameters====
 
====Configuring Named Query Type and Parameters====
 
 
Use this tab to select the query type and add or remove parameters.
 
Use this tab to select the query type and add or remove parameters.
  
Line 838: Line 800:
 
* '''ReadAllQuery'''
 
* '''ReadAllQuery'''
 
* '''ReadObjectQuery'''
 
* '''ReadObjectQuery'''
* '''ReportQuery'''<sup>Foot 1 </sup>To create other types of query, you must use Java (see [[#How to Configure Named Queries at the Descriptor Level Using Java]]).When you change the type of an existing query, Workbench preserves any configuration that is common between the old and new type and warns you if changing the type will result in the loss of configuration that is not shared by the new type.
+
* '''ReportQuery'''<sup> 1 </sup>
 +
To create other types of query, you must [[#How to Configure Named Queries at the Descriptor Level Using Java|use Java]].
 +
 
 +
When you change the type of an existing query, Workbench preserves any configuration that is common between the old and new type and warns you if changing the type will result in the loss of configuration that is not shared by the new type.
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r3c1-t15" headers="r1c1-t15" align="left" | '''Parameters'''
 
| id="r3c1-t15" headers="r1c1-t15" align="left" | '''Parameters'''
Line 855: Line 820:
 
|}
 
|}
  
<br><sup>Footnote 1 </sup>Relational descriptors only.<br>
+
<br><sup> 1 </sup>Relational descriptors only.<br>
  
 
'''See Also'''
 
'''See Also'''
 
+
: [[#Configuring Named Queries at the Descriptor Level|Configuring Named Queries at the Descriptor Level]]
: [[#Configuring Named Queries at the Descriptor Level]]
+
  
  
  
 
====Configuring Named Query Selection Criteria====
 
====Configuring Named Query Selection Criteria====
 
 
Use this tab to specify the format of the named query and enter the query string.
 
Use this tab to specify the format of the named query and enter the query string.
  
<br>
 
  
'''''Figure 115-9 Named Queries, Selection Criteria Tab'''''
+
 
 +
'''''Named Queries, Selection Criteria Tab'''''
  
 
[[Image:qrnmdsel.gif|Named Queries, Selection Criteria Tab]]<br><br>
 
[[Image:qrnmdsel.gif|Named Queries, Selection Criteria Tab]]<br><br>
Line 881: Line 844:
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r2c1-t16" headers="r1c1-t16" align="left" | '''Type'''
 
| id="r2c1-t16" headers="r1c1-t16" align="left" | '''Type'''
| headers="r2c1-t16 r1c2-t16" align="left" | Specify if query uses a EclipseLink '''Expression''', '''SQL''', or '''EJB QL'''.
+
| headers="r2c1-t16 r1c2-t16" align="left" | Specify if query uses an EclipseLink '''Expression''', '''SQL''', or '''EJB QL'''.
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r3c1-t16" headers="r1c1-t16" align="left" | '''Expression''' or '''Query String'''
 
| id="r3c1-t16" headers="r1c1-t16" align="left" | '''Expression''' or '''Query String'''
 
| headers="r3c1-t16 r1c2-t16" align="left" |
 
| headers="r3c1-t16 r1c2-t16" align="left" |
If the '''Type''' is '''SQL''' or '''EJB QL''', enter the query string (either SQL or EJB QL). Workbench does not validate the query string.See a note that follows this table for information on query syntax.
+
If the '''Type''' is '''SQL''' or '''EJB QL''', enter the query string (either SQL or EJB QL). Workbench does not validate the query string.<br>See a note that follows this table for information on query syntax.
 
|}
 
|}
  
Line 892: Line 855:
 
{| 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> Use a combination of an escape character and a double-quote ( \" ) instead of just a double-quote ( " ) when defining your query using SQL or EJB QL. For example:   
+
'''''Note'''''<nowiki>:</nowiki> Use a combination of an escape character and a double-quote ( \" ) instead of just a double-quote ( " ) when defining your query using SQL or EJB QL. For example:   
 
  SELECT OBJECT(employee) FROM Employee employee WHERE employee.name = \"Bob\"
 
  SELECT OBJECT(employee) FROM Employee employee WHERE employee.name = \"Bob\"
 
If you fail to do so, the generated Java code would look as follows:  
 
If you fail to do so, the generated Java code would look as follows:  
Line 903: Line 866:
  
 
'''See Also'''
 
'''See Also'''
: [[#Configuring Named Queries at the Descriptor Level]]
+
: [[#Configuring Named Queries at the Descriptor Level|Configuring Named Queries at the Descriptor Level]]
  
====Configuring Read All Query Order====
 
  
 +
 +
====Configuring Read All Query Order====
 
Use this tab to specify how the results of a read all query should be ordered by attribute name.
 
Use this tab to specify how the results of a read all query should be ordered by attribute name.
  
<br>
 
  
'''''Figure 115-10 Named Queries, Order Tab'''''
+
'''''Named Queries, Order Tab'''''
  
 
[[Image:ordertab.gif|Named Queries, Order Tab]]<br><br>
 
[[Image:ordertab.gif|Named Queries, Order Tab]]<br><br>
Line 925: Line 888:
  
 
====Configuring Named Query Optimization====
 
====Configuring Named Query Optimization====
 
 
You can optimize a named query by configuring batch (<tt>ReadAllQuery</tt> only) or joining (<tt>ReadAllQuery</tt> and <tt>ReadObjectyQuery</tt>) attributes.
 
You can optimize a named query by configuring batch (<tt>ReadAllQuery</tt> only) or joining (<tt>ReadAllQuery</tt> and <tt>ReadObjectyQuery</tt>) attributes.
  
Line 942: Line 904:
  
 
Select one of the following actions for '''Batch Read Attributes''' (<tt>ReadAllQuery</tt> only):
 
Select one of the following actions for '''Batch Read Attributes''' (<tt>ReadAllQuery</tt> only):
 
 
* To add a new batch read attribute, click '''Add'''. The Add Batch Read Attribute dialog box appears. Select the mapped attribute and click '''OK'''.
 
* To add a new batch read attribute, click '''Add'''. The Add Batch Read Attribute dialog box appears. Select the mapped attribute and click '''OK'''.
 
* To change the order of the batch read attributes, select an existing attribute and click '''Up''' or '''Down'''.
 
* To change the order of the batch read attributes, select an existing attribute and click '''Up''' or '''Down'''.
Line 949: Line 910:
  
 
Select one of the following actions for '''Joined Attributes''' (<tt>ReadAllQuery</tt> and <tt>ReadObjectQuery</tt>):
 
Select one of the following actions for '''Joined Attributes''' (<tt>ReadAllQuery</tt> and <tt>ReadObjectQuery</tt>):
 
 
* To add a new joined attribute, click '''Add'''. The Add Joined Attribute dialog box appears.<br><span id="Figure 115-12"></span>''''' Add Joined Attribute Dialog Box'''''<br>[[Image:addjoin.gif|Add Joined Attribute Dialog Box]]<br><br>Select the mapped attribute. Optionally, enable or disable '''Allows Null''' or, for a <tt>Collection</tt> attribute, '''Allows None'''. Click '''OK'''.
 
* To add a new joined attribute, click '''Add'''. The Add Joined Attribute dialog box appears.<br><span id="Figure 115-12"></span>''''' Add Joined Attribute Dialog Box'''''<br>[[Image:addjoin.gif|Add Joined Attribute Dialog Box]]<br><br>Select the mapped attribute. Optionally, enable or disable '''Allows Null''' or, for a <tt>Collection</tt> attribute, '''Allows None'''. Click '''OK'''.
 
* To change the order of the joined attributes, select an existing attribute and click '''Up''' or '''Down'''.
 
* To change the order of the joined attributes, select an existing attribute and click '''Up''' or '''Down'''.
Line 955: Line 915:
 
* To remove a joined attribute, select an existing attribute and click '''Remove'''.
 
* To remove a joined attribute, select an existing attribute and click '''Remove'''.
  
====Configuring Named Query Attributes====
 
  
 +
 +
====Configuring Named Query Attributes====
 
For <tt>ReportQuery</tt> queries only, you can configure report query functions to apply to one or more attributes.
 
For <tt>ReportQuery</tt> queries only, you can configure report query functions to apply to one or more attributes.
  
For more information about report queries, see [[Introduction%20to%20EclipseLink%20Queries%20(ELUG)|Report Query]].
+
For more information, see [[Introduction%20to%20EclipseLink%20Queries%20(ELUG)#Report Query|Report Query]].
  
 
Use this tab to configure report query attributes.
 
Use this tab to configure report query attributes.
Line 970: Line 931:
  
 
Select one of the following actions for '''Attributes''' (<tt>ReportQuery</tt> only):
 
Select one of the following actions for '''Attributes''' (<tt>ReportQuery</tt> only):
 
+
* To add a new report query attribute, click '''Add'''. The Add Joined Attribute dialog box appears. Continue with [[#Adding Report Query Attributes|Adding Report Query Attributes]].
* To add a new report query attribute, click '''Add'''. The Add Joined Attribute dialog box appears. Continue with [[#Adding Report Query Attributes]].
+
 
* To change the order of the report query attribute attributes, select an existing attribute and click '''Up''' or '''Down'''.
 
* To change the order of the report query attribute attributes, select an existing attribute and click '''Up''' or '''Down'''.
 
* To modify an existing report query attribute's options, select an existing attribute and click '''Edit'''.
 
* To modify an existing report query attribute's options, select an existing attribute and click '''Edit'''.
Line 987: Line 947:
  
 
=====Adding Report Query Attributes=====
 
=====Adding Report Query Attributes=====
 
 
Use this dialog box to add a report query attribute.
 
Use this dialog box to add a report query attribute.
  
Line 1,005: Line 964:
 
| id="r2c1-t19" headers="r1c1-t19" align="left" | '''Allows None''' or '''Allows Null'''
 
| id="r2c1-t19" headers="r1c1-t19" align="left" | '''Allows None''' or '''Allows Null'''
 
| headers="r2c1-t19 r1c2-t19" align="left" |
 
| headers="r2c1-t19 r1c2-t19" align="left" |
Use the '''Allows Null''' and '''Allows None''' options to define an expression with an outer join. Check the '''Allows Null''' option to use the <tt>ExpressionBuilder</tt> method <tt>getAllowingNull</tt>.Check the '''Allows None''' option for <tt>Collection</tt> attributes to use the <tt>ExpressionBuilder</tt> method <tt>anyOfAllowingNone</tt>.For more information, see [[Introduction%20to%20EclipseLink%20Expressions%20(ELUG)|Using EclipseLink Expression API for Joins]].
+
Use the '''Allows Null''' and '''Allows None''' options to define an expression with an outer join. Check the '''Allows Null''' option to use the <tt>ExpressionBuilder</tt> method <tt>getAllowingNull</tt>.
 +
 
 +
Check the '''Allows None''' option for <tt>Collection</tt> attributes to use the <tt>ExpressionBuilder</tt> method <tt>anyOfAllowingNone</tt>.<br>For more information, see [[Introduction%20to%20EclipseLink%20Expressions%20(ELUG)|Using EclipseLink Expression API for Joins]].
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r3c1-t19" headers="r1c1-t19" align="left" | '''Function'''
 
| id="r3c1-t19" headers="r1c1-t19" align="left" | '''Function'''
Line 1,015: Line 976:
 
|}
 
|}
  
<br>
+
 
  
 
Enter the necessary information and click '''OK'''. Workbench adds the report query attribute to the list of attributes in the Attribute tab.
 
Enter the necessary information and click '''OK'''. Workbench adds the report query attribute to the list of attributes in the Attribute tab.
  
'''See Also'''
 
: [[#Configuring Named Query Attributes]]
 
  
====Configuring Named Query Group/Order Options====
 
  
 +
====Configuring Named Query Group/Order Options====
 
For <tt>ReportQuery</tt> queries only, you can configure grouping and ordering attributes.
 
For <tt>ReportQuery</tt> queries only, you can configure grouping and ordering attributes.
  
For more information about report queries, see [[Introduction%20to%20EclipseLink%20Queries%20(ELUG)|Report Query]].
+
For more information, see [[Introduction%20to%20EclipseLink%20Queries%20(ELUG)#Report Query|Report Query]].
  
 
Use this tab to specify grouping and ordering attributes.
 
Use this tab to specify grouping and ordering attributes.
Line 1,037: Line 996:
  
 
Select one of the following actions for '''Grouping Attributes''' (<tt>ReportQuery</tt> only):
 
Select one of the following actions for '''Grouping Attributes''' (<tt>ReportQuery</tt> only):
 
 
* To add a new grouping attribute, click '''Add'''. The Add Grouping Attribute dialog appears. Select the desired mapped attribute and click '''OK'''.
 
* To add a new grouping attribute, click '''Add'''. The Add Grouping Attribute dialog appears. Select the desired mapped attribute and click '''OK'''.
 
* To change the order of the grouping attributes, select an existing attribute and click '''Up''' or '''Down'''.
 
* To change the order of the grouping attributes, select an existing attribute and click '''Up''' or '''Down'''.
Line 1,044: Line 1,002:
  
 
Select one of the four following actions for '''Ordering Attributes''' (<tt>ReportQuery</tt> only):
 
Select one of the four following actions for '''Ordering Attributes''' (<tt>ReportQuery</tt> only):
 
 
* To add a new ordering attribute, click '''Add'''. The Add Ordering Attribute dialog box appears. Continue with [[#Adding Ordering Attributes|Adding Ordering Attributes]].
 
* To add a new ordering attribute, click '''Add'''. The Add Ordering Attribute dialog box appears. Continue with [[#Adding Ordering Attributes|Adding Ordering Attributes]].
 
* To change the order of the ordering attributes, select an existing attribute and click '''Up''' or '''Down'''.
 
* To change the order of the ordering attributes, select an existing attribute and click '''Up''' or '''Down'''.
Line 1,053: Line 1,010:
  
 
=====Adding Ordering Attributes=====
 
=====Adding Ordering Attributes=====
 
 
Use this dialog box to add a report query ordering attribute.
 
Use this dialog box to add a report query ordering attribute.
  
Line 1,088: Line 1,044:
 
: [[#Configuring Named Query Attributes|Configuring Named Query Attributes]]
 
: [[#Configuring Named Query Attributes|Configuring Named Query Attributes]]
  
====Creating an EIS Interaction for a Named Query====
 
  
 +
 +
====Creating an EIS Interaction for a Named Query====
 
For an EIS root descriptor, you can define EIS interactions to invoke methods on an EIS.
 
For an EIS root descriptor, you can define EIS interactions to invoke methods on an EIS.
  
Line 1,127: Line 1,084:
 
| id="r7c1-t21" headers="r1c1-t21" align="left" | '''Output Arguments'''
 
| id="r7c1-t21" headers="r1c1-t21" align="left" | '''Output Arguments'''
 
| headers="r7c1-t21 r1c2-t21" align="left" |
 
| headers="r7c1-t21 r1c2-t21" align="left" |
Specify the result record field or XPath nodes to map the correct nodes in the record used by the descriptor's mappings. For example, if you are using XML records, use this option to map the output <tt>fname</tt> to <tt>name/first-name</tt>.Output arguments are not required if the interaction returns an XML result that matches the descriptor's mappings.
+
Specify the result record field or XPath nodes to map the correct nodes in the record used by the descriptor's mappings. For example, if you are using XML records, use this option to map the output <tt>fname</tt> to <tt>name/first-name</tt>.
 +
 
 +
Output arguments are not required if the interaction returns an XML result that matches the descriptor's mappings.
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r8c1-t21" headers="r1c1-t21" align="left" | '''Input Result Path'''
 
| id="r8c1-t21" headers="r1c1-t21" align="left" | '''Input Result Path'''
Line 1,143: Line 1,102:
 
<br>
 
<br>
  
====Configuring Named Query Options====
 
  
 +
====Configuring Named Query Options====
 
Use this tab to configure additional options for the query.
 
Use this tab to configure additional options for the query.
  
Line 1,161: Line 1,120:
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r2c1-t22" headers="r1c1-t22" align="left" |
 
| id="r2c1-t22" headers="r1c1-t22" align="left" |
'''Refresh Identity Map Results'''<sup>Foot 2</sup>
+
'''Refresh Identity Map Results'''<sup> 2</sup>
 
| headers="r2c1-t22 r1c2-t22" align="left" | Refreshes the attributes of the object(s) resulting from the query. If cascading is used, the private parts of the objects will also be refreshed.
 
| headers="r2c1-t22 r1c2-t22" align="left" | Refreshes the attributes of the object(s) resulting from the query. If cascading is used, the private parts of the objects will also be refreshed.
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r3c1-t22" headers="r1c1-t22" align="left" |
 
| id="r3c1-t22" headers="r1c1-t22" align="left" |
'''Cache Statement'''<sup>Foot 1 </sup>
+
'''Cache Statement'''<sup> 1 </sup>
 
| headers="r3c1-t22 r1c2-t22" align="left" | Caches the prepared statements. This requires full parameter binding as well (see '''Bind Parameters''').
 
| headers="r3c1-t22 r1c2-t22" align="left" | Caches the prepared statements. This requires full parameter binding as well (see '''Bind Parameters''').
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r4c1-t22" headers="r1c1-t22" align="left" |
 
| id="r4c1-t22" headers="r1c1-t22" align="left" |
'''Bind Parameters'''<sup>Foot 1</sup>
+
'''Bind Parameters'''<sup> 1</sup>
 
| headers="r4c1-t22 r1c2-t22" align="left" |
 
| headers="r4c1-t22 r1c2-t22" align="left" |
 
By default, EclipseLink binds all of the query's parameters. Deselect this option to disable binding.
 
By default, EclipseLink binds all of the query's parameters. Deselect this option to disable binding.
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r5c1-t22" headers="r1c1-t22" align="left" |
 
| id="r5c1-t22" headers="r1c1-t22" align="left" |
'''Cache Usage'''<sup>Foot 2 </sup>
+
'''Cache Usage'''<sup> 2 </sup>
 
| headers="r5c1-t22 r1c2-t22" align="left" |
 
| headers="r5c1-t22 r1c2-t22" align="left" |
 
Selects how EclipseLink should use the session cache when a query is executed:
 
Selects how EclipseLink should use the session cache when a query is executed:
Line 1,184: Line 1,143:
 
* Check cache only
 
* Check cache only
 
* Conform results in unit of workFor more information, see the following:
 
* Conform results in unit of workFor more information, see the following:
* [[Introduction%20to%20EclipseLink%20Queries%20(ELUG)|Configuring Cache Usage for In-Memory Queries]].
+
* [[Introduction%20to%20EclipseLink%20Queries%20(ELUG)#Configuring Cache Usage for In-Memory Queries|Configuring Cache Usage for In-Memory Queries]].
* [[#Configuring Unit of Work Conforming at the Descriptor Level]]
+
* [[#Configuring Unit of Work Conforming at the Descriptor Level|Configuring Unit of Work Conforming at the Descriptor Level]]
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r6c1-t22" headers="r1c1-t22" align="left" |
 
| id="r6c1-t22" headers="r1c1-t22" align="left" |
'''In Memory Query Indirection'''<sup>Foot 2</sup>
+
'''In Memory Query Indirection'''<sup> 2</sup>
 
| headers="r6c1-t22 r1c2-t22" align="left" |
 
| headers="r6c1-t22 r1c2-t22" align="left" |
 
Selects how EclipseLink should handle indirection (lazy loading) when an in-memory or conforming query is executed:
 
Selects how EclipseLink should handle indirection (lazy loading) when an in-memory or conforming query is executed:
* Throw indirection exception–if this object uses indirection and indirection has not been triggered, EclipseLink will throw an exception.
+
* Throw indirection exception – if this object uses indirection and indirection has not been triggered, EclipseLink will throw an exception.
* Trigger indirection–if this object uses indirection and indirection has not been triggered, EclipseLink will trigger indirection.
+
* Trigger indirection – if this object uses indirection and indirection has not been triggered, EclipseLink will trigger indirection.
* Ignore exception return conformed–returns conforming if an untriggered value holder is encountered. That is, you expect results from the database to conform, and an untriggered value holder is taken to mean that the underlying attribute has not changed.
+
* Ignore exception return conformed – returns conforming if an untriggered value holder is encountered. That is, you expect results from the database to conform, and an untriggered value holder is taken to mean that the underlying attribute has not changed.
* Ignore exception return not conformed–returns not conforming if an untriggered value holder is encountered.For more information, see the following:
+
* Ignore exception return not conformed – returns not conforming if an untriggered value holder is encountered.
* [[Introduction%20to%20EclipseLink%20Queries%20(ELUG)|Handling Exceptions Resulting from In-Memory Queries]].
+
 
* [[Introduction%20to%20Mappings%20(ELUG)|Indirection (Lazy Loading)]].
+
For more information, see the following:
 +
* [[Introduction%20to%20EclipseLink%20Queries%20(ELUG)#Handling Exceptions Resulting from In-Memory Queries|Handling Exceptions Resulting from In-Memory Queries]].
 +
* [[Introduction%20to%20Mappings%20(ELUG)#Indirection (Lazy Loading)|Indirection (Lazy Loading)]].
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r7c1-t22" headers="r1c1-t22" align="left" |
 
| id="r7c1-t22" headers="r1c1-t22" align="left" |
'''Return Choice'''<sup>Foot 3 </sup>
+
'''Return Choice'''<sup> 3 </sup>
 
| headers="r7c1-t22 r1c2-t22" align="left" |
 
| headers="r7c1-t22 r1c2-t22" align="left" |
 
Selects how EclipseLink should handle <tt>ReportQuery</tt> results:
 
Selects how EclipseLink should handle <tt>ReportQuery</tt> results:
* Result collection–return <tt>ReportQuery</tt> results as a <tt>Collection</tt> of <tt>ReportQueryResult</tt> objects.
+
* Result collection – return <tt>ReportQuery</tt> results as a <tt>Collection</tt> of <tt>ReportQueryResult</tt> objects.
* Single result–return only the first <tt>ReportQueryResult</tt> object (not wrapped in a <tt>Collection</tt> or <tt>Map</tt>). Use this option if you know that the <tt>ReportQuery</tt> returns only one row.
+
* Single result – return only the first <tt>ReportQueryResult</tt> object (not wrapped in a <tt>Collection</tt> or <tt>Map</tt>). Use this option if you know that the <tt>ReportQuery</tt> returns only one row.
* Single value–return only a single value. Use this option if you know that the <tt>ReportQuery</tt> returns only one row that contains only one attribute.
+
* Single value – return only a single value. Use this option if you know that the <tt>ReportQuery</tt> returns only one row that contains only one attribute.
* Single attribute–return only a single <tt>Collection</tt> of values. If the query returns multiple rows, but each row only has a single attribute, this option will return a <tt>Collection</tt> of values, instead of a <tt>Collection</tt> of <tt>ReportQueryResults</tt>.For more information, see [[Introduction%20to%20EclipseLink%20Queries%20(ELUG)|Collection Query Results]].
+
* Single attribute – return only a single <tt>Collection</tt> of values. If the query returns multiple rows, but each row only has a single attribute, this option will return a <tt>Collection</tt> of values, instead of a <tt>Collection</tt> of <tt>ReportQueryResults</tt>.
 +
 
 +
For more information, see [[Introduction%20to%20EclipseLink%20Queries%20(ELUG)#Collection Query Results|Collection Query Results]].
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r8c1-t22" headers="r1c1-t22" align="left" |
 
| id="r8c1-t22" headers="r1c1-t22" align="left" |
'''Retrieve Primary Keys'''<sup>Foot 3</sup>
+
'''Retrieve Primary Keys'''<sup> 3</sup>
 
| headers="r8c1-t22 r1c2-t22" align="left" |
 
| headers="r8c1-t22 r1c2-t22" align="left" |
 
Selects whether or not EclipseLink retrieves the primary key values within each result. You can use the primary keys to retrieve the real objects.
 
Selects whether or not EclipseLink retrieves the primary key values within each result. You can use the primary keys to retrieve the real objects.
* None–do not retrieve primary keys
+
* None – do not retrieve primary keys
* All–retrieve primary keys for each object read;
+
* All – retrieve primary keys for each object read;
* First–return only the first primary key value (in the case of a composite primary key). This can be used if you just want to know if something exists or not, but do not really care about the value.
+
* First – return only the first primary key value (in the case of a composite primary key). This can be used if you just want to know if something exists or not, but do not really care about the value.
 
|}
 
|}
  
<br><sup>Footnote 1 </sup> For more information, see [[Optimizing%20the%20EclipseLink%20Application%20(ELUG)|How to Use Parameterized SQL (Parameter Binding) and Prepared Statement Caching for Optimization]].<br><sup>Footnote 2 </sup>For <tt>ReadObjectQuery</tt> and <tt>ReadAllQuery</tt> queries only.<br><sup>Footnote 3 </sup>For <tt>ReportQuery</tt> queries only.<br>
+
<br><sup> 1 </sup> For more information, see [[Optimizing%20the%20EclipseLink%20Application%20(ELUG)|How to Use Parameterized SQL (Parameter Binding) and Prepared Statement Caching for Optimization]].<br><sup> 2 </sup>For <tt>ReadObjectQuery</tt> and <tt>ReadAllQuery</tt> queries only.<br><sup> 3 </sup>For <tt>ReportQuery</tt> queries only.<br>
  
Click '''Advanced''' to configure additional options. See [[#Configuring Named Query Advanced Options]].
+
Click '''Advanced''' to configure additional options. See [[#Configuring Named Query Advanced Options|Configuring Named Query Advanced Options]].
  
 
'''See Also'''
 
'''See Also'''
: [[#Configuring Named Queries at the Descriptor Level]]
+
: [[#Configuring Named Queries at the Descriptor Level|Configuring Named Queries at the Descriptor Level]]
  
====Configuring Named Query Advanced Options====
 
  
 +
 +
====Configuring Named Query Advanced Options====
 
To configure additional advanced query options, use this procedure.
 
To configure additional advanced query options, use this procedure.
  
# From the Named Queries – Options tab, click '''Advanced'''. The Advanced Query Options dialog box appears.From the Named Queries – Options tab, click '''Advanced'''. The Advanced Query Options dialog box appears.<br><span id="Figure 115-19"></span>''''' Advanced Query Options Dialog Box'''''<br>[[Image:advqropt.gif|Advanced Query Options Dialog Box]<br><br>
+
# From the Named Queries Options tab, click '''Advanced'''. The Advanced Query Options dialog box appears.From the Named Queries Options tab, click '''Advanced'''. The Advanced Query Options dialog box appears.<br><span id="Figure 115-19"></span>''''' Advanced Query Options Dialog Box'''''<br>[[Image:advqropt.gif|Advanced Query Options Dialog Box]]<br><br>
 
# Complete each field in the Advanced Query Options dialog box.
 
# Complete each field in the Advanced Query Options dialog box.
  
Line 1,239: Line 1,203:
 
| id="r2c1-t23" headers="r1c1-t23" align="left" | '''Maintain Cache'''
 
| id="r2c1-t23" headers="r1c1-t23" align="left" | '''Maintain Cache'''
 
| headers="r2c1-t23 r1c2-t23" align="left" |
 
| headers="r2c1-t23 r1c2-t23" align="left" |
Specify whether to use the cache for the query or to build objects directly from the database result. You should only use this option if you are executing a partial object query (see [[Introduction%20to%20EclipseLink%20Queries%20(ELUG)|Partial Object Queries]]), whose results cannot be cached. For more information, see [[Introduction%20to%20EclipseLink%20Queries%20(ELUG)|How to Disable the Identity Map Cache Update During a Read Query]].
+
Specify whether to use the cache for the query or to build objects directly from the database result. You should only use this option if you are executing a [[Introduction%20to%20EclipseLink%20Queries%20(ELUG)#Partial Object Queries|Partial Object Query]], whose results cannot be cached. For more information, see [[Introduction%20to%20EclipseLink%20Queries%20(ELUG)#How to Disable the Identity Map Cache Update During a Read Query|How to Disable the Identity Map Cache Update During a Read Query]].
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r3c1-t23" headers="r1c1-t23" align="left" | '''Use Wrapper Policy'''
 
| id="r3c1-t23" headers="r1c1-t23" align="left" | '''Use Wrapper Policy'''
 
| headers="r3c1-t23 r1c2-t23" align="left" |
 
| headers="r3c1-t23 r1c2-t23" align="left" |
Specify whether or not the named query will use the wrapper policy configured for this descriptor. For more information, see [[#Configuring Wrapper Policy].
+
Specify whether or not the named query will use the wrapper policy configured for this descriptor. For more information, see [[#Configuring Wrapper Policy|Configuring Wrapper Policy]].
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r4c1-t23" headers="r1c1-t23" align="left" | '''Prepare SQL Once'''
 
| id="r4c1-t23" headers="r1c1-t23" align="left" | '''Prepare SQL Once'''
Line 1,253: Line 1,217:
 
| id="r5c1-t23" headers="r1c1-t23" align="left" | '''Cache Query Results'''
 
| id="r5c1-t23" headers="r1c1-t23" align="left" | '''Cache Query Results'''
 
| headers="r5c1-t23 r1c2-t23" align="left" |
 
| headers="r5c1-t23 r1c2-t23" align="left" |
Specify the <tt>cacheQueryResults</tt> method for the query. The query will only access the database the first time it is executed. Subsequent execution will return exactly the original result. For more information, see [[Using%20Advanced%20Query%20API%20(ELUG)|How to Cache Results in a ReadQuery]].
+
Specify the <tt>cacheQueryResults</tt> method for the query. The query will only access the database the first time it is executed. Subsequent execution will return exactly the original result. For more information, see [[Using%20Advanced%20Query%20API%20(ELUG)#How to Cache Results in a ReadQuery|How to Cache Results in a ReadQuery]].
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r6c1-t23" headers="r1c1-t23" align="left" | '''Refresh Remote Identity Map Results'''
 
| id="r6c1-t23" headers="r1c1-t23" align="left" | '''Refresh Remote Identity Map Results'''
Line 1,260: Line 1,224:
 
| id="r7c1-t23" headers="r1c1-t23" align="left" | '''Exclusive Connection'''
 
| id="r7c1-t23" headers="r1c1-t23" align="left" | '''Exclusive Connection'''
 
| headers="r7c1-t23 r1c2-t23" align="left" |
 
| headers="r7c1-t23 r1c2-t23" align="left" |
Specify whether or not the named query will use an exclusive connection. You can also configure exclusive connection acquisition at the session level (see [[Configuring%20a%20Session%20(ELUG)|Configuring Connection Policy]].
+
Specify whether or not the named query will use an exclusive connection. You can also configure exclusive connection acquisition at the session level (see [[Configuring%20a%20Session%20(ELUG)#Configuring Connection Policy|Configuring Connection Policy]].
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r8c1-t23" headers="r1c1-t23" align="left" | '''Pessimistic Locking'''
 
| id="r8c1-t23" headers="r1c1-t23" align="left" | '''Pessimistic Locking'''
Line 1,278: Line 1,242:
  
 
'''See Also'''
 
'''See Also'''
: [[#Configuring Named Queries at the Descriptor Level]]
+
: [[#Configuring Named Queries at the Descriptor Level|Configuring Named Queries at the Descriptor Level]]
  
===How to Configure Named Queries at the Descriptor Level Using Java===
 
  
To configure named queries in Java, use a descriptor amendment method (see [[#Configuring Amendment Methods]]). [[#Example 115-1|Creating a Named Query with an Amendment Method]] illustrates an amendment method that creates a named query and adds it to the <tt>DescriptorQueryManager</tt>.
+
 
 +
===How to Configure Named Queries at the Descriptor Level Using Java===
 +
To configure named queries in Java, Use a [[#Configuring Amendment Methods|descriptor amendment method]]. The [[#Example 115-1|Creating a Named Query with an Amendment Method]] example illustrates an amendment method that creates a named query and adds it to the <tt>DescriptorQueryManager</tt>.
  
  
Line 1,305: Line 1,270:
  
 
==Configuring Query Timeout at the Descriptor Level==
 
==Configuring Query Timeout at the Descriptor Level==
 
 
You can specify how the EclipseLink runtime handles the duration of queries on a descriptor's reference class. Specifying a query timeout at the descriptor level applies to all queries on the descriptor's reference class. A query timeout ensures that your application does not block forever over a hung or lengthy query that does not return in a timely fashion.
 
You can specify how the EclipseLink runtime handles the duration of queries on a descriptor's reference class. Specifying a query timeout at the descriptor level applies to all queries on the descriptor's reference class. A query timeout ensures that your application does not block forever over a hung or lengthy query that does not return in a timely fashion.
  
Line 1,312: Line 1,276:
  
 
<span id="Table 115-9"></span>
 
<span id="Table 115-9"></span>
''''' Descriptor Support for Cache Refresh'''''
 
  
 
{| class="RuleFormal" dir="ltr" title="Descriptor Support for Cache Refresh" summary="This table summarizes which descriptors support for cache refresh." width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
 
{| class="RuleFormal" dir="ltr" title="Descriptor Support for Cache Refresh" summary="This table summarizes which descriptors support for cache refresh." width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
! id="r1c1-t24" align="left" valign="bottom" | '''Descriptor'''
 
! id="r1c1-t24" align="left" valign="bottom" | '''Descriptor'''
! id="r1c2-t24" align="left" valign="bottom" | '''[[#How to Configure Query Timeout at the Descriptor Level Workbench]]<br>'''
+
! id="r1c2-t24" align="left" valign="bottom" | '''[[#How to Configure Query Timeout at the Descriptor Level Workbench|Using the Workbench]]<br>'''
! id="r1c3-t24" align="left" valign="bottom" | '''[[#How to Configure Query Timeout at the Descriptor Level Java]]<br>'''
+
! id="r1c3-t24" align="left" valign="bottom" | '''[[#How to Configure Query Timeout at the Descriptor Level Java|Using Java]]<br>'''
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r2c1-t24" headers="r1c1-t24" align="left" |
 
| id="r2c1-t24" headers="r1c1-t24" align="left" |
Relational Descriptors <sup>Foot 1 </sup>
+
Relational Descriptors <sup> 1 </sup>
 
| headers="r2c1-t24 r1c2-t24" align="left" |
 
| headers="r2c1-t24 r1c2-t24" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
| headers="r2c1-t24 r1c3-t24" align="left" |
 
| headers="r2c1-t24 r1c3-t24" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r3c1-t24" headers="r1c1-t24" align="left" |
 
| id="r3c1-t24" headers="r1c1-t24" align="left" |
 
Object-Relational Data Type Descriptors
 
Object-Relational Data Type Descriptors
 
| headers="r3c1-t24 r1c2-t24" align="left" |
 
| headers="r3c1-t24 r1c2-t24" align="left" |
Unsupported<br>
+
[[Image:unsupport.gif|Unsupported]]<br>
 
| headers="r3c1-t24 r1c3-t24" align="left" |
 
| headers="r3c1-t24 r1c3-t24" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r4c1-t24" headers="r1c1-t24" align="left" |
 
| id="r4c1-t24" headers="r1c1-t24" align="left" |
 
EIS Descriptor
 
EIS Descriptor
 
| headers="r4c1-t24 r1c2-t24" align="left" |
 
| headers="r4c1-t24 r1c2-t24" align="left" |
Unsupported<br>
+
[[Image:unsupport.gif|Unsupported]]<br>
 
| headers="r4c1-t24 r1c3-t24" align="left" |
 
| headers="r4c1-t24 r1c3-t24" align="left" |
Unsupported<br>
+
[[Image:unsupport.gif|Unsupported]]<br>
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r5c1-t24" headers="r1c1-t24" align="left" |
 
| id="r5c1-t24" headers="r1c1-t24" align="left" |
 
XML Descriptors
 
XML Descriptors
 
| headers="r5c1-t24 r1c2-t24" align="left" |
 
| headers="r5c1-t24 r1c2-t24" align="left" |
Unsupported<br>
+
[[Image:unsupport.gif|Unsupported]]<br>
 
| headers="r5c1-t24 r1c3-t24" align="left" |
 
| headers="r5c1-t24 r1c3-t24" align="left" |
Unsupported<br>
+
[[Image:unsupport.gif|Unsupported]]<br>
 
|}
 
|}
  
<br><sup>Footnote 1 </sup>Relational class descriptors only (see [[Creating%20a%20Relational%20Descriptor%20(ELUG)|Creating Relational Class Descriptors]]).<br>
+
<br><sup> 1 </sup>[[Creating%20a%20Relational%20Descriptor%20(ELUG)#Creating Relational Class Descriptors|Relational Class Descriptors]] only.<br>
  
 
You can also configure a timeout on a per-query basis. For more information, see the following:
 
You can also configure a timeout on a per-query basis. For more information, see the following:
 
+
* [[#Configuring Named Query Advanced Options|Configuring Named Query Advanced Options]]
* [[#Configuring Named Query Advanced Options]]
+
* [[Using%20Basic%20Query%20API%20(ELUG)#Configuring Query Timeout at the Query Level|Configuring Query Timeout at the Query Level]]
* [[Using%20Basic%20Query%20API%20(ELUG)|Configuring Query Timeout at the Query Level]]
+
  
  
  
 
===How to Configure Query Timeout at the Descriptor Level Workbench===
 
===How to Configure Query Timeout at the Descriptor Level Workbench===
 
 
To configure how EclipseLink handles the duration of queries to this descriptor, use this procedure:
 
To configure how EclipseLink handles the duration of queries to this descriptor, use this procedure:
 
 
# Select a descriptor in the '''Navigator'''. Its properties appear in the Editor.
 
# Select a descriptor in the '''Navigator'''. Its properties appear in the Editor.
 
# Click the '''Queries''' tab. The Queries tab appears.
 
# Click the '''Queries''' tab. The Queries tab appears.
Line 1,386: Line 1,346:
  
 
'''See Also'''
 
'''See Also'''
: [[#Configuring Query Timeout at the Descriptor Level]]
+
: [[#Configuring Query Timeout at the Descriptor Level|Configuring Query Timeout at the Descriptor Level]]
  
  
  
 
===How to Configure Query Timeout at the Descriptor Level Java===
 
===How to Configure Query Timeout at the Descriptor Level Java===
 
 
Use <tt>DescriptorQueryManager</tt> method <tt>setQueryTimeout</tt> passing in the timeout value as a number of milliseconds.
 
Use <tt>DescriptorQueryManager</tt> method <tt>setQueryTimeout</tt> passing in the timeout value as a number of milliseconds.
  
==Configuring Cache Refreshing==
 
  
 +
 +
==Configuring Cache Refreshing==
 
By default, EclipseLink caches objects read from a data source (see [[Introduction%20to%20Cache%20(ELUG)|Introduction to Cache]]). Subsequent queries for these objects will access the cache and thus improve performance by reducing data source access and avoiding the cost of rebuilding object's and their relationships. Even if a query, such as a read-all query, accesses the data source, if the objects corresponding to the records returned are in the cache, EclipseLink will use the cache objects.
 
By default, EclipseLink caches objects read from a data source (see [[Introduction%20to%20Cache%20(ELUG)|Introduction to Cache]]). Subsequent queries for these objects will access the cache and thus improve performance by reducing data source access and avoiding the cost of rebuilding object's and their relationships. Even if a query, such as a read-all query, accesses the data source, if the objects corresponding to the records returned are in the cache, EclipseLink will use the cache objects.
  
This can lead to stale data in the application. Although using an appropriate locking policy (see [[#Configuring Locking Policy]]) is the only way to ensure that stale or conflicting data does not get committed to the data source, sometimes certain data in the application changes so frequently that it is desirable to always refresh the data, instead of only refreshing the data when a conflict is detected.
+
This can lead to stale data in the application. Although using an appropriate [[#Configuring Locking Policy|locking policy]] is the only way to ensure that stale or conflicting data does not get committed to the data source, sometimes certain data in the application changes so frequently that it is desirable to always refresh the data, instead of only refreshing the data when a conflict is detected.
  
 
You can specify how the EclipseLink runtime handles cache refreshing for all queries on a descriptor's reference class.
 
You can specify how the EclipseLink runtime handles cache refreshing for all queries on a descriptor's reference class.
Line 1,405: Line 1,365:
  
  
<span id="'Table 115-10"></span.
+
<span id="'Table 115-10"></span>
'''' Descriptor Support for Query Cache Refresh'''''
+
  
 
{| class="RuleFormal" dir="ltr" title="Descriptor Support for Query Cache Refresh" summary="This table summarizes which descriptors support for Query Cache Refresh." width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
 
{| class="RuleFormal" dir="ltr" title="Descriptor Support for Query Cache Refresh" summary="This table summarizes which descriptors support for Query Cache Refresh." 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" | '''Descriptor'''
 
! id="r1c1-t26" align="left" valign="bottom" | '''Descriptor'''
! id="r1c2-t26" align="left" valign="bottom" | '''[[#How to Configure Cache Refreshing Using Workbench]]<br>'''
+
! id="r1c2-t26" align="left" valign="bottom" | '''[[#How to Configure Cache Refreshing Using Workbench|Using the Workbench]]<br>'''
! id="r1c3-t26" align="left" valign="bottom" | '''[[#CHDFDJGJ1 How to Configure Cache Refreshing Using Java]]<br>'''
+
! id="r1c3-t26" align="left" valign="bottom" | '''[[#How to Configure Cache Refreshing Using Java|Using Java]]<br>'''
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r2c1-t26" headers="r1c1-t26" align="left" |
 
| id="r2c1-t26" headers="r1c1-t26" align="left" |
Relational Descriptors <sup>Foot 1 </sup>
+
Relational Descriptors <sup> 1 </sup>
 
| headers="r2c1-t26 r1c2-t26" align="left" |
 
| headers="r2c1-t26 r1c2-t26" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
| headers="r2c1-t26 r1c3-t26" align="left" |
 
| headers="r2c1-t26 r1c3-t26" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r3c1-t26" headers="r1c1-t26" align="left" |
 
| id="r3c1-t26" headers="r1c1-t26" align="left" |
 
Object-Relational Data Type Descriptors
 
Object-Relational Data Type Descriptors
 
| headers="r3c1-t26 r1c2-t26" align="left" |
 
| headers="r3c1-t26 r1c2-t26" align="left" |
Unsupported<br>
+
[[Image:unsupport.gif|Unsupported]]<br>
 
| headers="r3c1-t26 r1c3-t26" align="left" |
 
| headers="r3c1-t26 r1c3-t26" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r4c1-t26" headers="r1c1-t26" align="left" |
 
| id="r4c1-t26" headers="r1c1-t26" align="left" |
EIS Descriptor[#sthref4461 <sup>Foot 2 </sup>]
+
EIS Descriptor <sup> 2 </sup>
 
| headers="r4c1-t26 r1c2-t26" align="left" |
 
| headers="r4c1-t26 r1c2-t26" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
| headers="r4c1-t26 r1c3-t26" align="left" |
 
| headers="r4c1-t26 r1c3-t26" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r5c1-t26" headers="r1c1-t26" align="left" |
 
| id="r5c1-t26" headers="r1c1-t26" align="left" |
 
XML Descriptors
 
XML Descriptors
 
| headers="r5c1-t26 r1c2-t26" align="left" |
 
| headers="r5c1-t26 r1c2-t26" align="left" |
Unsupported<br>
+
[[Image:unsupport.gif|Unsupported]]<br>
 
| headers="r5c1-t26 r1c3-t26" align="left" |
 
| headers="r5c1-t26 r1c3-t26" align="left" |
Unsupported<br>
+
[[Image:unsupport.gif|Unsupported]]<br>
 
|}
 
|}
  
<br><sup>Footnote 1 </sup>Relational class descriptors only (see [[Creating%20a%20Relational%20Descriptor%20(ELUG)|Creating Relational Class Descriptors]]).<br><sup>Footnote 2 </sup>EIS root descriptors only (see [[Creating%20an%20EIS%20Descriptor%20(ELUG)|EIS Root Descriptors]]).<br>
+
<br><sup> 1 </sup>[[Creating%20a%20Relational%20Descriptor%20(ELUG)#Creating Relational Class Descriptors|Relational Class Descriptors]] only.<br><sup> 2 </sup>[[Creating%20an%20EIS%20Descriptor%20(ELUG)#EIS Root Descriptors|EIS Root Descriptors]] only.<br>
  
 
Configuring descriptor-level cache refresh may affect performance. As an alternative, consider configuring the following:
 
Configuring descriptor-level cache refresh may affect performance. As an alternative, consider configuring the following:
 +
* [[Introduction%20to%20EclipseLink%20Queries%20(ELUG)#How to Refresh the Cache|cache refresh on a query-by-query basis]]
 +
* [[#Configuring Cache Expiration at the Descriptor Level|cache expiration]]
 +
* [[Introduction%20to%20Cache%20(ELUG)#Cache Isolation|isolated caching ]]
  
* cache refresh on a query-by-query basis (see [[Introduction%20to%20EclipseLink%20Queries%20(ELUG)|How to Refresh the Cache]])
+
For more information, see [[Optimizing%20the%20EclipseLink%20Application%20(ELUG)#Optimizing Cache|Optimizing Cache]].
* cache expiration (see [[#Configuring Cache Expiration at the Descriptor Level]])
+
* isolated caching (see [[Introduction%20to%20Cache%20(ELUG)|Cache Isolation]])
+
 
+
For more information, see [[Optimizing%20the%20EclipseLink%20Application%20(ELUG)|Optimizing Cache]].
+
  
  
  
 
===How to Configure Cache Refreshing Using Workbench===
 
===How to Configure Cache Refreshing Using Workbench===
 
 
To configure how EclipseLink refreshes the cache for queries to this descriptor, use this procedure:
 
To configure how EclipseLink refreshes the cache for queries to this descriptor, use this procedure:
 
 
# Select a descriptor in the '''Navigator'''. Its properties appear in the Editor.
 
# Select a descriptor in the '''Navigator'''. Its properties appear in the Editor.
 
# Click the '''Queries''' tab. The Queries tab appears.
 
# Click the '''Queries''' tab. The Queries tab appears.
# Click the '''Settings''' tab. The Settings tab appears.<br>'''''Figure 115-21 Descriptor Queries Settings Tab, Cache Refreshing Options'''''[[Image:descache.gif|Descriptor Queries Settings Tab, Cache Refreshing Options]]<br><br>
+
# Click the '''Settings''' tab. The Settings tab appears.<br><span id="Figure 115-21"></span>''''' Descriptor Queries Settings Tab, Cache Refreshing Options'''''<br>[[Image:descache.gif|Descriptor Queries Settings Tab, Cache Refreshing Options]]<br><br>
# Select the [topicid:descriptor.transactional.refreshCache Refreshing Cache options] on the tab.
+
# Select the Refreshing Cache options on the tab.
  
 
Use the following table to enter data in the fields on the descriptor's '''Settings''' tab to specify how EclipseLink will refresh the cache for queries:
 
Use the following table to enter data in the fields on the descriptor's '''Settings''' tab to specify how EclipseLink will refresh the cache for queries:
Line 1,473: Line 1,429:
 
| id="r2c1-t27" headers="r1c1-t27" align="left" | '''Always Refresh'''
 
| id="r2c1-t27" headers="r1c1-t27" align="left" | '''Always Refresh'''
 
| headers="r2c1-t27 r1c2-t27" align="left" |
 
| headers="r2c1-t27 r1c2-t27" align="left" |
Refreshes the cache on all queries. Avoids stale data by ensuring that any query that accesses the data source will refresh the resulting objects in the cache. This has no effect on queries that get a cache hit and never access the data source, such as read-object primary key queries or in-memory queries.Configuring descriptor level cache refresh may affect performance. As an alternative, consider configuring:
+
Refreshes the cache on all queries. Avoids stale data by ensuring that any query that accesses the data source will refresh the resulting objects in the cache. This has no effect on queries that get a cache hit and never access the data source, such as read-object primary key queries or in-memory queries.
* cache refresh on a query-by-query basis (see [[Introduction%20to%20EclipseLink%20Queries%20(ELUG)|How to Refresh the Cache]])
+
 
* cache expiration (see [[#Configuring Cache Expiration at the Descriptor Level]])
+
Configuring descriptor level cache refresh may affect performance. As an alternative, consider configuring:
* isolated caching (see [[Introduction%20to%20Cache%20(ELUG)|Cache Isolation]])
+
* [[Introduction%20to%20EclipseLink%20Queries%20(ELUG)#How to Refresh the Cache|cache refresh on a query-by-query basis]]
 +
* [[#Configuring Cache Expiration at the Descriptor Level|cache expiration]]
 +
* [[Introduction%20to%20Cache%20(ELUG)#Cache Isolation|isolated caching]]
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r3c1-t27" headers="r1c1-t27" align="left" | '''Only Refresh If Newer Version'''
 
| id="r3c1-t27" headers="r1c1-t27" align="left" | '''Only Refresh If Newer Version'''
 
| headers="r3c1-t27 r1c2-t27" align="left" |
 
| headers="r3c1-t27 r1c2-t27" align="left" |
Refreshes the cache only if the object in the database is newer than the object in the cache (as determined by the '''Optimistic Locking''' field). See [[#Configuring Locking Policy]] for more information. Improves performance by avoiding unnecessary refreshing of an object if its version matches the data source version. This option does not cause refreshing on its own: you must use it in combination with '''Always Refresh''', query refreshing (see [[Introduction%20to%20EclipseLink%20Queries%20(ELUG)|How to Refresh the Cache]]), or cache expiration (see [[#Configuring Cache Expiration at the Descriptor Level]]).
+
Refreshes the cache only if the object in the database is newer than the object in the cache (as determined by the '''Optimistic Locking''' field). See [[#Configuring Locking Policy|Configuring Locking Policy]] for more information. Improves performance by avoiding unnecessary refreshing of an object if its version matches the data source version. This option does not cause refreshing on its own: you must use it in combination with '''Always Refresh''', [[Introduction%20to%20EclipseLink%20Queries%20(ELUG)#How to Refresh the Cache|query refreshing]], or [[#Configuring Cache Expiration at the Descriptor Level|cache expiration]].
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r4c1-t27" headers="r1c1-t27" align="left" | '''Disable Cache Hits'''
 
| id="r4c1-t27" headers="r1c1-t27" align="left" | '''Disable Cache Hits'''
 
| headers="r4c1-t27 r1c2-t27" align="left" |
 
| headers="r4c1-t27 r1c2-t27" align="left" |
When selected, EclipseLink bypasses the cache and goes to the database for read object queries based on primary key. Using this option in conjunction with '''Always Refresh''' ensures that EclipseLink always goes to the database. This option ensures that all queries including read-object primary key queries will always access the data source. This option does not cause refreshing on its own: you must use it in combination with '''Always Refresh'''.This option can cause a serious performance issue: avoid whenever possible.
+
When selected, EclipseLink bypasses the cache and goes to the database for read object queries based on primary key. Using this option in conjunction with '''Always Refresh''' ensures that EclipseLink always goes to the database. This option ensures that all queries including read-object primary key queries will always access the data source. This option does not cause refreshing on its own: you must use it in combination with '''Always Refresh'''.
 +
 
 +
This option can cause a serious performance issue: avoid whenever possible.
 
|}
 
|}
  
Line 1,491: Line 1,451:
 
{| 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" |
''''''Caution'''<nowiki>:</nowiki>''' Use the '''Always Refresh''' and '''Disable Cache Hits''' properties with caution as they may lead to poor performance. As an alternative, consider configuring cache refresh on a query-by-query basis (see [[Introduction%20to%20EclipseLink%20Queries%20(ELUG)|How to Refresh the Cache]]) or configuring cache expiration (see [[#Configuring Cache Expiration at the Descriptor Level]]). For more information about cache performance, see [[Optimizing%20the%20EclipseLink%20Application%20(ELUG)|Optimizing Cache]].
+
'''Caution'''<nowiki>:</nowiki> Use the '''Always Refresh''' and '''Disable Cache Hits''' properties with caution as they may lead to poor performance. As an alternative, consider [[Introduction%20to%20EclipseLink%20Queries%20(ELUG)#How to Refresh the Cache|configuring cache refresh on a query-by-query basis]] or [[#Configuring Cache Expiration at the Descriptor Level|configuring cache expiration]]. For more information, see [[Optimizing%20the%20EclipseLink%20Application%20(ELUG)#Optimizing Cache|Optimizing Cache]].
 
|}
 
|}
  
 
<br>
 
<br>
  
'''See Also'''
+
 
: [[#Configuring Cache Refreshing]
+
: [[#Configuring a Descriptor]
+
  
 
===How to Configure Cache Refreshing Using Java===
 
===How to Configure Cache Refreshing Using Java===
 
 
Configure cache refresh options using the following <tt>ClassDescriptor</tt> methods:
 
Configure cache refresh options using the following <tt>ClassDescriptor</tt> methods:
 
 
* <tt>setShouldAlwaysRefreshCache</tt>
 
* <tt>setShouldAlwaysRefreshCache</tt>
 
* <tt>setShouldAlwaysRefreshCacheOnRemote</tt>
 
* <tt>setShouldAlwaysRefreshCacheOnRemote</tt>
Line 1,510: Line 1,466:
 
* <tt>setShouldOnlyRefreshCacheIfNewerVersion</tt>
 
* <tt>setShouldOnlyRefreshCacheIfNewerVersion</tt>
  
Use these methods in a descriptor amendment method (see [[#Configuring Amendment Methods]], as this example illustrates.
+
Use these methods in [[#Configuring Amendment Methods|a descriptor amendment method]], as this example illustrates.
  
  
Line 1,520: Line 1,476:
 
  }
 
  }
  
==Configuring Query Keys==
 
  
 +
 +
==Configuring Query Keys==
 
A '''query key''' is a schema-independent alias for a database field name. For example, consider a class <tt>Employee</tt> with attribute <tt>firstName</tt> mapped directly to a database field <tt>F_NAME</tt> in database table <tt>EMPLOYEE</tt>. Without a query key, when you create a query or expression that involves <tt>Employee</tt> attribute <tt>firstName</tt>, you must use the database management system-specific field name <tt>F_NAME</tt>. This makes it more difficult to build a query and ties the query to the schema. With a query key, you can refer to this field using a schema-independent alias, such as <tt>firstName</tt>.
 
A '''query key''' is a schema-independent alias for a database field name. For example, consider a class <tt>Employee</tt> with attribute <tt>firstName</tt> mapped directly to a database field <tt>F_NAME</tt> in database table <tt>EMPLOYEE</tt>. Without a query key, when you create a query or expression that involves <tt>Employee</tt> attribute <tt>firstName</tt>, you must use the database management system-specific field name <tt>F_NAME</tt>. This makes it more difficult to build a query and ties the query to the schema. With a query key, you can refer to this field using a schema-independent alias, such as <tt>firstName</tt>.
  
Line 1,528: Line 1,485:
  
 
<span id="Table 115-11"></span>
 
<span id="Table 115-11"></span>
''''' Descriptor Support for Query Keys'''''
 
  
 
{| class="RuleFormal" dir="ltr" title="Descriptor Support for Query Keys" summary="This table summarizes which descriptors support for query keys." width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
 
{| class="RuleFormal" dir="ltr" title="Descriptor Support for Query Keys" summary="This table summarizes which descriptors support for query keys." width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
! id="r1c1-t29" align="left" valign="bottom" | '''Descriptor'''
 
! id="r1c1-t29" align="left" valign="bottom" | '''Descriptor'''
! id="r1c2-t29" align="left" valign="bottom" | '''[[#How to Configure Query Keys Using Workbench]]<br>'''
+
! id="r1c2-t29" align="left" valign="bottom" | '''[[#How to Configure Query Keys Using Workbench|Using the Workbench]]<br>'''
! id="r1c3-t29" align="left" valign="bottom" | '''[[#How to Configure Query Keys Using Java]]<br>'''
+
! id="r1c3-t29" align="left" valign="bottom" | '''[[#How to Configure Query Keys Using Java|Using Java]]<br>'''
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r2c1-t29" headers="r1c1-t29" align="left" |
 
| id="r2c1-t29" headers="r1c1-t29" align="left" |
 
Relational Descriptors
 
Relational Descriptors
 
| headers="r2c1-t29 r1c2-t29" align="left" |
 
| headers="r2c1-t29 r1c2-t29" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
| headers="r2c1-t29 r1c3-t29" align="left" |
 
| headers="r2c1-t29 r1c3-t29" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r3c1-t29" headers="r1c1-t29" align="left" |
 
| id="r3c1-t29" headers="r1c1-t29" align="left" |
 
Object-Relational Data Type Descriptors
 
Object-Relational Data Type Descriptors
 
| headers="r3c1-t29 r1c2-t29" align="left" |
 
| headers="r3c1-t29 r1c2-t29" align="left" |
Unsupported<br>
+
[[Image:unsupport.gif|Unsupported]]<br>
 
| headers="r3c1-t29 r1c3-t29" align="left" |
 
| headers="r3c1-t29 r1c3-t29" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r4c1-t29" headers="r1c1-t29" align="left" |
 
| id="r4c1-t29" headers="r1c1-t29" align="left" |
 
EIS Descriptors
 
EIS Descriptors
 
| headers="r4c1-t29 r1c2-t29" align="left" |
 
| headers="r4c1-t29 r1c2-t29" align="left" |
Unsupported<br>
+
[[Image:unsupport.gif|Unsupported]]<br>
 
| headers="r4c1-t29 r1c3-t29" align="left" |
 
| headers="r4c1-t29 r1c3-t29" align="left" |
Unsupported<br>
+
[[Image:unsupport.gif|Unsupported]]<br>
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r5c1-t29" headers="r1c1-t29" align="left" |
 
| id="r5c1-t29" headers="r1c1-t29" align="left" |
 
XML Descriptors
 
XML Descriptors
 
| headers="r5c1-t29 r1c2-t29" align="left" |
 
| headers="r5c1-t29 r1c2-t29" align="left" |
Unsupported<br>
+
[[Image:unsupport.gif|Unsupported]]<br>
 
| headers="r5c1-t29 r1c3-t29" align="left" |
 
| headers="r5c1-t29 r1c3-t29" align="left" |
Unsupported<br>
+
[[Image:unsupport.gif|Unsupported]]<br>
 
|}
 
|}
  
Line 1,568: Line 1,524:
  
 
Using query keys offers the following advantages:
 
Using query keys offers the following advantages:
 
 
* Enhances code readability in EclipseLink expressions and simplifies expression development. You can compose expressions entirely within the context of your object model.
 
* Enhances code readability in EclipseLink expressions and simplifies expression development. You can compose expressions entirely within the context of your object model.
 
* Increases portability by making code independent of the database schema. If you rename a field in your schema, you can redefine the query key without changing any code that uses it.
 
* Increases portability by making code independent of the database schema. If you rename a field in your schema, you can redefine the query key without changing any code that uses it.
Line 1,575: Line 1,530:
 
Query keys are automatically generated for all mapped attributes. The name of the query key is the name of the class attribute specified in your object model.
 
Query keys are automatically generated for all mapped attributes. The name of the query key is the name of the class attribute specified in your object model.
  
For information on how to use query keys in queries and expressions, see [[Introduction%20to%20EclipseLink%20Queries%20(ELUG)|Query Keys]].
+
For information on how to use query keys in queries and expressions, see [[Introduction%20to%20EclipseLink%20Queries%20(ELUG)#Query Keys|Query Keys]].
  
 
When query keys are generated and how you can add or modify query keys depends on the type of mapping or descriptor involved:
 
When query keys are generated and how you can add or modify query keys depends on the type of mapping or descriptor involved:
 +
* [[#Direct Mappings|Direct Mappings]]
 +
* [[#Relationship Mappings|Relationship Mappings]]
 +
* [[#Interface Descriptors|Interface Descriptors]]
  
* [[#Direct Mappings]]
 
* [[#Relationship Mappings]]
 
* [[#Interface Descriptors]]
 
 
'''Direct Mappings'''
 
  
 +
==='''Direct Mappings'''===
 
Workbench automatically generates query keys for all direct mappings at the time you create the mapping.
 
Workbench automatically generates query keys for all direct mappings at the time you create the mapping.
  
 
Workbench provides support for adding or modifying query keys for simple unmapped attributes that could be mapped by a direct mapping: for example, the <tt>version</tt> field used for optimistic locking or the <tt>type</tt> field used for inheritance. You cannot modify or remove automatically generated query keys.
 
Workbench provides support for adding or modifying query keys for simple unmapped attributes that could be mapped by a direct mapping: for example, the <tt>version</tt> field used for optimistic locking or the <tt>type</tt> field used for inheritance. You cannot modify or remove automatically generated query keys.
  
'''Relationship Mappings'''
 
  
 +
==='''Relationship Mappings'''===
 
EclipseLink automatically generates query keys for all relationship mappings at run time.
 
EclipseLink automatically generates query keys for all relationship mappings at run time.
  
Line 1,597: Line 1,551:
 
The Workbench does not currently support adding or modifying the query keys for relationship mappings. If you must add or modify such a query key, you must do so in Java code, using a descriptor amendment method.
 
The Workbench does not currently support adding or modifying the query keys for relationship mappings. If you must add or modify such a query key, you must do so in Java code, using a descriptor amendment method.
  
'''Interface Descriptors'''
 
  
Interface descriptors (see [[Creating%20a%20Relational%20Descriptor%20(ELUG)|Creating Relational Interface Descriptors]]) define only the query keys that are shared among their implementors. In the descriptor for an interface, only the name of the query key is specified.
+
==='''Interface Descriptors'''===
 +
[[Creating%20a%20Relational%20Descriptor%20(ELUG)#Creating Relational Interface Descriptors|Interface descriptors]] define only the query keys that are shared among their implementors. In the descriptor for an interface, only the name of the query key is specified.
  
Workbench provides support for choosing the implementors of an interface that share at least one common automatically generated query key (see [[#Configuring Interface Query Keys]]).
+
Workbench provides support for choosing the implementors of an interface that share at least one common automatically generated [[#Configuring Interface Query Keys|query key]].
  
  
  
 
===How to Configure Query Keys Using Workbench===
 
===How to Configure Query Keys Using Workbench===
 
 
To add query keys to simple unmapped fields and to view the query keys automatically generated for directly mapped attributes, use this procedure:
 
To add query keys to simple unmapped fields and to view the query keys automatically generated for directly mapped attributes, use this procedure:
 
 
# Select a descriptor in the '''Navigator'''. Its properties appear in the Editor.
 
# Select a descriptor in the '''Navigator'''. Its properties appear in the Editor.
# Click the '''Query Keys''' tab in the '''Editor'''.<br>'''''Figure 115-22 Queries, Query Keys Tab'''''[[Image:querykey.gif|Description of Figure 115-22 follows]]<br>[img_text/querykey.htm Description of "Figure 115-22 Queries, Query Keys Tab"]<br><br>
+
# Click the '''Query Keys''' tab in the '''Editor'''.<br><span id="Figure 115-22"></span>''''' Queries, Query Keys Tab'''''<br>[[Image:querykey.gif|Queries, Query Keys Tab]]<br><br>
  
 
To add a new query key, click '''Add.'''
 
To add a new query key, click '''Add.'''
Line 1,623: Line 1,575:
  
 
===How to Configure Query Keys Using Java===
 
===How to Configure Query Keys Using Java===
 +
To manually create a relationship query key, implement a [[#Configuring Amendment Methods|descriptor amendment method]] that uses one of the following <tt>ClassDescriptor</tt> methods to register the query keys:
  
To manually create a relationship query key, implement a descriptor amendment method (see [[#Configuring Amendment Methods]) that uses one of the following <tt>ClassDescriptor</tt> methods to register the query keys:
+
* <tt>addQueryKey</tt> – specify a query key using an instance of <tt>QueryKey</tt> such as <tt>DirectQueryKey</tt>, <tt>DirectCollectionQueryKey</tt>, <tt>ManyToManyQueryKey</tt>, <tt>OneToManyQueryKey</tt>, or <tt>OneToOneQueryKey</tt>.
 +
* <tt>addDirectQueryKey</tt> – add a query key that maps directly to the given database field.
 +
* <tt>addAbstractQueryKey</tt> – add an abstract query key to an interface descriptor. Any implementors of that interface must define the query key defined by this abstract query key.
  
* <tt>addQueryKey</tt>–specify a query key using an instance of <tt>QueryKey</tt> such as <tt>DirectQueryKey</tt>, <tt>DirectCollectionQueryKey</tt>, <tt>ManyToManyQueryKey</tt>, <tt>OneToManyQueryKey</tt>, or <tt>OneToOneQueryKey</tt>.
+
The [[#Example 115-3|Defining a Query Key]], [[#Example 115-4|Defining a One-to-Many Query Key]], and [[#Example 115-5|Defining a Many-to-Many Query Key]] examples illustrate how to define a query key in Java code.
* <tt>addDirectQueryKey</tt>–add a query key that maps directly to the given database field.
+
* <tt>addAbstractQueryKey</tt>–add an abstract query key to an interface descriptor. Any implementors of that interface must define the query key defined by this abstract query key.
+
 
+
[[#Example 115-3]], [[#Example 115-4]], and [[#Example 115-5]] illustrate how to define a query key in Java code.
+
  
  
Line 1,656: Line 1,607:
  
 
<span id="Example 115-4"></span>
 
<span id="Example 115-4"></span>
''''' '''Defining a One-to-Many Query Key''''''''
+
''''' Defining a One-to-Many Query Key '''''
 
  '''// Add a one-to-many query key for the projects where the employee'''
 
  '''// Add a one-to-many query key for the projects where the employee'''
 
  '''// '''manages multiple projects  
 
  '''// '''manages multiple projects  
Line 1,676: Line 1,627:
 
  ExpressionBuilder builder = new ExpressionBuilder();
 
  ExpressionBuilder builder = new ExpressionBuilder();
 
  projectsQueryKey.setJoinCriteria(
 
  projectsQueryKey.setJoinCriteria(
     builder.getTable("EMP_PROJ").getField("EMP_ID").equal(
+
     (builder.getParameter("EMPLOYEE.EMP_ID").equal(
     builder.getParameter("EMPLOYEE.EMP_ID").and(
+
     builder.getTable("EMP_PROJ").getField("EMP_ID")).and(
 
     builder.getTable("EMP_PROJ").getField("PROJ_ID").equal(
 
     builder.getTable("EMP_PROJ").getField("PROJ_ID").equal(
     builder.getField("PROJECT.PROJ_ID")));
+
     builder.getField("PROJECT.PROJ_ID")))));
 
  descriptor.addQueryKey(projectsQueryKey);
 
  descriptor.addQueryKey(projectsQueryKey);
 
   
 
   
Line 1,685: Line 1,636:
  
  
[[#Example 115-6|Defining a One-to-One Query Key with an Amendment Method]] illustrates how to implement a <tt>Descriptor</tt> amendment method to define a one-to-one query key. In this example, the object model for the <tt>Address</tt> class does not include a reference to its owner, an <tt>Employee</tt> object. You can amend the <tt>Address</tt> class descriptor to add a query key named <tt>owner</tt> to make up for this deficiency. At run time, you can compose expressions that select <tt>Address</tt> objects based on this <tt>owner</tt> query key.
+
The [[#Example 115-6|Defining a One-to-One Query Key with an Amendment Method]] example illustrates how to implement a <tt>Descriptor</tt> amendment method to define a one-to-one query key. In this example, the object model for the <tt>Address</tt> class does not include a reference to its owner, an <tt>Employee</tt> object. You can amend the <tt>Address</tt> class descriptor to add a query key named <tt>owner</tt> to make up for this deficiency. At run time, you can compose expressions that select <tt>Address</tt> objects based on this <tt>owner</tt> query key.
  
  
Line 1,703: Line 1,654:
 
     descriptor.addQueryKey(ownerQueryKey);
 
     descriptor.addQueryKey(ownerQueryKey);
 
  }
 
  }
 
 
  
 
==Configuring Interface Query Keys==
 
==Configuring Interface Query Keys==
 +
A query key is a schema independent alias for a database field name. For more information about query keys, see [[#Configuring Query Keys|Configuring Query Keys]].
  
A query key is a schema independent alias for a database field name. For more information about query keys, see [[#Configuring Query Keys]].
+
[[Creating%20a%20Relational%20Descriptor%20(ELUG)#Creating Relational Interface Descriptors|Interface descriptors]] are defined only with query keys that are shared among their implementors. In the descriptor for an interface, only the name of the query key is specified.
 
+
Interface descriptors (see [[Creating%20a%20Relational%20Descriptor%20(ELUG)|Creating Relational Interface Descriptors]]) are defined only with query keys that are shared among their implementors. In the descriptor for an interface, only the name of the query key is specified.
+
  
 
In each implementor descriptor, the key must be defined with the appropriate field from one of the implementor descriptor's tables.
 
In each implementor descriptor, the key must be defined with the appropriate field from one of the implementor descriptor's tables.
Line 1,722: Line 1,670:
  
 
<span id="Table 115-12"></span>
 
<span id="Table 115-12"></span>
''''' Descriptor Support for Interface Query Keys'''''
 
 
 
{| class="RuleFormal" dir="ltr" title="Descriptor Support for Interface Query Keys" summary="This table summarizes which descriptors support for interface query keys." width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
 
{| class="RuleFormal" dir="ltr" title="Descriptor Support for Interface Query Keys" summary="This table summarizes which descriptors support for interface query keys." width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
! id="r1c1-t30" align="left" valign="bottom" | '''Descriptor'''
 
! id="r1c1-t30" align="left" valign="bottom" | '''Descriptor'''
! id="r1c2-t30" align="left" valign="bottom" | '''[[#How to Configure Interface Query Keys Using Workbench]]<br>'''
+
! id="r1c2-t30" align="left" valign="bottom" | '''[[#How to Configure Interface Query Keys Using Workbench|Using the Workbench]]<br>'''
! id="r1c3-t30" align="left" valign="bottom" | '''[[#How to Configure Interface Query Keys Using Java]]<br>'''
+
! id="r1c3-t30" align="left" valign="bottom" | '''[[#How to Configure Interface Query Keys Using Java|Using Java]]<br>'''
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r2c1-t30" headers="r1c1-t30" align="left" |
 
| id="r2c1-t30" headers="r1c1-t30" align="left" |
 
Relational Descriptors
 
Relational Descriptors
 
| headers="r2c1-t30 r1c2-t30" align="left" |
 
| headers="r2c1-t30 r1c2-t30" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
| headers="r2c1-t30 r1c3-t30" align="left" |
 
| headers="r2c1-t30 r1c3-t30" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r3c1-t30" headers="r1c1-t30" align="left" |
 
| id="r3c1-t30" headers="r1c1-t30" align="left" |
 
Object-Relational Data Type Descriptors
 
Object-Relational Data Type Descriptors
 
| headers="r3c1-t30 r1c2-t30" align="left" |
 
| headers="r3c1-t30 r1c2-t30" align="left" |
Unsupported<br>
+
[[Image:unsupport.gif|Unsupported]]<br>
 
| headers="r3c1-t30 r1c3-t30" align="left" |
 
| headers="r3c1-t30 r1c3-t30" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r4c1-t30" headers="r1c1-t30" align="left" |
 
| id="r4c1-t30" headers="r1c1-t30" align="left" |
 
EIS Descriptors
 
EIS Descriptors
 
| headers="r4c1-t30 r1c2-t30" align="left" |
 
| headers="r4c1-t30 r1c2-t30" align="left" |
Unsupported<br>
+
[[Image:unsupport.gif|Unsupported]]<br>
 
| headers="r4c1-t30 r1c3-t30" align="left" |
 
| headers="r4c1-t30 r1c3-t30" align="left" |
Unsupported<br>
+
[[Image:unsupport.gif|Unsupported]]<br>
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r5c1-t30" headers="r1c1-t30" align="left" |
 
| id="r5c1-t30" headers="r1c1-t30" align="left" |
 
XML Descriptors
 
XML Descriptors
 
| headers="r5c1-t30 r1c2-t30" align="left" |
 
| headers="r5c1-t30 r1c2-t30" align="left" |
Unsupported<br>
+
[[Image:unsupport.gif|Unsupported]]<br>
 
| headers="r5c1-t30 r1c3-t30" align="left" |
 
| headers="r5c1-t30 r1c3-t30" align="left" |
Unsupported<br>
+
[[Image:unsupport.gif|Unsupported]]<br>
 
|}
 
|}
  
Line 1,767: Line 1,713:
 
''''' Automatically Generated Query Keys for Phone and Email'''''
 
''''' Automatically Generated Query Keys for Phone and Email'''''
  
[[Image:atgenkey.gif|Automatically Generated Query Keys for Phone and Email "]<br><br>
+
[[Image:atgenkey.gif|Automatically Generated Query Keys for Phone and Email ]]<br><br>
  
 
Both classes have an attribute, id, that is directly mapped to fields that have different names. However, a query key is generated for this attribute. For the <tt>Contact</tt> interface descriptor, you must indicate that the <tt>id</tt> query key must be defined for each of the implementors.
 
Both classes have an attribute, id, that is directly mapped to fields that have different names. However, a query key is generated for this attribute. For the <tt>Contact</tt> interface descriptor, you must indicate that the <tt>id</tt> query key must be defined for each of the implementors.
Line 1,773: Line 1,719:
 
If either of the implementor classes did not have the <tt>id</tt> query key defined the Workbench would flag that descriptor as deficient.
 
If either of the implementor classes did not have the <tt>id</tt> query key defined the Workbench would flag that descriptor as deficient.
  
Now that a descriptor with a commonly shared query key has been defined for <tt>Contact</tt>, you can use it as the reference class for a variable one-to-one mapping (see [[Using%20Advanced%20Query%20API%20(ELUG)|Using Queries on Variable One-to-One Mappings]]).
+
Now that a descriptor with a commonly shared query key has been defined for <tt>Contact</tt>, you can use it as the reference class for a variable one-to-one mapping (see [[Using%20Advanced%20Query%20API%20(ELUG)#Using Queries on Variable One-to-One Mappings|Using Queries on Variable One-to-One Mappings]]).
  
 
For example, you can now create a variable one-to-one mapping for the <tt>contact</tt> attribute of <tt>Employee</tt>. When you edit the foreign key field information for the mapping, you must match the <tt>Employee</tt> descriptor's tables to query keys from the <tt>Contact</tt> interface descriptor.
 
For example, you can now create a variable one-to-one mapping for the <tt>contact</tt> attribute of <tt>Employee</tt>. When you edit the foreign key field information for the mapping, you must match the <tt>Employee</tt> descriptor's tables to query keys from the <tt>Contact</tt> interface descriptor.
Line 1,824: Line 1,770:
 
  phoneClassDescriptor.addDirectMapping("number", "P_NUM");
 
  phoneClassDescriptor.addDirectMapping("number", "P_NUM");
  
==Configuring Cache Type and Size at the Descriptor Level==
 
  
The EclipseLink cache is an in-memory repository that stores recently read or written objects based on class and primary key values. EclipseLink uses the cache to do the following:
 
  
 +
==Configuring Cache Type and Size at the Descriptor Level==
 +
The EclipseLink cache is an in-memory repository that stores recently read or written objects based on class and primary key values. EclipseLink uses the cache to do the following:
 
* improve performance by holding recently read or written objects and accessing them in-memory to minimize database access;
 
* improve performance by holding recently read or written objects and accessing them in-memory to minimize database access;
 
* manage locking and isolation level;
 
* manage locking and isolation level;
Line 1,836: Line 1,782:
  
 
<span id="Table 115-13"></span>
 
<span id="Table 115-13"></span>
''''' Descriptor Support for Identity Map'''''
 
  
 
{| class="RuleFormal" dir="ltr" title="Descriptor Support for Identity Map" summary="This table summarizes which descriptors support identity map." width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
 
{| class="RuleFormal" dir="ltr" title="Descriptor Support for Identity Map" summary="This table summarizes which descriptors support identity map." width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
! id="r1c1-t31" align="left" valign="bottom" | '''Descriptor'''
 
! id="r1c1-t31" align="left" valign="bottom" | '''Descriptor'''
! id="r1c2-t31" align="left" valign="bottom" | '''[[#How to Configure Cache Type and Size at the Descriptor Level Using Workbench]]<br>'''
+
! id="r1c2-t31" align="left" valign="bottom" | '''[[#How to Configure Cache Type and Size at the Descriptor Level Using Workbench|Using the Workbench]]<br>'''
! id="r1c3-t31" align="left" valign="bottom" | '''[[#How to Configure Cache Type and Size at the Descriptor Level Using Java]]<br>'''
+
! id="r1c3-t31" align="left" valign="bottom" | '''[[#How to Configure Cache Type and Size at the Descriptor Level Using Java|Using Java]]<br>'''
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r2c1-t31" headers="r1c1-t31" align="left" |
 
| id="r2c1-t31" headers="r1c1-t31" align="left" |
Relational Descriptors<sup>Foot 1 </sup>
+
Relational Descriptors<sup> 1 </sup>
 
| headers="r2c1-t31 r1c2-t31" align="left" |
 
| headers="r2c1-t31 r1c2-t31" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
| headers="r2c1-t31 r1c3-t31" align="left" |
 
| headers="r2c1-t31 r1c3-t31" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r3c1-t31" headers="r1c1-t31" align="left" |
 
| id="r3c1-t31" headers="r1c1-t31" align="left" |
 
Object-Relational Data Type Descriptors
 
Object-Relational Data Type Descriptors
 
| headers="r3c1-t31 r1c2-t31" align="left" |
 
| headers="r3c1-t31 r1c2-t31" align="left" |
Unsupported<br>
+
[[Image:unsupport.gif|Unsupported]]<br>
 
| headers="r3c1-t31 r1c3-t31" align="left" |
 
| headers="r3c1-t31 r1c3-t31" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r4c1-t31" headers="r1c1-t31" align="left" |
 
| id="r4c1-t31" headers="r1c1-t31" align="left" |
EIS Descriptors <sup>Foot 2 </sup>
+
EIS Descriptors <sup> 2 </sup>
 
| headers="r4c1-t31 r1c2-t31" align="left" |
 
| headers="r4c1-t31 r1c2-t31" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
| headers="r4c1-t31 r1c3-t31" align="left" |
 
| headers="r4c1-t31 r1c3-t31" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r5c1-t31" headers="r1c1-t31" align="left" |
 
| id="r5c1-t31" headers="r1c1-t31" align="left" |
 
XML Descriptors
 
XML Descriptors
 
| headers="r5c1-t31 r1c2-t31" align="left" |
 
| headers="r5c1-t31 r1c2-t31" align="left" |
Unsupported<br>
+
[[Image:unsupport.gif|Unsupported]]<br>
 
| headers="r5c1-t31 r1c3-t31" align="left" |
 
| headers="r5c1-t31 r1c3-t31" align="left" |
Unsupported<br>
+
[[Image:unsupport.gif|Unsupported]]<br>
 
|}
 
|}
  
<br><sup>Footnote 1 </sup>Relational class descriptors only (see [[Creating%20a%20Relational%20Descriptor%20(ELUG)|Creating Relational Class Descriptors]]).<br><sup>Footnote 2 </sup>EIS root descriptors only (see [[Creating%20an%20EIS%20Descriptor%20(ELUG)|EIS Root Descriptors].<br>
+
<br><sup> 1 </sup>[[Creating%20a%20Relational%20Descriptor%20(ELUG)#Creating Relational Class Descriptors|Relational Class Descriptors]] only.<br><sup> 2 </sup>[[Creating%20an%20EIS%20Descriptor%20(ELUG)#EIS Root Descriptors|EIS Root Descriptors]] only.<br>
  
This configuration overrides the default identity map configuration defined at the project level (see [[Configuring%20a%20Project%20(ELUG)|Configuring Cache Type and Size at the Project Level]]).
+
This configuration overrides the default identity map configuration [[Configuring%20a%20Project%20(ELUG)#Configuring Cache Type and Size at the Project Level|defined at the project level]].
  
For detailed information on caching and object identity, and the recommended settings to maximize EclipseLink performance, see to [[Introduction%20to%20Cache%20(ELUG)|Cache Type and Object Identity]].
+
For detailed information on caching and object identity, and the recommended settings to maximize EclipseLink performance, see to [[Introduction%20to%20Cache%20(ELUG)#Cache Type and Object Identity|Cache Type and Object Identity]].
  
For more information about the cache, see [[Introduction%20to%20Cache%20(ELUG)|Introduction to Cache]].
+
For more information, see [[Introduction%20to%20Cache%20(ELUG)|Introduction to Cache]].
  
  
Line 1,888: Line 1,833:
  
 
# Select the descriptor in the '''Navigator'''.
 
# Select the descriptor in the '''Navigator'''.
# Select the '''Caching''' tab in the '''Editor'''. The Caching tab appears.<br>'''''Figure 115-25 Caching Tab, Identity Map Options'''''<br>[[Image:desiden.gif|Caching Tab, Identity Map Options]]<br><br>
+
# Select the '''Caching''' tab in the '''Editor'''. The Caching tab appears.<br>'''''Caching Tab, Identity Map Options'''''<br>[[Image:desiden.gif|Caching Tab, Identity Map Options]]<br><br>
 
# Complete the fields on the'''Caching''' tab to specify the default identity map for the selected descriptor.
 
# Complete the fields on the'''Caching''' tab to specify the default identity map for the selected descriptor.
  
Line 1,902: Line 1,847:
 
| headers="r2c1-t32 r1c2-t32" align="left" |
 
| headers="r2c1-t32 r1c2-t32" align="left" |
 
Use the '''Type''' list to choose the identity map as follows:
 
Use the '''Type''' list to choose the identity map as follows:
* '''Weak with Soft Subcache''' (<tt>SoftCacheWeakIdentityMap</tt>)–cache first ''n'' elements in soft space, anything after that in weak space (see [[Introduction%20to%20Cache%20(ELUG)|Soft Cache Weak Identity Map and Hard Cache Weak Identity Map]])
+
* '''Weak with Soft Subcache''' (<tt>SoftCacheWeakIdentityMap</tt>) – cache first ''n'' elements in soft space, anything after that in weak space (see [[Introduction%20to%20Cache%20(ELUG)#Soft Cache Weak Identity Map and Hard Cache Weak Identity Map|Soft Cache Weak Identity Map and Hard Cache Weak Identity Map]])
* '''Weak with Hard Subcache''' (<tt>HardCacheWeakIdentityMap</tt>)–cache first ''n'' elements in hard space, anything after that in weak space (see [[Introduction%20to%20Cache%20(ELUG)|Soft Cache Weak Identity Map and Hard Cache Weak Identity Map]])
+
* '''Weak with Hard Subcache''' (<tt>HardCacheWeakIdentityMap</tt>) – cache first ''n'' elements in hard space, anything after that in weak space (see [[Introduction%20to%20Cache%20(ELUG)#Soft Cache Weak Identity Map and Hard Cache Weak Identity Map|Soft Cache Weak Identity Map and Hard Cache Weak Identity Map]])
* '''Weak''' (<tt>WeakIdentityMap</tt>)–cache everything in weak space (see [[Introduction%20to%20Cache%20(ELUG)|Weak Identity Map]])
+
* '''Weak''' ([[Introduction%20to%20Cache%20(ELUG)#Weak Identity Map|<tt>WeakIdentityMap</tt>]]) – cache everything in weak space
* '''Soft''' (<tt>SoftIdentityMap</tt>)–cache everything in soft space(see [[Introduction%20to%20Cache%20(ELUG)|Soft Identity Map]])
+
* '''Soft''' ([[Introduction%20to%20Cache%20(ELUG)#Soft Identity Map|<tt>SoftIdentityMap</tt>]]) – cache everything in soft space
* '''Full''' (<tt>FullIdentityMap</tt>)–cache everything permanently (see [[Introduction%20to%20Cache%20(ELUG)|Full Identity Map]])
+
* '''Full''' ([[Introduction%20to%20Cache%20(ELUG)#Full Identity Map|<tt>FullIdentityMap</tt>]]) – cache everything permanently
* '''None''' (<tt>NoIdentityMap</tt>)–cache nothing (see [[Introduction%20to%20Cache%20(ELUG)|No Identity Map]]).
+
* '''None''' ([[Introduction%20to%20Cache%20(ELUG)#No Identity Map|<tt>NoIdentityMap</tt>]]) – cache nothing.
For more information, see [[Introduction%20to%20Cache%20(ELUG)|Cache Type and Object Identity]].
+
 
 +
For more information, see [[Introduction%20to%20Cache%20(ELUG)#Cache Type and Object Identity|Cache Type and Object Identity]].
  
 
Changing the project's default identity map does not affect descriptors that already exist in the project.
 
Changing the project's default identity map does not affect descriptors that already exist in the project.
Line 1,923: Line 1,869:
 
|}
 
|}
  
<br><sup>Footnote 1 </sup>If a descriptor is a child in an inheritance hierarchy, EclipseLink makes this field read only and displays the options from the parent root descriptor.<br>
+
<br><sup> 1 </sup>If a descriptor is a child in an inheritance hierarchy, EclipseLink makes this field read only and displays the options from the parent root descriptor.<br>
  
===How to Configure Cache Type and Size at the Descriptor Level Using Java===
 
  
 +
===How to Configure Cache Type and Size at the Descriptor Level Using Java===
 
Use one of the following <tt>ClassDescriptor</tt> methods to configure the descriptor to use the appropriate type of identity map:
 
Use one of the following <tt>ClassDescriptor</tt> methods to configure the descriptor to use the appropriate type of identity map:
 
 
* <tt>useFullIdentitMap</tt>
 
* <tt>useFullIdentitMap</tt>
 
* <tt>useWeakIdentityMap</tt>
 
* <tt>useWeakIdentityMap</tt>
Line 1,938: Line 1,883:
 
Use the <tt>ClassDescriptor</tt> method <tt>setIdentityMapSize</tt> to configure the size of the identity map.
 
Use the <tt>ClassDescriptor</tt> method <tt>setIdentityMapSize</tt> to configure the size of the identity map.
  
==Configuring Cache Isolation at the Descriptor Level==
 
  
If you plan to use isolated sessions (see [[Introduction%20to%20Cache%20(ELUG)|Cache Isolation]]), you must configure descriptors as isolated for any object that you want confined to an isolated session cache.
+
==Configuring Cache Isolation at the Descriptor Level==
 +
If you plan to use [[Introduction%20to%20Cache%20(ELUG)#Cache Isolation|isolated sessions]], you must configure descriptors as isolated for any object that you want confined to an isolated session cache.
  
 
Configuring a descriptor to be isolated means that EclipseLink will not store the object in the shared session cache and the object will not be shared across client sessions. Each client will have their own object read directly from the database. Objects in an isolated client session cache can reference objects in their parent server session's shared session cache, but no objects in the shared session cache can reference objects in an isolated client session cache. Isolation is required when using Oracle Database Virtual Private Database (VPD) support or database user-based read security. Isolation can also be used if caching is not desired across client sessions.
 
Configuring a descriptor to be isolated means that EclipseLink will not store the object in the shared session cache and the object will not be shared across client sessions. Each client will have their own object read directly from the database. Objects in an isolated client session cache can reference objects in their parent server session's shared session cache, but no objects in the shared session cache can reference objects in an isolated client session cache. Isolation is required when using Oracle Database Virtual Private Database (VPD) support or database user-based read security. Isolation can also be used if caching is not desired across client sessions.
Line 1,948: Line 1,893:
  
 
<span id="Table 115-14"></span>
 
<span id="Table 115-14"></span>
''''' Descriptor Support for Cache Isolation Map'''''
 
  
 
{| class="RuleFormal" dir="ltr" title="Descriptor Support for Cache Isolation Map" summary="This table summarizes which descriptors support cache isolation map" width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
 
{| class="RuleFormal" dir="ltr" title="Descriptor Support for Cache Isolation Map" summary="This table summarizes which descriptors support cache isolation map" width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
! id="r1c1-t33" align="left" valign="bottom" | '''Descriptor'''
 
! id="r1c1-t33" align="left" valign="bottom" | '''Descriptor'''
! id="r1c2-t33" align="left" valign="bottom" | '''[[#How to Configure Cache Isolation at the Descriptor Level Using Workbench]]<br>'''
+
! id="r1c2-t33" align="left" valign="bottom" | '''[[#How to Configure Cache Isolation at the Descriptor Level Using Workbench|Using the Workbench]]<br>'''
! id="r1c3-t33" align="left" valign="bottom" | '''[[#How to Configure Cache Isolation at the Descriptor Level Using Java]]<br>'''
+
! id="r1c3-t33" align="left" valign="bottom" | '''[[#How to Configure Cache Isolation at the Descriptor Level Using Java|Using Java]]<br>'''
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r2c1-t33" headers="r1c1-t33" align="left" |
 
| id="r2c1-t33" headers="r1c1-t33" align="left" |
Relational Descriptors <sup>Foot 1 </sup>
+
Relational Descriptors <sup> 1 </sup>
 
| headers="r2c1-t33 r1c2-t33" align="left" |
 
| headers="r2c1-t33 r1c2-t33" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
| headers="r2c1-t33 r1c3-t33" align="left" |
 
| headers="r2c1-t33 r1c3-t33" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r3c1-t33" headers="r1c1-t33" align="left" |
 
| id="r3c1-t33" headers="r1c1-t33" align="left" |
 
Object-Relational Data Type Descriptors
 
Object-Relational Data Type Descriptors
 
| headers="r3c1-t33 r1c2-t33" align="left" |
 
| headers="r3c1-t33 r1c2-t33" align="left" |
Unsupported<br>
+
[[Image:unsupport.gif|Unsupported]]<br>
 
| headers="r3c1-t33 r1c3-t33" align="left" |
 
| headers="r3c1-t33 r1c3-t33" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r4c1-t33" headers="r1c1-t33" align="left" |
 
| id="r4c1-t33" headers="r1c1-t33" align="left" |
EIS Descriptors <sup>Foot 2 </sup>
+
EIS Descriptors <sup> 2 </sup>
 
| headers="r4c1-t33 r1c2-t33" align="left" |
 
| headers="r4c1-t33 r1c2-t33" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
| headers="r4c1-t33 r1c3-t33" align="left" |
 
| headers="r4c1-t33 r1c3-t33" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r5c1-t33" headers="r1c1-t33" align="left" |
 
| id="r5c1-t33" headers="r1c1-t33" align="left" |
 
XML Descriptors
 
XML Descriptors
 
| headers="r5c1-t33 r1c2-t33" align="left" |
 
| headers="r5c1-t33 r1c2-t33" align="left" |
Unsupported<br>
+
[[Image:unsupport.gif|Unsupported]]<br>
 
| headers="r5c1-t33 r1c3-t33" align="left" |
 
| headers="r5c1-t33 r1c3-t33" align="left" |
Unsupported<br>
+
[[Image:unsupport.gif|Unsupported]]<br>
 
|}
 
|}
  
<br><sup>Footnote 1 </sup>Relational class descriptors only (see [[Creating%20a%20Relational%20Descriptor%20(ELUG)|Creating Relational Class Descriptors]).<br><sup>Footnote 2 </sup>EIS root descriptors only (see [[Creating%20an%20EIS%20Descriptor%20(ELUG)|EIS Root Descriptors]]).<br>
+
<br><sup> 1 </sup>[[Creating%20a%20Relational%20Descriptor%20(ELUG)#Creating Relational Class Descriptors|Relational Class Descriptors]] only.<br><sup> 2 </sup>[[Creating%20an%20EIS%20Descriptor%20(ELUG)#EIS Root Descriptors|EIS Root Descriptors]] only.<br>
  
This configuration overrides the default cache isolation configuration defined at the project level (see [[Configuring%20a%20Project%20(ELUG)|Configuring Cache Isolation at the Project Level]]).
+
This configuration overrides the default cache isolation configuration [[Configuring%20a%20Project%20(ELUG)#Configuring Cache Isolation at the Project Level|defined at the project level]].
  
 
<br>
 
<br>
Line 1,993: Line 1,937:
 
{| 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:''' If you configure a descriptor as isolated, it cannot participate in a coordinated cache (see [[#Configuring Cache Coordination Change Propagation at the Descriptor Level]]).
+
'''Note:''' If you configure a descriptor as isolated, it cannot participate in a coordinated cache (see [[#Configuring Cache Coordination Change Propagation at the Descriptor Level|Configuring Cache Coordination Change Propagation at the Descriptor Level]]).
 
|}
 
|}
  
<br>
+
 
  
 
===How to Configure Cache Isolation at the Descriptor Level Using Workbench===
 
===How to Configure Cache Isolation at the Descriptor Level Using Workbench===
 
 
To specify the cache isolation options, use this procedure:
 
To specify the cache isolation options, use this procedure:
 
 
# Select the descriptor in the '''Navigator'''.
 
# Select the descriptor in the '''Navigator'''.
# Select the '''Caching''' tab in the '''Editor'''. The Caching tab appears.<br>'''''Figure 115-26 Caching Tab, Isolation Options'''''[[Image:desisol.gif|Caching Tab, Isolation Options]]<br><br>
+
# Select the '''Caching''' tab in the '''Editor'''. The Caching tab appears.<br>'''''Caching Tab, Isolation Options'''''<br>[[Image:desisol.gif|Caching Tab, Isolation Options]]<br><br>
# Complete the [topicid:descriptor.cacheIsolation '''Isolation''' options] on the '''Caching''' tab.
+
# Complete the '''Isolation''' options on the '''Caching''' tab.
  
 
Use the '''Isolation''' list to choose one of the following:
 
Use the '''Isolation''' list to choose one of the following:
 
+
* '''Isolated''' – if you want all objects confined to an isolated client session cache. For more information, see [[Introduction%20to%20Cache%20(ELUG)#Cache Isolation|Cache Isolation]].
* '''Isolated'''–if you want all objects confined to an isolated client session cache. For more information, see [[Introduction%20to%20Cache%20(ELUG)|Cache Isolation]].
+
* '''Shared''' – if you want all objects visible in the shared session cache (default).
* '''Shared'''–if you want all objects visible in the shared session cache (default).
+
  
  
  
 
===How to Configure Cache Isolation at the Descriptor Level Using Java===
 
===How to Configure Cache Isolation at the Descriptor Level Using Java===
 +
To specify that a class is isolated, Use a [[#Configuring Amendment Methods|descriptor amendment method]] to call <tt>ClassDescriptor</tt> method <tt>setIsIsolated</tt>, passing in a <tt>boolean</tt> of <tt>true</tt>.
  
To specify that a class is isolated, use a descriptor amendment method (see [[#Configuring Amendment Methods]]) to call <tt>ClassDescriptor</tt> method <tt>setIsIsolated</tt>, passing in a <tt>boolean</tt> of <tt>true</tt>.
 
  
==Configuring Unit of Work Cache Isolation at the Descriptor Level==
 
  
 +
==Configuring Unit of Work Cache Isolation at the Descriptor Level==
 
Use this policy to determine how a unit of work uses a session cache for a specific class. This table lists the unit of work cache isolation options.
 
Use this policy to determine how a unit of work uses a session cache for a specific class. This table lists the unit of work cache isolation options.
  
  
 
<span id="Table 115-15"></span>
 
<span id="Table 115-15"></span>
''''' Unit of Work Cache Isolation Options'''''
 
 
 
{| class="HRuleFormal" dir="ltr" title="Unit of Work Cache Isolation Options" summary="This table lists the unit of work cache isolation options." width="100%" border="1" frame="hsides" rules="rows" cellpadding="3" frame="hsides" rules="rows"
 
{| class="HRuleFormal" dir="ltr" title="Unit of Work Cache Isolation Options" summary="This table lists the unit of work cache isolation options." width="100%" border="1" frame="hsides" rules="rows" cellpadding="3" frame="hsides" rules="rows"
 
|- align="left" valign="top"
 
|- align="left" valign="top"
Line 2,033: Line 1,972:
 
Using the Session Cache After the Transaction
 
Using the Session Cache After the Transaction
 
| headers="r2c1-t35 r1c2-t35" align="left" |
 
| headers="r2c1-t35 r1c2-t35" align="left" |
<tt>USE_SESSION_CACHE_AFTER_TRANSACTION</tt>Objects built from new data accessed after a unit of work early transaction are stored in the session cache.This options is the most efficient as it allows the cache to be used after an early transaction.
+
<tt>USE_SESSION_CACHE_AFTER_TRANSACTION</tt>
 +
 
 +
Objects built from new data accessed after a unit of work early transaction are stored in the session cache.This options is the most efficient as it allows the cache to be used after an early transaction.
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r3c1-t35" headers="r1c1-t35" align="left" |
 
| id="r3c1-t35" headers="r1c1-t35" align="left" |
 
Isolating New Data After the Transaction
 
Isolating New Data After the Transaction
 
| headers="r3c1-t35 r1c2-t35" align="left" |
 
| headers="r3c1-t35 r1c2-t35" align="left" |
<tt>ISOLATE_NEW_DATA_AFTER_TRANSACTION</tt> (default) Objects built from new data accessed after a unit of work early transaction are only stored in the unit of work.
+
<tt>ISOLATE_NEW_DATA_AFTER_TRANSACTION</tt> (default)  
 +
 
 +
Objects built from new data accessed after a unit of work early transaction are only stored in the unit of work.
  
 
This still allows previously cached objects to be accessed in the unit of work after an early transaction, while ensuring that uncommitted data will never be put in the session cache by storing any object built from new data only in the unit of work
 
This still allows previously cached objects to be accessed in the unit of work after an early transaction, while ensuring that uncommitted data will never be put in the session cache by storing any object built from new data only in the unit of work
Line 2,047: Line 1,990:
 
<tt>ISOLATE_CACHE_AFTER_TRANSACTION</tt>After a unit of work early transaction the session cache is no longer used for this class. Objects are directly built from the database data and only stored in the unit of work, ''even if previously cached''.
 
<tt>ISOLATE_CACHE_AFTER_TRANSACTION</tt>After a unit of work early transaction the session cache is no longer used for this class. Objects are directly built from the database data and only stored in the unit of work, ''even if previously cached''.
  
Note: This option may affect performance because you are bypassing the session cache after an early transaction.
+
'''Note''': This option may affect performance because you are bypassing the session cache after an early transaction.
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r5c1-t35" headers="r1c1-t35" align="left" |
 
| id="r5c1-t35" headers="r1c1-t35" align="left" |
 
Always Isolating the Cache
 
Always Isolating the Cache
 
| headers="r5c1-t35 r1c2-t35" align="left" |
 
| headers="r5c1-t35 r1c2-t35" align="left" |
<tt>ISOLATE_CACHE_ALWAYS</tt>The session cache will ''never'' be used for the class. Objects are directly built from the database data and only stored in the unit of work. New objects and changes will never be merged into the session cache.
+
<tt>ISOLATE_CACHE_ALWAYS</tt>
  
Note: This option my affect performance because you are bypassing the session cache. However if this class is isolated or pessimistic locked and always accessed in a transaction, this can avoid having to build two copies of the object.
+
The session cache will ''never'' be used for the class. Objects are directly built from the database data and only stored in the unit of work. New objects and changes will never be merged into the session cache.
 +
 
 +
'''Note''': This option my affect performance because you are bypassing the session cache. However if this class is isolated or pessimistic locked and always accessed in a transaction, this can avoid having to build two copies of the object.
 
|}
 
|}
  
Line 2,060: Line 2,005:
  
 
Most of these options apply only to a unit of work in an early transaction, such as the following:
 
Most of these options apply only to a unit of work in an early transaction, such as the following:
 
 
* A unit of work that was flushed (<tt>write changes</tt>).
 
* A unit of work that was flushed (<tt>write changes</tt>).
 
* Issued a modify query.
 
* Issued a modify query.
Line 2,068: Line 2,012:
  
 
===How to Configure Unit of Work Cache Isolation at the Descriptor Level Using Java===
 
===How to Configure Unit of Work Cache Isolation at the Descriptor Level Using Java===
 +
To specify that a class is isolated, use a [[#Configuring Amendment Methods|descriptor amendment method]] to call <tt>ClassDescriptor</tt> method <tt>setUnitOfWorkCacheIsolationLevel</tt><nowiki>.</nowiki>
  
To specify that a class is isolated, use a descriptor amendment method (see [[#Configuring Amendment Methods]]) to call <tt>ClassDescriptor</tt> method <tt>setUnitOfWorkCacheIsolationLevel</tt><nowiki>.</nowiki>
 
  
==Configuring Cache Coordination Change Propagation at the Descriptor Level==
 
  
If you plan to use a coordinated cache (see [[Introduction%20to%20Cache%20(ELUG)|Cache Coordination]]), you can configure how, and under what conditions, a coordinated cache propagates changes for a given descriptor.
+
==Configuring Cache Coordination Change Propagation at the Descriptor Level==
 +
If you plan to use a [[Introduction%20to%20Cache%20(ELUG)#Cache Coordination|coordinated cache]], you can configure how, and under what conditions, a coordinated cache propagates changes for a given descriptor.
  
 
This table summarizes which descriptors support cache isolation configuration.
 
This table summarizes which descriptors support cache isolation configuration.
Line 2,079: Line 2,023:
  
 
<span id="Table 115-16"></span>
 
<span id="Table 115-16"></span>
''''' Descriptor Support for Cache Coordination Change Propagation Configuration'''''
 
 
 
{| class="RuleFormal" dir="ltr" title="Descriptor Support for Cache Coordination Change Propagation Configuration" summary="This table summarizes which descriptors support Cache Coordination Change Propagation Configuration" width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
 
{| class="RuleFormal" dir="ltr" title="Descriptor Support for Cache Coordination Change Propagation Configuration" summary="This table summarizes which descriptors support Cache Coordination Change Propagation Configuration" width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
! id="r1c1-t36" align="left" valign="bottom" | '''Descriptor'''
 
! id="r1c1-t36" align="left" valign="bottom" | '''Descriptor'''
! id="r1c2-t36" align="left" valign="bottom" | '''[[#How to Configure Cache Coordination Change Propagation at the Descriptor Level Using Workbench]]<br>'''
+
! id="r1c2-t36" align="left" valign="bottom" | '''[[#How to Configure Cache Coordination Change Propagation at the Descriptor Level Using Workbench|Using the Workbench]]<br>'''
! id="r1c3-t36" align="left" valign="bottom" | '''[[#How to Configure Cache Coordination Change Propagation at the Descriptor Level Using Java]]<br>'''
+
! id="r1c3-t36" align="left" valign="bottom" | '''[[#How to Configure Cache Coordination Change Propagation at the Descriptor Level Using Java|Using Java]]<br>'''
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r2c1-t36" headers="r1c1-t36" align="left" |
 
| id="r2c1-t36" headers="r1c1-t36" align="left" |
Relational Descriptors <sup>Foot 1 </sup>
+
Relational Descriptors <sup> 1 </sup>
 
| headers="r2c1-t36 r1c2-t36" align="left" |
 
| headers="r2c1-t36 r1c2-t36" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
| headers="r2c1-t36 r1c3-t36" align="left" |
 
| headers="r2c1-t36 r1c3-t36" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r3c1-t36" headers="r1c1-t36" align="left" |
 
| id="r3c1-t36" headers="r1c1-t36" align="left" |
 
Object-Relational Data Type Descriptors
 
Object-Relational Data Type Descriptors
 
| headers="r3c1-t36 r1c2-t36" align="left" |
 
| headers="r3c1-t36 r1c2-t36" align="left" |
Unsupported<br>
+
[[Image:unsupport.gif|Unsupported]]<br>
 
| headers="r3c1-t36 r1c3-t36" align="left" |
 
| headers="r3c1-t36 r1c3-t36" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r4c1-t36" headers="r1c1-t36" align="left" |
 
| id="r4c1-t36" headers="r1c1-t36" align="left" |
EIS Descriptors <sup>Foot 2 </sup>
+
EIS Descriptors <sup> 2 </sup>
 
| headers="r4c1-t36 r1c2-t36" align="left" |
 
| headers="r4c1-t36 r1c2-t36" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
| headers="r4c1-t36 r1c3-t36" align="left" |
 
| headers="r4c1-t36 r1c3-t36" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r5c1-t36" headers="r1c1-t36" align="left" |
 
| id="r5c1-t36" headers="r1c1-t36" align="left" |
 
XML Descriptors
 
XML Descriptors
 
| headers="r5c1-t36 r1c2-t36" align="left" |
 
| headers="r5c1-t36 r1c2-t36" align="left" |
Unsupported<br>
+
[[Image:unsupport.gif|Unsupported]]<br>
 
| headers="r5c1-t36 r1c3-t36" align="left" |
 
| headers="r5c1-t36 r1c3-t36" align="left" |
Unsupported<br>
+
[[Image:unsupport.gif|Unsupported]]<br>
 
|}
 
|}
  
<br><sup>Footnote 1 </sup>Relational class descriptors only (see [[Creating%20a%20Relational%20Descriptor%20(ELUG)|Creating Relational Class Descriptors]]).<br><sup>Footnote 2 </sup>EIS root descriptors only (see [[Creating%20an%20EIS%20Descriptor%20(ELUG)|EIS Root Descriptors]]).<br>
+
<br><sup> 1 </sup>[[Creating%20a%20Relational%20Descriptor%20(ELUG)#Creating Relational Class Descriptors|Relational Class Descriptors]] only.<br><sup> 2 </sup>[[Creating%20an%20EIS%20Descriptor%20(ELUG)#EIS Root Descriptors|EIS Root Descriptors]] only.<br>
  
This configuration overrides the default cache coordination change propagation configuration defined at the project level (see [[Configuring%20a%20Project%20(ELUG)|Configuring Cache Coordination Change Propagation at the Project Level]]).
+
This configuration overrides the default cache coordination change propagation configuration defined at the project level (see [[Configuring%20a%20Project%20(ELUG)#Configuring Cache Coordination Change Propagation at the Project Level|Configuring Cache Coordination Change Propagation at the Project Level]]).
  
To complete your coordinated cache configuration, see [[Configuring%20a%20Coordinated%20Cache%20(ELUG)|Configuring a Coordinated Cache]].
+
To complete your coordinated cache configuration, see [[Configuring%20a%20Coordinated%20Cache%20(ELUG)#Configuring a Coordinated Cache|Configuring a Coordinated Cache]].
  
 
<br>
 
<br>
Line 2,126: Line 2,068:
 
{| 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:''' If you configure a descriptor as isolated (see [[#Configuring Cache Isolation at the Descriptor Level]]), it cannot participate in a coordinated cache.
+
'''Note:''' If you configure a descriptor as isolated (see [[#Configuring Cache Isolation at the Descriptor Level|Configuring Cache Isolation at the Descriptor Level]]), it cannot participate in a coordinated cache.
 
|}
 
|}
  
<br>
 
  
===How to Configure Cache Coordination Change Propagation at the Descriptor Level Using Workbench===
 
  
To specify the coordinated cache change propagation options, use this procedure:
 
  
 +
===How to Configure Cache Coordination Change Propagation at the Descriptor Level Using Workbench===
 +
To specify the coordinated cache change propagation options, use this procedure:
 
# Select the descriptor in the '''Navigator'''.
 
# Select the descriptor in the '''Navigator'''.
# Select the '''Caching''' tab in the '''Editor'''. The Caching tab appears.<br>'''''Figure 115-27 Caching Tab, Coordination Options'''''[[Image:descord.gif|Caching Tab, Coordination Options]]<br><br>
+
# Select the '''Caching''' tab in the '''Editor'''. The Caching tab appears.<br><span id="Figure 115-27"></span>''''' Caching Tab, Coordination Options'''''<br>[[Image:descord.gif|Caching Tab, Coordination Options]]<br><br>
# Complete the [topicid:descriptor.cacheCoord '''Coordination''' options] on the '''Caching''' tab.
+
# Complete the '''Coordination''' options on the '''Caching''' tab.
  
 
Use the following information to enter data in the '''Coordination''' field:
 
Use the following information to enter data in the '''Coordination''' field:
 
  
  
Line 2,174: Line 2,114:
  
 
'''See Also'''
 
'''See Also'''
: [[#Configuring Cache Coordination Change Propagation at the Descriptor Level]]
+
: [[#Configuring Cache Coordination Change Propagation at the Descriptor Level|Configuring Cache Coordination Change Propagation at the Descriptor Level]]
: [[Configuring%20a%20Project%20(ELUG)|Configuring Cache Coordination Change Propagation at the Project Level]]
+
: [[Configuring%20a%20Project%20(ELUG)#Configuring Cache Coordination Change Propagation at the Project Level|Configuring Cache Coordination Change Propagation at the Project Level]]
 
: [[Introduction%20to%20Cache%20(ELUG)|Introduction to Cache]]
 
: [[Introduction%20to%20Cache%20(ELUG)|Introduction to Cache]]
  
Line 2,181: Line 2,121:
  
 
===How to Configure Cache Coordination Change Propagation at the Descriptor Level Using Java===
 
===How to Configure Cache Coordination Change Propagation at the Descriptor Level Using Java===
 
+
Use a [[#Configuring Amendment Methods|descriptor amendment method]] to invoke <tt>ClassDescriptor</tt> method <tt>setCacheSynchronizationType</tt> passing in one of the following parameters:
Use a descriptor amendment method (see [[#Configuring Amendment Methods]]) to invoke <tt>ClassDescriptor</tt> method <tt>setCacheSynchronizationType</tt> passing in one of the following parameters:
+
 
+
 
* <tt>ClassDescriptor.DO_NOT_SEND_CHANGES</tt>
 
* <tt>ClassDescriptor.DO_NOT_SEND_CHANGES</tt>
 
* <tt>ClassDescriptor.SEND_OBJECT_CHANGES</tt>
 
* <tt>ClassDescriptor.SEND_OBJECT_CHANGES</tt>
Line 2,189: Line 2,127:
 
* <tt>ClassDescriptor.INVALIDATE_CHANGED_OBJECTS</tt>
 
* <tt>ClassDescriptor.INVALIDATE_CHANGED_OBJECTS</tt>
  
==Configuring Cache Expiration at the Descriptor Level==
 
  
By default, objects remain in the cache until they are explicitly deleted (see [[Using%20Basic%20Unit%20of%20Work%20API%20(ELUG)|Deleting Objects]]) or garbage-collected when using a weak identity map (see [[Configuring%20a%20Project%20(ELUG)|Configuring Cache Isolation at the Project Level]]). Alternatively, you can configure an object with a <tt>CacheInvalidationPolicy</tt> that allows you to specify, either automatically or manually, that an object is invalid: when any query attempts to read an invalid object, EclipseLink will go to the data source for the most up-to-date version of that object and update the cache with this information.
 
  
Using cache invalidation ensures that your application does not use stale data. It provides a better performing alternative to always refreshing (see [[#Configuring Cache Refreshing]]).
+
 
 +
==Configuring Cache Expiration at the Descriptor Level==
 +
By default, objects remain in the cache until they are explicitly deleted (see [[Using%20Basic%20Unit%20of%20Work%20API%20(ELUG)#Deleting Objects|Deleting Objects]]) or garbage-collected when using a weak identity map (see [[Configuring%20a%20Project%20(ELUG)#Configuring Cache Isolation at the Project Level|Configuring Cache Isolation at the Project Level]]). Alternatively, you can configure an object with a <tt>CacheInvalidationPolicy</tt> that allows you to specify, either automatically or manually, that an object is invalid: when any query attempts to read an invalid object, EclipseLink will go to the data source for the most up-to-date version of that object and update the cache with this information.
 +
 
 +
Using cache invalidation ensures that your application does not use stale data. It provides a better performing alternative to always refreshing (see [[#Configuring Cache Refreshing|Configuring Cache Refreshing]]).
  
 
This table summarizes which descriptors support a cache invalidation policy.
 
This table summarizes which descriptors support a cache invalidation policy.
Line 2,199: Line 2,139:
  
 
<span id="Table 115-17"></span>
 
<span id="Table 115-17"></span>
''''' Descriptor Support for Cache Invalidation Policy'''''
 
 
 
{| class="RuleFormal" dir="ltr" title="Descriptor Support for Cache Invalidation Policy" summary="This table summarizes which descriptors support a cache invalidation policy." width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
 
{| class="RuleFormal" dir="ltr" title="Descriptor Support for Cache Invalidation Policy" summary="This table summarizes which descriptors support a cache invalidation policy." width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
! id="r1c1-t39" align="left" valign="bottom" | '''Descriptor'''
 
! id="r1c1-t39" align="left" valign="bottom" | '''Descriptor'''
! id="r1c2-t39" align="left" valign="bottom" | '''[[#How to Configure Cache Expiration at the Descriptor Level Using Workbench]]<br>'''
+
! id="r1c2-t39" align="left" valign="bottom" | '''[[#How to Configure Cache Expiration at the Descriptor Level Using Workbench|Using the Workbench]]<br>'''
! id="r1c3-t39" align="left" valign="bottom" | '''[[#How to Configure Cache Expiration at the Descriptor Level Using Java]]<br>'''
+
! id="r1c3-t39" align="left" valign="bottom" | '''[[#How to Configure Cache Expiration at the Descriptor Level Using Java|Using Java]]<br>'''
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r2c1-t39" headers="r1c1-t39" align="left" |
 
| id="r2c1-t39" headers="r1c1-t39" align="left" |
Relational Descriptors[#sthref4545 <sup>Foot 1 </sup>]
+
Relational Descriptors <sup> 1 </sup>  
 
| headers="r2c1-t39 r1c2-t39" align="left" |
 
| headers="r2c1-t39 r1c2-t39" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
| headers="r2c1-t39 r1c3-t39" align="left" |
 
| headers="r2c1-t39 r1c3-t39" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r3c1-t39" headers="r1c1-t39" align="left" |
 
| id="r3c1-t39" headers="r1c1-t39" align="left" |
 
Object-Relational Data Type Descriptors
 
Object-Relational Data Type Descriptors
 
| headers="r3c1-t39 r1c2-t39" align="left" |
 
| headers="r3c1-t39 r1c2-t39" align="left" |
Unsupported<br>
+
[[Image:unsupport.gif|Unsupported]]<br>
 
| headers="r3c1-t39 r1c3-t39" align="left" |
 
| headers="r3c1-t39 r1c3-t39" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r4c1-t39" headers="r1c1-t39" align="left" |
 
| id="r4c1-t39" headers="r1c1-t39" align="left" |
EIS Descriptors[#sthref4546 <sup>Foot 2 </sup>]
+
EIS Descriptors <sup> 2 </sup>  
 
| headers="r4c1-t39 r1c2-t39" align="left" |
 
| headers="r4c1-t39 r1c2-t39" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
| headers="r4c1-t39 r1c3-t39" align="left" |
 
| headers="r4c1-t39 r1c3-t39" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r5c1-t39" headers="r1c1-t39" align="left" |
 
| id="r5c1-t39" headers="r1c1-t39" align="left" |
 
XML Descriptors
 
XML Descriptors
 
| headers="r5c1-t39 r1c2-t39" align="left" |
 
| headers="r5c1-t39 r1c2-t39" align="left" |
Unsupported<br>
+
[[Image:unsupport.gif|Unsupported]]<br>
 
| headers="r5c1-t39 r1c3-t39" align="left" |
 
| headers="r5c1-t39 r1c3-t39" align="left" |
Unsupported<br>
+
[[Image:unsupport.gif|Unsupported]]<br>
 
|}
 
|}
  
<br><sup>Footnote 1 </sup>Relational class descriptors only (see [[Creating%20a%20Relational%20Descriptor%20(ELUG)|Creating Relational Class Descriptors]]).<br><sup>Footnote 2 </sup>EIS root descriptors only (see [[Creating%20an%20EIS%20Descriptor%20(ELUG)|EIS Root Descriptors]]).<br>
+
<br><sup> 1 </sup>[[Creating%20a%20Relational%20Descriptor%20(ELUG)#Creating Relational Class Descriptors|Relational Class Descriptors]] only.<br><sup> 2 </sup>[[Creating%20an%20EIS%20Descriptor%20(ELUG)#EIS Root Descriptors|EIS Root Descriptors]] only.<br>
  
You can override the project-level cache invalidation configuration (see [[Configuring%20a%20Project%20(ELUG)|Configuring Cache Expiration at the Project Level]]) by defining cache invalidation at the descriptor or query level (see [[Using%20Advanced%20Query%20API%20(ELUG)|How to Configure Cache Expiration at the Query Level]]).
+
You can override the project-level cache invalidation configuration (see [[Configuring%20a%20Project%20(ELUG)#Configuring Cache Expiration at the Project Level|Configuring Cache Expiration at the Project Level]]) by defining cache invalidation at the descriptor or query level (see [[Using%20Advanced%20Query%20API%20(ELUG)#How to Configure Cache Expiration at the Query Level|How to Configure Cache Expiration at the Query Level]]).
  
You can customize how EclipseLink communicates the fact that an object has been declared invalid to improve efficiency, if you are using a coordinated cache. For more information, see [[#Configuring Cache Coordination Change Propagation at the Descriptor Level]].
+
You can customize how EclipseLink communicates the fact that an object has been declared invalid to improve efficiency, if you are using a coordinated cache. For more information, see [[#Configuring Cache Coordination Change Propagation at the Descriptor Level|Configuring Cache Coordination Change Propagation at the Descriptor Level]].
  
For more information, see [[Introduction%20to%20Cache%20(ELUG)|Cache Invalidation]].
+
For more information, see [[Introduction%20to%20Cache%20(ELUG)#Cache Invalidation|Cache Invalidation]].
  
  
  
 
===How to Configure Cache Expiration at the Descriptor Level Using Workbench===
 
===How to Configure Cache Expiration at the Descriptor Level Using Workbench===
 
 
To specify the cache invalidation information for a descriptor, use this procedure:
 
To specify the cache invalidation information for a descriptor, use this procedure:
 
 
# Select the descriptor in the '''Navigator'''.
 
# Select the descriptor in the '''Navigator'''.
# Select the '''Caching''' tab in the '''Editor'''. The '''Caching''' tab appears.<br>'''''Figure 115-28 Caching Tab, Expiration Options'''''[[Image:idcacexp.gif|Caching Tab, Expiration Options]]<br><br>
+
# Select the '''Caching''' tab in the '''Editor'''. The '''Caching''' tab appears.<br><span id="Figure 115-28"></span>''''' Caching Tab, Expiration Options'''''<br>[[Image:idcacexp.gif|Caching Tab, Expiration Options]]<br><br>
# Complete the [topicid:descriptor.identity.CacheExpiry Cache Expiry] options on the tab.
+
# Complete the Cache Expiry options on the tab.
 
+
Use this table to enter data in the following fields on the '''Caching''' tab to specify the cache invalidation policy for the descriptors.
+
  
  
 +
Use this table to enter data in the following fields on the '''Caching''' tab to specify the cache invalidation policy for the descriptors.
  
 
{| class="HRuleInformal" dir="ltr" title="This table defines Cache Expiry options on the Caching tab" summary="This table defines Cache Expiry options on the Caching tab" width="100%" border="1" frame="hsides" rules="rows" cellpadding="3" frame="hsides" rules="rows"
 
{| class="HRuleInformal" dir="ltr" title="This table defines Cache Expiry options on the Caching tab" summary="This table defines Cache Expiry options on the Caching tab" width="100%" border="1" frame="hsides" rules="rows" cellpadding="3" frame="hsides" rules="rows"
Line 2,265: Line 2,200:
 
| id="r2c1-t40" headers="r1c1-t40" align="left" | '''Project Default'''
 
| id="r2c1-t40" headers="r1c1-t40" align="left" | '''Project Default'''
 
| headers="r2c1-t40 r1c2-t40" align="left" |
 
| headers="r2c1-t40 r1c2-t40" align="left" |
Use the project's cache expiration options for this descriptor. See [[Configuring%20a%20Project%20(ELUG)|Configuring Cache Expiration at the Project Level]] for more information.
+
Use the project's cache expiration options for this descriptor. See [[Configuring%20a%20Project%20(ELUG)#Configuring Cache Expiration at the Project Level|Configuring Cache Expiration at the Project Level]] for more information.
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r3c1-t40" headers="r1c1-t40" align="left" | '''No Expiry'''
 
| id="r3c1-t40" headers="r1c1-t40" align="left" | '''No Expiry'''
Line 2,284: Line 2,219:
 
{| 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:''' These options apply per descriptor. See [[Configuring%20a%20Project%20(ELUG)|Configuring Cache Expiration at the Project Level]] for information on configuring project-level options.
+
'''Note:''' These options apply per descriptor. See [[Configuring%20a%20Project%20(ELUG)#Configuring Cache Expiration at the Project Level|Configuring Cache Expiration at the Project Level]] for information on configuring project-level options.
 
|}
 
|}
  
Line 2,290: Line 2,225:
  
 
'''See Also'''
 
'''See Also'''
: [[#Configuring Cache Expiration at the Descriptor Level]]
+
: [[#Configuring Cache Expiration at the Descriptor Level|Configuring Cache Expiration at the Descriptor Level]]
: [[Configuring%20a%20Project%20(ELUG)|Configuring Cache Expiration at the Project Level]]
+
: [[Configuring%20a%20Project%20(ELUG)#Configuring Cache Expiration at the Project Level|Configuring Cache Expiration at the Project Level]]
: [[#Configuring a Descriptor]]
+
  
===How to Configure Cache Expiration at the Descriptor Level Using Java===
 
  
 +
 +
===How to Configure Cache Expiration at the Descriptor Level Using Java===
 
Use <tt>ClassDescriptor</tt> method <tt>setCacheInvalidationPolicy</tt> to set an appropriate instance of <tt>CacheInvalidationPolicy</tt>.
 
Use <tt>ClassDescriptor</tt> method <tt>setCacheInvalidationPolicy</tt> to set an appropriate instance of <tt>CacheInvalidationPolicy</tt>.
  
==Configuring Cache Existence Checking at the Descriptor Level==
 
  
 +
 +
==Configuring Cache Existence Checking at the Descriptor Level==
 
When EclipseLink writes an object to the database, EclipseLink runs an existence check to determine whether to perform an insert or an update.
 
When EclipseLink writes an object to the database, EclipseLink runs an existence check to determine whether to perform an insert or an update.
  
By default, EclipseLink checks against the cache. We recommend that you use this default existence check option for most applications. Checking the database for existence can cause a performance bottleneck in your application.
+
When using JPA, EclipseLink checks against the database by default.  When using the EclipseLink Native API it checks against the cache by default. We recommend that you use the default existence check option for most applications.
  
 
This table summarizes which descriptors support existence checking.
 
This table summarizes which descriptors support existence checking.
Line 2,308: Line 2,244:
  
 
<span id="Table 115-18"></span>
 
<span id="Table 115-18"></span>
''''' Descriptor Support for Existence Checking'''''
 
 
 
{| class="RuleFormal" dir="ltr" title="Descriptor Support for Existence Checking" summary="This table summarizes which descriptors support existence checking." width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
 
{| class="RuleFormal" dir="ltr" title="Descriptor Support for Existence Checking" summary="This table summarizes which descriptors support existence checking." width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
! id="r1c1-t42" align="left" valign="bottom" | '''Descriptor'''
 
! id="r1c1-t42" align="left" valign="bottom" | '''Descriptor'''
! id="r1c2-t42" align="left" valign="bottom" | '''[[#How to Configure Cache Existence Checking at the Descriptor Level Using Workbench]]<br>'''
+
! id="r1c2-t42" align="left" valign="bottom" | '''[[#How to Configure Cache Existence Checking at the Descriptor Level Using Workbench|Using the Workbench]]<br>'''
! id="r1c3-t42" align="left" valign="bottom" | '''[[#How to Configure Cache Existence Checking at the Descriptor Level Using Java]]<br>'''
+
! id="r1c3-t42" align="left" valign="bottom" | '''[[#How to Configure Cache Existence Checking at the Descriptor Level Using Java|Using Java]]<br>'''
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r2c1-t42" headers="r1c1-t42" align="left" |
 
| id="r2c1-t42" headers="r1c1-t42" align="left" |
Relational Descriptors <sup>Foot 1 </sup>
+
Relational Descriptors <sup> 1 </sup>
 
| headers="r2c1-t42 r1c2-t42" align="left" |
 
| headers="r2c1-t42 r1c2-t42" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
| headers="r2c1-t42 r1c3-t42" align="left" |
 
| headers="r2c1-t42 r1c3-t42" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r3c1-t42" headers="r1c1-t42" align="left" |
 
| id="r3c1-t42" headers="r1c1-t42" align="left" |
 
Object-Relational Data Type Descriptors
 
Object-Relational Data Type Descriptors
 
| headers="r3c1-t42 r1c2-t42" align="left" |
 
| headers="r3c1-t42 r1c2-t42" align="left" |
Unsupported<br>
+
[[Image:unsupport.gif|Unsupported]]<br>
 
| headers="r3c1-t42 r1c3-t42" align="left" |
 
| headers="r3c1-t42 r1c3-t42" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r4c1-t42" headers="r1c1-t42" align="left" |
 
| id="r4c1-t42" headers="r1c1-t42" align="left" |
EIS Descriptors <sup>Foot 2 </sup>
+
EIS Descriptors <sup> 2 </sup>
 
| headers="r4c1-t42 r1c2-t42" align="left" |
 
| headers="r4c1-t42 r1c2-t42" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
| headers="r4c1-t42 r1c3-t42" align="left" |
 
| headers="r4c1-t42 r1c3-t42" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r5c1-t42" headers="r1c1-t42" align="left" |
 
| id="r5c1-t42" headers="r1c1-t42" align="left" |
 
XML Descriptors
 
XML Descriptors
 
| headers="r5c1-t42 r1c2-t42" align="left" |
 
| headers="r5c1-t42 r1c2-t42" align="left" |
Unsupported<br>
+
[[Image:unsupport.gif|Unsupported]]<br>
 
| headers="r5c1-t42 r1c3-t42" align="left" |
 
| headers="r5c1-t42 r1c3-t42" align="left" |
Unsupported<br>
+
[[Image:unsupport.gif|Unsupported]]<br>
 
|}
 
|}
  
<br><sup>Footnote 1 </sup>Relational class descriptors only (see [[Creating%20a%20Relational%20Descriptor%20(ELUG)|Creating Relational Class Descriptors]]).<br><sup>Footnote 2 </sup>EIS root descriptors only (see [[Creating%20an%20EIS%20Descriptor%20(ELUG)|EIS Root Descriptors]]).<br>
+
<br><sup> 1 </sup>[[Creating%20a%20Relational%20Descriptor%20(ELUG)#Creating Relational Class Descriptors|Relational Class Descriptors]] only.<br><sup> 2 </sup>[[Creating%20an%20EIS%20Descriptor%20(ELUG)#EIS Root Descriptors|EIS Root Descriptors]] only.<br>
  
You can configure existence checking at the descriptor level to override the project level configuration (see [[Configuring%20a%20Project%20(ELUG)|Configuring Existence Checking at the Project Level]]).
+
You can configure existence checking at the descriptor level to override the project level configuration (see [[Configuring%20a%20Project%20(ELUG)#Configuring Existence Checking at the Project Level|Configuring Existence Checking at the Project Level]]).
  
 
For more information see the following:
 
For more information see the following:
 
+
* [[Introduction%20to%20Cache%20(ELUG)#Cache Type and Object Identity|Cache Type and Object Identity]]
* [[Introduction%20to%20Cache%20(ELUG)|Cache Type and Object Identity]]
+
* [[Introduction%20to%20EclipseLink%20Queries%20(ELUG)#Queries and the Cache|Queries and the Cache]]
* [[Introduction%20to%20EclipseLink%20Queries%20(ELUG)|Queries and the Cache]]
+
* [[Using%20Advanced%20Unit%20of%20Work%20API%20(ELUG)#How to Use Registration and Existence Checking|How to Use Registration and Existence Checking]]
* [[Using%20Advanced%20Unit%20of%20Work%20API%20(ELUG)|How to Use Registration and Existence Checking]]
+
  
  
  
 
===How to Configure Cache Existence Checking at the Descriptor Level Using Workbench===
 
===How to Configure Cache Existence Checking at the Descriptor Level Using Workbench===
 
 
To specify the existence checking information for a descriptor, use this procedure:
 
To specify the existence checking information for a descriptor, use this procedure:
 
 
# Select the descriptor in the '''Navigator'''.
 
# Select the descriptor in the '''Navigator'''.
# Select the '''Caching''' tab in the '''Editor'''. The Caching tab appears.<br>'''''Figure 115-29 Caching Tab, Existence Checking Options'''''[[Image:idexichk.gif|Caching Tab, Existence Checking Options]]<br><br>
+
# Select the '''Caching''' tab in the '''Editor'''. The Caching tab appears.<br>'''''Caching Tab, Existence Checking Options'''''<br>[[Image:idexichk.gif|Caching Tab, Existence Checking Options]]<br><br>
 
# Complete the '''Existence Checking''' options on the tab.
 
# Complete the '''Existence Checking''' options on the tab.
 +
  
 
Use this table to enter data in the following fields of the tab to specify the existence checking options for newly created descriptors:
 
Use this table to enter data in the following fields of the tab to specify the existence checking options for newly created descriptors:
 
 
  
 
{| class="HRuleInformal" dir="ltr" title="This table defines existence checking options on the Caching tab" summary="This table defines existence checking options on the Caching tab" width="100%" border="1" frame="hsides" rules="rows" cellpadding="3" frame="hsides" rules="rows"
 
{| class="HRuleInformal" dir="ltr" title="This table defines existence checking options on the Caching tab" summary="This table defines existence checking options on the Caching tab" width="100%" border="1" frame="hsides" rules="rows" cellpadding="3" frame="hsides" rules="rows"
Line 2,379: Line 2,309:
 
| id="r3c1-t43" headers="r1c1-t43" align="left" | '''Check Cache then Database'''
 
| id="r3c1-t43" headers="r1c1-t43" align="left" | '''Check Cache then Database'''
 
| headers="r3c1-t43 r1c2-t43" align="left" |
 
| headers="r3c1-t43 r1c2-t43" align="left" |
If an object is not in the cache, query the database to determine if the object exists. If the object exists, do an update. Otherwise, do an insert. Selecting this option may negatively impact performance. For more information, see [[Using%20Advanced%20Unit%20of%20Work%20API%20(ELUG)|Using Check Database]].
+
If an object is not in the cache, query the database to determine if the object exists. If the object exists, do an update. Otherwise, do an insert. Selecting this option may negatively impact performance. For more information, see [[Using%20Advanced%20Unit%20of%20Work%20API%20(ELUG)#Using Check Database|Using Check Database]].
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r4c1-t43" headers="r1c1-t43" align="left" | '''Assume Existence'''
 
| id="r4c1-t43" headers="r1c1-t43" align="left" | '''Assume Existence'''
 
| headers="r4c1-t43 r1c2-t43" align="left" |
 
| headers="r4c1-t43 r1c2-t43" align="left" |
Always assume objects exist: always do an update (never do an insert). For more information, see [[Using%20Advanced%20Unit%20of%20Work%20API%20(ELUG)|Using Assume Existence]].
+
Always assume objects exist: always do an update (never do an insert). For more information, see [[Using%20Advanced%20Unit%20of%20Work%20API%20(ELUG)#Using Assume Existence|Using Assume Existence]].
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r5c1-t43" headers="r1c1-t43" align="left" | '''Assume Non-Existence'''
 
| id="r5c1-t43" headers="r1c1-t43" align="left" | '''Assume Non-Existence'''
 
| headers="r5c1-t43 r1c2-t43" align="left" |
 
| headers="r5c1-t43 r1c2-t43" align="left" |
Always assume objects do not exist: always do an insert (never do an update). For more information, see [[Using%20Advanced%20Unit%20of%20Work%20API%20(ELUG)|Using Assume Nonexistence]].
+
Always assume objects do not exist: always do an insert (never do an update). For more information, see [[Using%20Advanced%20Unit%20of%20Work%20API%20(ELUG)#Using Assume Nonexistence|Using Assume Nonexistence]].
 
|}
 
|}
  
<br>
 
  
===How to Configure Cache Existence Checking at the Descriptor Level Using Java===
 
  
To configure existence checking at the descriptor level using Java, use <tt>ClassDescriptor</tt> method <tt>getQueryManager</tt> to acquire the <tt>DescriptorQueryManager</tt> from the descriptor and then use one of the following <tt>DescriptorQueryManager</tt> methods (see [[#Example 115-8|Configuring Existence Checking Using Java]]):
 
  
* <tt>checkCacheForDoesExist</tt>–check the session cache. If the object is not in the cache, assume that the object does not exist (do an insert). If the object is in the cache, assume that the object exists (do an update). We recommend using this option for most applications.
+
===How to Configure Cache Existence Checking at the Descriptor Level Using Java===
* <tt>checkDatabaseForDoesExist</tt>–if an object is not in the cache, query the database to determine if the object exists. If the object exists, do an update. Otherwise, do an insert. Selecting this option may negatively impact performance. For more information, see [[Using%20Advanced%20Unit%20of%20Work%20API%20(ELUG)|Using Check Database]].
+
To configure existence checking at the descriptor level using Java, use <tt>ClassDescriptor</tt> method <tt>getQueryManager</tt> to acquire the <tt>DescriptorQueryManager</tt> from the descriptor and then use one of the following <tt>DescriptorQueryManager</tt> methods (see the [[#Example 115-8|Configuring Existence Checking Using Java]] example):
* <tt>assumeExistenceForDoesExist</tt>–always assume objects exist: always do an update (never do an insert). For more information, see [[Using%20Advanced%20Unit%20of%20Work%20API%20(ELUG)|Using Assume Existence]].
+
* <tt>checkCacheForDoesExist</tt> – check the session cache. If the object is not in the cache, assume that the object does not exist (do an insert). If the object is in the cache, assume that the object exists (do an update). We recommend using this option for most applications.
* <tt>assumeNonExistenceForDoesExist</tt>–always assume objects do not exist: always do an insert (never do an update). For more information, see [[Using%20Advanced%20Unit%20of%20Work%20API%20(ELUG)|Using Assume Nonexistence]].
+
* <tt>checkDatabaseForDoesExist</tt> – if an object is not in the cache, query the database to determine if the object exists. If the object exists, do an update. Otherwise, do an insert. Selecting this option may negatively impact performance. For more information, see [[Using%20Advanced%20Unit%20of%20Work%20API%20(ELUG)#Using Check Database|Using Check Database]].
 +
* <tt>assumeExistenceForDoesExist</tt> – always assume objects exist: always do an update (never do an insert). For more information, see [[Using%20Advanced%20Unit%20of%20Work%20API%20(ELUG)#Using Assume Existence|Using Assume Existence]].
 +
* <tt>assumeNonExistenceForDoesExist</tt> – always assume objects do not exist: always do an insert (never do an update). For more information, see [[Using%20Advanced%20Unit%20of%20Work%20API%20(ELUG)#Using Assume Nonexistence|Using Assume Nonexistence]].
  
  
Line 2,407: Line 2,336:
  
 
==Configuring Reading Subclasses on Queries==
 
==Configuring Reading Subclasses on Queries==
 
 
If you are mapping an inheritance hierarchy, by default, queries on root or branch classes return instances of the root class and their subclasses.
 
If you are mapping an inheritance hierarchy, by default, queries on root or branch classes return instances of the root class and their subclasses.
  
 
Alternatively, you can configure a root or branch class descriptor to do the following:
 
Alternatively, you can configure a root or branch class descriptor to do the following:
 
 
* not include subclasses when the root or branch class is queried;
 
* not include subclasses when the root or branch class is queried;
 
* outer-join subclasses when the root or branch class is queried.
 
* outer-join subclasses when the root or branch class is queried.
Line 2,423: Line 2,350:
  
 
<span id="Table 115-19"></span>
 
<span id="Table 115-19"></span>
''''' Descriptor Support for Inherited Attribute Mapping Configuration'''''
+
 
  
 
{| class="RuleFormal" dir="ltr" title="Descriptor Support for Inherited Attribute Mapping Configuration" summary="This table summarizes which descriptors support Inherited Attribute Mapping Configuration." width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
 
{| class="RuleFormal" dir="ltr" title="Descriptor Support for Inherited Attribute Mapping Configuration" summary="This table summarizes which descriptors support Inherited Attribute Mapping Configuration." width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
! id="r1c1-t44" align="left" valign="bottom" | '''Descriptor'''
 
! id="r1c1-t44" align="left" valign="bottom" | '''Descriptor'''
! id="r1c2-t44" align="left" valign="bottom" | '''[[#How to Configure Reading Subclasses on Queries Using Workbench]]<br>'''
+
! id="r1c2-t44" align="left" valign="bottom" | '''[[#How to Configure Reading Subclasses on Queries Using Workbench|Using the Workbench]]<br>'''
! id="r1c3-t44" align="left" valign="bottom" | '''[[#How to Configure Reading Subclasses on Queries Using Java]]<br>'''
+
! id="r1c3-t44" align="left" valign="bottom" | '''[[#How to Configure Reading Subclasses on Queries Using Java|Using Java]]<br>'''
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r2c1-t44" headers="r1c1-t44" align="left" |
 
| id="r2c1-t44" headers="r1c1-t44" align="left" |
 
Relational Descriptors
 
Relational Descriptors
 
| headers="r2c1-t44 r1c2-t44" align="left" |
 
| headers="r2c1-t44 r1c2-t44" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
| headers="r2c1-t44 r1c3-t44" align="left" |
 
| headers="r2c1-t44 r1c3-t44" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r3c1-t44" headers="r1c1-t44" align="left" |
 
| id="r3c1-t44" headers="r1c1-t44" align="left" |
 
Object-Relational Data Type Descriptors
 
Object-Relational Data Type Descriptors
 
| headers="r3c1-t44 r1c2-t44" align="left" |
 
| headers="r3c1-t44 r1c2-t44" align="left" |
Unsupported<br>
+
[[Image:unsupport.gif|Unsupported]]<br>
 
| headers="r3c1-t44 r1c3-t44" align="left" |
 
| headers="r3c1-t44 r1c3-t44" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r4c1-t44" headers="r1c1-t44" align="left" |
 
| id="r4c1-t44" headers="r1c1-t44" align="left" |
 
EIS Descriptors
 
EIS Descriptors
 
| headers="r4c1-t44 r1c2-t44" align="left" |
 
| headers="r4c1-t44 r1c2-t44" align="left" |
Unsupported<br>
+
[[Image:unsupport.gif|Unsupported]]<br>
 
| headers="r4c1-t44 r1c3-t44" align="left" |
 
| headers="r4c1-t44 r1c3-t44" align="left" |
Unsupported<br>
+
[[Image:unsupport.gif|Unsupported]]<br>
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r5c1-t44" headers="r1c1-t44" align="left" |
 
| id="r5c1-t44" headers="r1c1-t44" align="left" |
 
XML Descriptors
 
XML Descriptors
 
| headers="r5c1-t44 r1c2-t44" align="left" |
 
| headers="r5c1-t44 r1c2-t44" align="left" |
Unsupported<br>
+
[[Image:unsupport.gif|Unsupported]]<br>
 
| headers="r5c1-t44 r1c3-t44" align="left" |
 
| headers="r5c1-t44 r1c3-t44" align="left" |
Unsupported<br>
+
[[Image:unsupport.gif|Unsupported]]<br>
 
|}
 
|}
  
 
<br>
 
<br>
  
For more information, see [[Introduction%20to%20Descriptors%20(ELUG)|Descriptors and Inheritance]].
+
For more information, see [[Introduction%20to%20Descriptors%20(ELUG)#Descriptors and Inheritance|Descriptors and Inheritance]].
  
  
  
 
===How to Configure Reading Subclasses on Queries Using Workbench===
 
===How to Configure Reading Subclasses on Queries Using Workbench===
 
 
To configure reading classes on subqueries, use this procedure:
 
To configure reading classes on subqueries, use this procedure:
 
 
# In the '''Navigator''', select a root or branch descriptor.If the '''Inheritance''' advanced property is not visible for the descriptor, right-click the descriptor and choose '''Select Advanced Properties''' > '''Inheritance''' from context menu or from the '''Selected''' menu.
 
# In the '''Navigator''', select a root or branch descriptor.If the '''Inheritance''' advanced property is not visible for the descriptor, right-click the descriptor and choose '''Select Advanced Properties''' > '''Inheritance''' from context menu or from the '''Selected''' menu.
# Click the '''Inheritance''' tab.<br>'''''Figure 115-30 Inheritance Tab, Read Subclasses on Query Option'''''[[Image:inhrqury.gif|Inheritance Tab, Read Subclasses on Query Option]]<br><br>
+
# Click the '''Inheritance''' tab.<br>'''''Inheritance Tab, Read Subclasses on Query Option'''''<br>[[Image:inhrqury.gif|Inheritance Tab, Read Subclasses on Query Option]]<br><br>
 
# Enter data in the Read Subclasses on Query section on the '''Inheritance''' tab.
 
# Enter data in the Read Subclasses on Query section on the '''Inheritance''' tab.
  
Line 2,497: Line 2,422:
 
'''See Also'''
 
'''See Also'''
  
: [[#Configuring Reading Subclasses on Queries]]
+
: [[#Configuring Reading Subclasses on Queries|Configuring Reading Subclasses on Queries]]
  
  
  
 
===How to Configure Reading Subclasses on Queries Using Java===
 
===How to Configure Reading Subclasses on Queries Using Java===
 +
Create a [[#Configuring Amendment Methods|descriptor amendment method]] to customize the root or branch class descriptor's <tt>InheritancePolicy</tt>.
  
Create a descriptor amendment method ( [[#Configuring Amendment Methods]]) to customize the root or branch class descriptor's <tt>InheritancePolicy</tt>.
+
This example shows an amendment method for the <tt>Person</tt> class. In this example, you use the <tt>InheritancePolicy</tt> method <tt>dontReadSubclassesOnQueries</tt> to configure the descriptor so that subclasses are not read on queries.
 
+
[[#Example 115-9]] shows an amendment method for the <tt>Person</tt> class. In this example, you use the <tt>InheritancePolicy</tt> method <tt>dontReadSubclassesOnQueries</tt> to configure the descriptor so that subclasses are not read on queries.
+
  
  
Line 2,518: Line 2,442:
  
  
[[#Example 115-10]] shows an amendment method for the <tt>Person</tt> class. In this example, you use the <tt>InheritancePolicy</tt> method <tt>setReadAllSubclassesViewName</tt> to optimize multiple table inheritance queries.
+
This example shows an amendment method for the <tt>Person</tt> class. In this example, you use the <tt>InheritancePolicy</tt> method <tt>setReadAllSubclassesViewName</tt> to optimize multiple table inheritance queries.
  
  
Line 2,531: Line 2,455:
  
  
[[#Example 115-11]] shows an amendment method for the <tt>Person</tt> class. In this example, you use the <tt>InheritancePolicy</tt> method <tt>setShouldOuterJoinSubclasses</tt> to configure the descriptor so that subclasses are outer-joined on queries.
+
This example shows an amendment method for the <tt>Person</tt> class. In this example, you use the <tt>InheritancePolicy</tt> method <tt>setShouldOuterJoinSubclasses</tt> to configure the descriptor so that subclasses are outer-joined on queries.
  
  
Line 2,542: Line 2,466:
 
  ...
 
  ...
  
==Configuring Inheritance for a Child (Branch or Leaf) Class Descriptor==
 
  
 +
 +
==Configuring Inheritance for a Child (Branch or Leaf) Class Descriptor==
 
Inheritance describes how a derived (child) class inherits the characteristics of its superclass (parent). When you designate a class as a child, you must also specify the descriptor that represents the child's parent in your inheritance hierarchy.
 
Inheritance describes how a derived (child) class inherits the characteristics of its superclass (parent). When you designate a class as a child, you must also specify the descriptor that represents the child's parent in your inheritance hierarchy.
  
Line 2,550: Line 2,475:
  
 
<span id="Table 115-20"></span>
 
<span id="Table 115-20"></span>
''''' Descriptor Support for Child Inheritance Configuration'''''
 
  
 
{| class="RuleFormal" dir="ltr" title="Descriptor Support for Child Inheritance Configuration" summary="This table summarizes which descriptors support child inheritance configuration." width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
 
{| class="RuleFormal" dir="ltr" title="Descriptor Support for Child Inheritance Configuration" summary="This table summarizes which descriptors support child inheritance configuration." width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
! id="r1c1-t46" align="left" valign="bottom" | '''Descriptor'''
 
! id="r1c1-t46" align="left" valign="bottom" | '''Descriptor'''
! id="r1c2-t46" align="left" valign="bottom" | '''[[#How to Configure Inheritance for a Child (Branch or Leaf) Class Descriptor Using Workbench]]<br>'''
+
! id="r1c2-t46" align="left" valign="bottom" | '''[[#How to Configure Inheritance for a Child (Branch or Leaf) Class Descriptor Using Workbench|Using the Workbench]]<br>'''
! id="r1c3-t46" align="left" valign="bottom" | '''[[#How to Configure Inheritance for a Child (Branch or Leaf) Class Descriptor Using Java]]<br>'''
+
! id="r1c3-t46" align="left" valign="bottom" | '''[[#How to Configure Inheritance for a Child (Branch or Leaf) Class Descriptor Using Java|Using Java]]<br>'''
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r2c1-t46" headers="r1c1-t46" align="left" |
 
| id="r2c1-t46" headers="r1c1-t46" align="left" |
 
Relational Descriptors
 
Relational Descriptors
 
| headers="r2c1-t46 r1c2-t46" align="left" |
 
| headers="r2c1-t46 r1c2-t46" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
| headers="r2c1-t46 r1c3-t46" align="left" |
 
| headers="r2c1-t46 r1c3-t46" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r3c1-t46" headers="r1c1-t46" align="left" |
 
| id="r3c1-t46" headers="r1c1-t46" align="left" |
 
Object-Relational Data Type Descriptors
 
Object-Relational Data Type Descriptors
 
| headers="r3c1-t46 r1c2-t46" align="left" |
 
| headers="r3c1-t46 r1c2-t46" align="left" |
Unsupported<br>
+
[[Image:unsupport.gif|Unsupported]]<br>
 
| headers="r3c1-t46 r1c3-t46" align="left" |
 
| headers="r3c1-t46 r1c3-t46" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r4c1-t46" headers="r1c1-t46" align="left" |
 
| id="r4c1-t46" headers="r1c1-t46" align="left" |
 
EIS Descriptors
 
EIS Descriptors
 
| headers="r4c1-t46 r1c2-t46" align="left" |
 
| headers="r4c1-t46 r1c2-t46" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
| headers="r4c1-t46 r1c3-t46" align="left" |
 
| headers="r4c1-t46 r1c3-t46" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r5c1-t46" headers="r1c1-t46" align="left" |
 
| id="r5c1-t46" headers="r1c1-t46" align="left" |
 
XML Descriptors
 
XML Descriptors
 
| headers="r5c1-t46 r1c2-t46" align="left" |
 
| headers="r5c1-t46 r1c2-t46" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
| headers="r5c1-t46 r1c3-t46" align="left" |
 
| headers="r5c1-t46 r1c3-t46" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
|}
 
|}
  
 
<br>
 
<br>
  
For more information about inheritance, see [[Introduction%20to%20Descriptors%20(ELUG)|Descriptors and Inheritance]].
+
For more information about inheritance, see [[Introduction%20to%20Descriptors%20(ELUG)#Descriptors and Inheritance|Descriptors and Inheritance]].
  
For more information about configuring inheritance for a parent (root) class descriptor, see [[#Configuring Inheritance for a Parent (Root) Descriptor]].
+
For more information about configuring inheritance for a parent (root) class descriptor, see [[#Configuring Inheritance for a Parent (Root) Descriptor|Configuring Inheritance for a Parent (Root) Descriptor]].
  
  
  
 
===How to Configure Inheritance for a Child (Branch or Leaf) Class Descriptor Using Workbench===
 
===How to Configure Inheritance for a Child (Branch or Leaf) Class Descriptor Using Workbench===
 
 
To create a child (branch or leaf class) for an inheritance, use this procedure.
 
To create a child (branch or leaf class) for an inheritance, use this procedure.
 
 
# In the '''Navigator''', select the descriptor you wish to specify as a child.
 
# In the '''Navigator''', select the descriptor you wish to specify as a child.
 
# Choose the '''Inheritance''' tab in the '''Property''' window.If the '''Inheritance''' tab is not visible, right-click the descriptor and choose '''Select Advanced Properties''' > '''Inheritance'''.
 
# Choose the '''Inheritance''' tab in the '''Property''' window.If the '''Inheritance''' tab is not visible, right-click the descriptor and choose '''Select Advanced Properties''' > '''Inheritance'''.
# Select the '''Is Child Descriptor''' option to specify this descriptor is a child class. The '''Parent Descriptor''' list is now enabled and the class indicator information is disabled.<br>'''''Figure 115-31 Inheritance Tab, Child Descriptor Option'''''[[Image:inhbr_lf.gif|Inheritance Tab, Child Descriptor Option]]<br><br>
+
# Select the '''Is Child Descriptor''' option to specify this descriptor is a child class. The '''Parent Descriptor''' list is now enabled and the class indicator information is disabled.<br>'''''Inheritance Tab, Child Descriptor Option'''''<br>[[Image:inhbr_lf.gif|Inheritance Tab, Child Descriptor Option]]<br><br>
 
# Complete each child descriptor option on the Inheritance tab.
 
# Complete each child descriptor option on the Inheritance tab.
  
Line 2,618: Line 2,540:
 
| id="r3c1-t47" headers="r1c1-t47" align="left" | ''' Parent Descriptor'''
 
| id="r3c1-t47" headers="r1c1-t47" align="left" | ''' Parent Descriptor'''
 
| headers="r3c1-t47 r1c2-t47" align="left" |
 
| headers="r3c1-t47 r1c2-t47" align="left" |
Use the list to select the parent of this descriptor. See [[Introduction%20to%20Descriptors%20(ELUG)|Descriptors and Inheritance]] for more information.
+
Use the list to select the parent of this descriptor. See [[Introduction%20to%20Descriptors%20(ELUG)#Descriptors and Inheritance|Descriptors and Inheritance]] for more information.
 
|}
 
|}
  
<br>
+
 
  
 
'''See Also'''
 
'''See Also'''
: [[#Configuring Inheritance for a Child (Branch or Leaf) Class Descriptor]]
+
: [[#Configuring Inheritance for a Child (Branch or Leaf) Class Descriptor|Configuring Inheritance for a Child (Branch or Leaf) Class Descriptor]][[#Configuring Inheritance for a Child (Branch or Leaf) Class Descriptor|Configuring Inheritance for a Child (Branch or Leaf) Class Descriptor]]
: [[Introduction%20to%20Descriptors%20(ELUG)|Descriptors and Inheritance]]
+
: [[Introduction%20to%20Descriptors%20(ELUG)#Descriptors and Inheritance|Descriptors and Inheritance]]
  
===How to Configure Inheritance for a Child (Branch or Leaf) Class Descriptor Using Java===
 
  
 +
 +
===How to Configure Inheritance for a Child (Branch or Leaf) Class Descriptor Using Java===
 
Using Java, you can configure an inheritance child descriptor using <tt>InheritancePolicy</tt> method <tt>setParentClass</tt>, as this example shows.
 
Using Java, you can configure an inheritance child descriptor using <tt>InheritancePolicy</tt> method <tt>setParentClass</tt>, as this example shows.
  
Line 2,636: Line 2,559:
 
  descriptor.getInheritancePolicy().setParentClass(ChildClass.class);
 
  descriptor.getInheritancePolicy().setParentClass(ChildClass.class);
  
==Configuring Inheritance for a Parent (Root) Descriptor==
 
  
 +
 +
==Configuring Inheritance for a Parent (Root) Descriptor==
 
Inheritance describes how a derived (child) class inherits the characteristics of its superclass (parent). When you designate a class as a parent, you can configure how EclipseLink handles the class's inheritance hierarchy.
 
Inheritance describes how a derived (child) class inherits the characteristics of its superclass (parent). When you designate a class as a parent, you can configure how EclipseLink handles the class's inheritance hierarchy.
  
[[#Table 115-23]] summarizes which descriptors support parent inheritance configuration.
+
The following table summarizes which descriptors support parent inheritance configuration.
  
  
 
<span id="Table 115-21"></span>
 
<span id="Table 115-21"></span>
''''' Descriptor Support for Parent Inheritance Configuration'''''
 
  
 
{| class="RuleFormal" dir="ltr" title="Descriptor Support for Parent Inheritance Configuration" summary="This table summarizes which descriptors support Parent Inheritance Configuration" width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
 
{| class="RuleFormal" dir="ltr" title="Descriptor Support for Parent Inheritance Configuration" summary="This table summarizes which descriptors support Parent Inheritance Configuration" width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
! id="r1c1-t48" align="left" valign="bottom" | '''Descriptor'''
 
! id="r1c1-t48" align="left" valign="bottom" | '''Descriptor'''
! id="r1c2-t48" align="left" valign="bottom" | '''[[#How to Configure Inheritance for a Parent (Root) Descriptor Using Workbench]]<br>'''
+
! id="r1c2-t48" align="left" valign="bottom" | '''[[#How to Configure Inheritance for a Parent (Root) Descriptor Using Workbench|Using the Workbench]]<br>'''
! id="r1c3-t48" align="left" valign="bottom" | '''[[#How to Configure Inheritance for a Parent (Root) Descriptor Using Java]]<br>'''
+
! id="r1c3-t48" align="left" valign="bottom" | '''[[#How to Configure Inheritance for a Parent (Root) Descriptor Using Java|Using Java]]<br>'''
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r2c1-t48" headers="r1c1-t48" align="left" |
 
| id="r2c1-t48" headers="r1c1-t48" align="left" |
 
Relational Descriptors
 
Relational Descriptors
 
| headers="r2c1-t48 r1c2-t48" align="left" |
 
| headers="r2c1-t48 r1c2-t48" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
| headers="r2c1-t48 r1c3-t48" align="left" |
 
| headers="r2c1-t48 r1c3-t48" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r3c1-t48" headers="r1c1-t48" align="left" |
 
| id="r3c1-t48" headers="r1c1-t48" align="left" |
 
Object-Relational Data Type Descriptors
 
Object-Relational Data Type Descriptors
 
| headers="r3c1-t48 r1c2-t48" align="left" |
 
| headers="r3c1-t48 r1c2-t48" align="left" |
Unsupported<br>
+
[[Image:unsupport.gif|Unsupported]]<br>
 
| headers="r3c1-t48 r1c3-t48" align="left" |
 
| headers="r3c1-t48 r1c3-t48" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r4c1-t48" headers="r1c1-t48" align="left" |
 
| id="r4c1-t48" headers="r1c1-t48" align="left" |
 
EIS Descriptors
 
EIS Descriptors
 
| headers="r4c1-t48 r1c2-t48" align="left" |
 
| headers="r4c1-t48 r1c2-t48" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
| headers="r4c1-t48 r1c3-t48" align="left" |
 
| headers="r4c1-t48 r1c3-t48" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r5c1-t48" headers="r1c1-t48" align="left" |
 
| id="r5c1-t48" headers="r1c1-t48" align="left" |
 
XML Descriptors
 
XML Descriptors
 
| headers="r5c1-t48 r1c2-t48" align="left" |
 
| headers="r5c1-t48 r1c2-t48" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
| headers="r5c1-t48 r1c3-t48" align="left" |
 
| headers="r5c1-t48 r1c3-t48" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
|}
 
|}
  
 
<br>
 
<br>
  
For more information about configuring inheritance for a child (branch or leaf) class descriptor, see [[#Configuring Inheritance for a Child (Branch or Leaf) Class Descriptor]].
+
For more information about configuring inheritance for a child (branch or leaf) class descriptor, see [[#Configuring Inheritance for a Child (Branch or Leaf) Class Descriptor|Configuring Inheritance for a Child (Branch or Leaf) Class Descriptor]].
  
For more information, see [[Introduction%20to%20Descriptors%20(ELUG)|Descriptors and Inheritance].
+
For more information, see [[Introduction%20to%20Descriptors%20(ELUG)#Descriptors and Inheritance|Descriptors and Inheritance]].
  
  
  
 
===How to Configure Inheritance for a Parent (Root) Descriptor Using Workbench===
 
===How to Configure Inheritance for a Parent (Root) Descriptor Using Workbench===
 
 
To create a root class for an inheritance, use this procedure.
 
To create a root class for an inheritance, use this procedure.
 
 
# In the '''Navigator''', select the descriptor you wish to specify as the root.
 
# In the '''Navigator''', select the descriptor you wish to specify as the root.
 
# Choose the '''Inheritance''' tab in the '''Property''' window.If the '''Inheritance''' tab is not visible, right-click the descriptor and choose '''Select Advanced Properties''' > '''Inheritance'''.
 
# Choose the '''Inheritance''' tab in the '''Property''' window.If the '''Inheritance''' tab is not visible, right-click the descriptor and choose '''Select Advanced Properties''' > '''Inheritance'''.
# Select the '''Is Root Parent Descriptor''' option to specify this descriptor is a root class.<br>'''''Figure 115-32 Inheritance Tab, Configuring Inheritance for a Root Descriptor'''''<br>[[Image:didoeis.gif|Inheritance Tab, Configuring Inheritance for a Root Descriptor]]<br><br>
+
# Select the '''Is Root Parent Descriptor''' option to specify this descriptor is a root class.<br><span id="Figure 115-32"></span>''''' Inheritance Tab, Configuring Inheritance for a Root Descriptor'''''<br>[[Image:didoeis.gif|Inheritance Tab, Configuring Inheritance for a Root Descriptor]]<br><br>
 
# Complete each root descriptor option on the Inheritance tab.
 
# Complete each root descriptor option on the Inheritance tab.
  
Line 2,712: Line 2,633:
 
| id="r3c1-t49" headers="r1c1-t49" align="left" | '''Use Class Extraction Method'''
 
| id="r3c1-t49" headers="r1c1-t49" align="left" | '''Use Class Extraction Method'''
 
| headers="r3c1-t49 r1c2-t49" align="left" |
 
| headers="r3c1-t49 r1c2-t49" align="left" |
Choose this option to specify a class indicator using a class extraction method, and select your static class extraction method from the list. For more information, see [[Introduction%20to%20Descriptors%20(ELUG)|Using Class Extraction Methods]].
+
Choose this option to specify a class indicator using a class extraction method, and select your static class extraction method from the list. For more information, see [[Introduction%20to%20Descriptors%20(ELUG)#Using Class Extraction Methods|Using Class Extraction Methods]].
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r4c1-t49" headers="r1c1-t49" align="left" | '''Use Class Indicator Field'''
 
| id="r4c1-t49" headers="r1c1-t49" align="left" | '''Use Class Indicator Field'''
 
| headers="r4c1-t49 r1c2-t49" align="left" |
 
| headers="r4c1-t49 r1c2-t49" align="left" |
Choose this option to specify a class indicator using a class indicator field. For more information, see [[Introduction%20to%20Descriptors%20(ELUG)|Using Class Indicator Fields]].
+
Choose this option to specify a class indicator using a class indicator field. For more information, see [[Introduction%20to%20Descriptors%20(ELUG)#Using Class Indicator Fields|Using Class Indicator Fields]].
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r5c1-t49" headers="r1c1-t49" align="left" | '''Field Selection'''
 
| id="r5c1-t49" headers="r1c1-t49" align="left" | '''Field Selection'''
Line 2,722: Line 2,643:
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r6c1-t49" headers="r1c1-t49" align="left" |
 
| id="r6c1-t49" headers="r1c1-t49" align="left" |
'''Use XML Schema "Type" Attribute'''<sup>Foot 1 </sup>
+
'''Use XML Schema "Type" Attribute'''<sup> 1 </sup>
 
| headers="r6c1-t49 r1c2-t49" align="left" | Select this option to use the type attribute specified in the XML schema for this descriptor's reference class.
 
| headers="r6c1-t49 r1c2-t49" align="left" | Select this option to use the type attribute specified in the XML schema for this descriptor's reference class.
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r7c1-t49" headers="r1c1-t49" align="left" | '''Specify Field'''
 
| id="r7c1-t49" headers="r1c1-t49" align="left" | '''Specify Field'''
 
| headers="r7c1-t49 r1c2-t49" align="left" |
 
| headers="r7c1-t49 r1c2-t49" align="left" |
For a relational descriptor, select the field of the database table associated with this descriptor (see [[Configuring%20a%20Relational%20Descriptor%20(ELUG)|Configuring Associated Tables]]). For an EIS root descriptor (using XML records) or an XML descriptor, click '''Browse''' to select an element attribute or text node.
+
For a relational descriptor, select the field of the database table associated with this descriptor (see [[Configuring%20a%20Relational%20Descriptor%20(ELUG)#Configuring Associated Tables|Configuring Associated Tables]]). For an EIS root descriptor (using XML records) or an XML descriptor, click '''Browse''' to select an element attribute or text node.
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r8c1-t49" headers="r1c1-t49" align="left" | ''' Indicator Selection'''
 
| id="r8c1-t49" headers="r1c1-t49" align="left" | ''' Indicator Selection'''
Line 2,744: Line 2,665:
 
|}
 
|}
  
<br><sup>Footnote 1 </sup>EIS root (see [[Creating%20an%20EIS%20Descriptor%20(ELUG)|EIS Root Descriptors]]) or XML descriptors (see [[Introduction%20to%20XML%20Descriptors%20(ELUG)|XML Descriptor Concepts]]) only.<br>
+
<br><sup> 1 </sup>EIS root (see [[Creating%20an%20EIS%20Descriptor%20(ELUG)#EIS Root Descriptors|EIS Root Descriptors]]) or XML descriptors (see [[Introduction%20to%20XML%20Descriptors%20(ELUG)#XML Descriptor Concepts|XML Descriptor Concepts]]) only.<br>
  
===How to Configure Inheritance for a Parent (Root) Descriptor Using Java===
 
  
Create a descriptor amendment method ( [[#Configuring Amendment Methods]]) to customize the root class descriptor's inheritance policy using <tt>InheritancePolicy</tt> methods <tt>setParentClass</tt>, <tt>setClassIndicatorFieldName</tt>, <tt>addClassIndicator</tt>, <tt>useClassNameAsIndicator</tt> and <tt>setClassExtractionMethodName</tt>, as required.
 
  
The following example shows amendment methods for the <tt>Person</tt> and <tt>Student</tt> classes where <tt>Student</tt> extends <tt>Person</tt> in a relational project. In this example, a class indicator field is used (see [[Introduction%20to%20Descriptors%20(ELUG)|Using Class Indicator Fields]]).
+
===How to Configure Inheritance for a Parent (Root) Descriptor Using Java===
 +
Create a [[#Configuring Amendment Methods|descriptor amendment method]] to customize the root class descriptor's inheritance policy using <tt>InheritancePolicy</tt> methods <tt>setParentClass</tt>, <tt>setClassIndicatorFieldName</tt>, <tt>addClassIndicator</tt>, <tt>useClassNameAsIndicator</tt> and <tt>setClassExtractionMethodName</tt>, as required.
 +
 
 +
The following example shows amendment methods for the <tt>Person</tt> and <tt>Student</tt> classes where <tt>Student</tt> extends <tt>Person</tt> in a relational project. In this example, a class indicator field is used (see [[Introduction%20to%20Descriptors%20(ELUG)#Using Class Indicator Fields|Using Class Indicator Fields]]).
  
  
Line 2,758: Line 2,680:
 
  public static void addToPersonDescriptor(Descriptor descriptor) {
 
  public static void addToPersonDescriptor(Descriptor descriptor) {
 
     descriptor.getInheritancePolicy().setClassIndicatorFieldName("CLIENT_TYPE");
 
     descriptor.getInheritancePolicy().setClassIndicatorFieldName("CLIENT_TYPE");
     descriptor.getInheritancePolicy().
+
     descriptor.getInheritancePolicy().addClassIndicator(Student.class, indicator);
                                    addClassIndicator(Student.class, indicator);
+
 
  }
 
  }
 
   
 
   
Line 2,769: Line 2,690:
  
  
If you are using a class-extraction method (see [[Introduction%20to%20Descriptors%20(ELUG)|Using Class Extraction Methods]]), you may also need to use <tt>InheritancePolicy</tt> methods <tt>setOnlyInstancesExpression</tt> and <tt>setWithAllSubclassesExpression</tt> (see [[#Configuring Inheritance Expressions for a Parent (Root) Class Descriptor]]).
+
If you are using a class-extraction method (see [[Introduction%20to%20Descriptors%20(ELUG)#Using Class Extraction Methods|Using Class Extraction Methods]]), you may also need to use <tt>InheritancePolicy</tt> methods <tt>setOnlyInstancesExpression</tt> and <tt>setWithAllSubclassesExpression</tt> (see [[#Configuring Inheritance Expressions for a Parent (Root) Class Descriptor|Configuring Inheritance Expressions for a Parent (Root) Class Descriptor]]).
  
The following example shows amendment methods for the <tt>Person</tt> and <tt>Student</tt> classes where <tt>Student</tt> extends <tt>Person</tt> in an EIS project using XML records. In this example, a class indicator field is used (see [[Introduction%20to%20Descriptors%20(ELUG)|Using Class Indicator Fields]]).
+
The following example shows amendment methods for the <tt>Person</tt> and <tt>Student</tt> classes where <tt>Student</tt> extends <tt>Person</tt> in an EIS project using XML records. In this example, a class indicator field is used (see [[Introduction%20to%20Descriptors%20(ELUG)#Using Class Indicator Fields|Using Class Indicator Fields]]).
  
  
Line 2,778: Line 2,699:
 
  ...
 
  ...
 
  public static void addToPersonDescriptor(Descriptor descriptor) {
 
  public static void addToPersonDescriptor(Descriptor descriptor) {
     descriptor.getInheritancePolicy().
+
     descriptor.getInheritancePolicy().setClassIndicatorField(new XMLField("@CLIENT_TYPE"));
                          setClassIndicatorField(new XMLField("@CLIENT_TYPE"));
+
     descriptor.getInheritancePolicy().addClassIndicator(Student.class, indicator);
     descriptor.getInheritancePolicy().
+
                          addClassIndicator(Student.class, indicator);
+
 
  }
 
  }
 
   
 
   
 
  public static void addToStudentDescriptor(Descriptor descriptor) {
 
  public static void addToStudentDescriptor(Descriptor descriptor) {
 
     descriptor.getInheritancePolicy().setParentClass(Person.class);
 
     descriptor.getInheritancePolicy().setParentClass(Person.class);
     descriptor.getInheritancePolicy().setClassIndicatorField(
+
     descriptor.getInheritancePolicy().setClassIndicatorField(new XMLField("@CLIENT_TYPE"));
                                              new XMLField("@CLIENT_TYPE"));
+
 
  }
 
  }
 
  ...
 
  ...
  
==Configuring Inheritance Expressions for a Parent (Root) Class Descriptor==
 
  
If your class uses inheritance (see [[Introduction%20to%20Descriptors%20(ELUG)|Descriptors and Inheritance]]) with a class extraction method (see [[Introduction%20to%20Descriptors%20(ELUG)|Using Class Extraction Methods]]) you must provide EclipseLink with expressions to correctly filter sibling instances for all classes that share a common table.
+
==Configuring Inheritance Expressions for a Parent (Root) Class Descriptor==
 +
If your class uses inheritance (see [[Introduction%20to%20Descriptors%20(ELUG)#Descriptors and Inheritance|Descriptors and Inheritance]]) with a class extraction method (see [[Introduction%20to%20Descriptors%20(ELUG)#Using Class Extraction Methods|Using Class Extraction Methods]]) you must provide EclipseLink with expressions to correctly filter sibling instances for all classes that share a common table.
  
 
This table summarizes which descriptors support inheritance expression configuration.
 
This table summarizes which descriptors support inheritance expression configuration.
Line 2,799: Line 2,717:
  
 
<span id="Table 115-22"></span>
 
<span id="Table 115-22"></span>
''''' Descriptor Support for Inheritance Expression Configuration'''''
 
  
 
{| class="RuleFormal" dir="ltr" title="Descriptor Support for Inheritance Expression Configuration" summary="This table summarizes which descriptors support inheritance expression configuration." width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
 
{| class="RuleFormal" dir="ltr" title="Descriptor Support for Inheritance Expression Configuration" summary="This table summarizes which descriptors support inheritance expression configuration." width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
Line 2,805: Line 2,722:
 
! id="r1c1-t50" align="left" valign="bottom" | '''Descriptor'''
 
! id="r1c1-t50" align="left" valign="bottom" | '''Descriptor'''
 
! id="r1c2-t50" align="left" valign="bottom" | '''How to Use Workbench'''
 
! id="r1c2-t50" align="left" valign="bottom" | '''How to Use Workbench'''
! id="r1c3-t50" align="left" valign="bottom" | '''[[#How to Configure Inheritance Expressions for a Parent (Root) Class Descriptor Using Java]]<br>'''
+
! id="r1c3-t50" align="left" valign="bottom" | '''[[#How to Configure Inheritance Expressions for a Parent (Root) Class Descriptor Using Java|Using Java]]<br>'''
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r2c1-t50" headers="r1c1-t50" align="left" |
 
| id="r2c1-t50" headers="r1c1-t50" align="left" |
 
Relational Descriptors
 
Relational Descriptors
 
| headers="r2c1-t50 r1c2-t50" align="left" |
 
| headers="r2c1-t50 r1c2-t50" align="left" |
Unsupported<br>
+
[[Image:unsupport.gif|Unsupported]]<br>
 
| headers="r2c1-t50 r1c3-t50" align="left" |
 
| headers="r2c1-t50 r1c3-t50" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r3c1-t50" headers="r1c1-t50" align="left" |
 
| id="r3c1-t50" headers="r1c1-t50" align="left" |
 
Object-Relational Data Type Descriptors
 
Object-Relational Data Type Descriptors
 
| headers="r3c1-t50 r1c2-t50" align="left" |
 
| headers="r3c1-t50 r1c2-t50" align="left" |
Unsupported<br>
+
[[Image:unsupport.gif|Unsupported]]<br>
 
| headers="r3c1-t50 r1c3-t50" align="left" |
 
| headers="r3c1-t50 r1c3-t50" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r4c1-t50" headers="r1c1-t50" align="left" |
 
| id="r4c1-t50" headers="r1c1-t50" align="left" |
 
EIS Descriptors
 
EIS Descriptors
 
| headers="r4c1-t50 r1c2-t50" align="left" |
 
| headers="r4c1-t50 r1c2-t50" align="left" |
Unsupported<br>
+
[[Image:unsupport.gif|Unsupported]]<br>
 
| headers="r4c1-t50 r1c3-t50" align="left" |
 
| headers="r4c1-t50 r1c3-t50" align="left" |
Unsupported<br>
+
[[Image:unsupport.gif|Unsupported]]<br>
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r5c1-t50" headers="r1c1-t50" align="left" |
 
| id="r5c1-t50" headers="r1c1-t50" align="left" |
 
XML Descriptors
 
XML Descriptors
 
| headers="r5c1-t50 r1c2-t50" align="left" |
 
| headers="r5c1-t50 r1c2-t50" align="left" |
Unsupported<br>
+
[[Image:unsupport.gif|Unsupported]]<br>
 
| headers="r5c1-t50 r1c3-t50" align="left" |
 
| headers="r5c1-t50 r1c3-t50" align="left" |
Unsupported<br>
+
[[Image:unsupport.gif|Unsupported]]<br>
 
|}
 
|}
  
<br>
 
  
[[#Figure 115-33|Example Inheritance Hierarchy]] shows a typical inheritance hierarchy. In this example, instances of both <tt>Person</tt> and <tt>Student</tt> are stored in the same <tt>PERSON</tt> table, as [[#Figure 115-34|PERSON Table]] shows: an instance of <tt>Person</tt> has a <tt>null</tt> value for <tt>STUDENT_NUMBER</tt>. Instances of <tt>Company</tt> are stored in a separate <tt>COMPANY</tt> table.
+
 
 +
The [[#Figure 115-33|Example Inheritance Hierarchy]] figure shows a typical inheritance hierarchy. In this example, instances of both <tt>Person</tt> and <tt>Student</tt> are stored in the same <tt>PERSON</tt> table, as the [[#Figure 115-34|PERSON Table]] figure shows: an instance of <tt>Person</tt> has a <tt>null</tt> value for <tt>STUDENT_NUMBER</tt>. Instances of <tt>Company</tt> are stored in a separate <tt>COMPANY</tt> table.
  
 
<br>
 
<br>
Line 2,858: Line 2,775:
 
Queries on a class that has its own table for its specific data, such as <tt>Company</tt>, and does not share this table with any sibling classes, do not require these expressions.
 
Queries on a class that has its own table for its specific data, such as <tt>Company</tt>, and does not share this table with any sibling classes, do not require these expressions.
  
If you use a class indicator type field (see [[Introduction%20to%20Descriptors%20(ELUG)|Using Class Indicator Fields]]), EclipseLink automatically generates the required expressions.
+
If you use a class indicator type field (see [[Introduction%20to%20Descriptors%20(ELUG)#Using Class Indicator Fields|Using Class Indicator Fields]]), EclipseLink automatically generates the required expressions.
  
If you use a class extraction method (see [[Introduction%20to%20Descriptors%20(ELUG)|Using Class Extraction Methods]]), you must provide EclipseLink with an expressions to correctly filter sibling instances for all classes that share a common table.
+
If you use a class extraction method (see [[Introduction%20to%20Descriptors%20(ELUG)#Using Class Extraction Methods|Using Class Extraction Methods]]), you must provide EclipseLink with an expressions to correctly filter sibling instances for all classes that share a common table.
  
 
For concrete classes, you must define an only- instances expression.
 
For concrete classes, you must define an only- instances expression.
Line 2,868: Line 2,785:
 
When EclipseLink queries for a leaf class, it uses the only- instances expression to filter out any sibling classes.
 
When EclipseLink queries for a leaf class, it uses the only- instances expression to filter out any sibling classes.
  
When EclipseLink queries for a root or branch class whose subclasses do not define their own tables, it uses the with-all-subclasses expression. This is also the case when a subclass view is used (see [[#Configuring Reading Subclasses on Queries]]).
+
When EclipseLink queries for a root or branch class whose subclasses do not define their own tables, it uses the with-all-subclasses expression. This is also the case when a subclass view is used (see [[#Configuring Reading Subclasses on Queries|Configuring Reading Subclasses on Queries]]).
  
 
When querying for a root or branch class that has subclasses that span multiple tables, a query is performed for each concrete class in the inheritance hierarchy using the only- instances expression to filter sibling classes.
 
When querying for a root or branch class that has subclasses that span multiple tables, a query is performed for each concrete class in the inheritance hierarchy using the only- instances expression to filter sibling classes.
  
When a class extraction method is used the only-instances expression is used to determine if a class is concrete. If a class does not require an only instances expression, do not enable reading subclasses on queries (see [[#Configuring Reading Subclasses on Queries]), otherwise EclipseLink will assume that the class has no instances and it will skip that class on queries.
+
When a class extraction method is used the only-instances expression is used to determine if a class is concrete. If a class does not require an only instances expression, do not enable reading subclasses on queries (see [[#Configuring Reading Subclasses on Queries|Configuring Reading Subclasses on Queries]]), otherwise EclipseLink will assume that the class has no instances and it will skip that class on queries.
  
For more information about inheritance expressions, see [[Introduction%20to%20Descriptors%20(ELUG)|Specifying Expressions for Only-Instances and With-All-Subclasses]].
+
For more information about inheritance expressions, see [[Introduction%20to%20Descriptors%20(ELUG)#Specifying Expressions for Only-Instances and With-All-Subclasses|Specifying Expressions for Only-Instances and With-All-Subclasses]].
  
  
  
 
===How to Configure Inheritance Expressions for a Parent (Root) Class Descriptor Using Java===
 
===How to Configure Inheritance Expressions for a Parent (Root) Class Descriptor Using Java===
 +
Create a [[#Configuring Amendment Methods|descriptor amendment method]] to customize the root class descriptor's <tt>InheritancePolicy</tt> using <tt>InheritancePolicy</tt> methods <tt>setOnlyInstancesExpression</tt> and <tt>setWithAllSubclassesExpression</tt>, as required.
  
Create a descriptor amendment method ( [[#Configuring Amendment Methods]]) to customize the root class descriptor's <tt>InheritancePolicy</tt> using <tt>InheritancePolicy</tt> methods <tt>setOnlyInstancesExpression</tt> and <tt>setWithAllSubclassesExpression</tt>, as required.
+
This example shows amendment methods for the <tt>Person</tt> and <tt>Student</tt> descriptors based on the class hierarchy shown in the  [[#Figure 115-33|Example Inheritance Hierarchy]] figure and the database table shown in the  [[#Figure 115-34|PERSON Table]] figure.
 
+
[[#Example 115-15|Configuring Only-Instances Expressions]] shows amendment methods for the <tt>Person</tt> and <tt>Student</tt> descriptors based on the class hierarchy shown in [[#Figure 115-33]] and the database table shown in [[#Figure 115-34]].
+
  
  
Line 2,905: Line 2,821:
  
  
[[#Example 115-16|Configuring Only-Instances and With-All-Subclasses Expressions]] shows amendment methods for the <tt>Bicycle</tt> and <tt>NonFueledVehicle</tt> descriptors based on the class hierarchy shown in [[Introduction%20to%20Descriptors%20(ELUG)|Figure 14-1]] if the vehicle hierarchy stored all of the classes in a single vehicle table, and there was not a class indicator, but a class extraction method instead.
+
The [[#Example 115-16|Configuring Only-Instances and With-All-Subclasses Expressions]] example shows amendment methods for the <tt>Bicycle</tt> and <tt>NonFueledVehicle</tt> descriptors based on the class hierarchy shown in [[Introduction%20to%20Descriptors%20(ELUG)|Figure 14-1]] if the vehicle hierarchy stored all of the classes in a single vehicle table, and there was not a class indicator, but a class extraction method instead.
  
  
Line 2,939: Line 2,855:
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
! id="r1c1-t51" align="left" valign="bottom" | '''Descriptor'''
 
! id="r1c1-t51" align="left" valign="bottom" | '''Descriptor'''
! id="r1c2-t51" align="left" valign="bottom" | '''[[#How to Configure Inherited Attribute Mapping in a Subclass Using Workbench]]<br>'''
+
! id="r1c2-t51" align="left" valign="bottom" | '''[[#How to Configure Inherited Attribute Mapping in a Subclass Using Workbench|Using the Workbench]]<br>'''
! id="r1c3-t51" align="left" valign="bottom" | '''[[#How to Configure Inherited Attribute Mapping in a Subclass Using Java]]<br>'''
+
! id="r1c3-t51" align="left" valign="bottom" | '''[[#How to Configure Inherited Attribute Mapping in a Subclass Using Java|Using Java]]<br>'''
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r2c1-t51" headers="r1c1-t51" align="left" |
 
| id="r2c1-t51" headers="r1c1-t51" align="left" |
 
Relational Descriptors
 
Relational Descriptors
 
| headers="r2c1-t51 r1c2-t51" align="left" |
 
| headers="r2c1-t51 r1c2-t51" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
| headers="r2c1-t51 r1c3-t51" align="left" |
 
| headers="r2c1-t51 r1c3-t51" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r3c1-t51" headers="r1c1-t51" align="left" |
 
| id="r3c1-t51" headers="r1c1-t51" align="left" |
 
Object-Relational Data Type Descriptors
 
Object-Relational Data Type Descriptors
 
| headers="r3c1-t51 r1c2-t51" align="left" |
 
| headers="r3c1-t51 r1c2-t51" align="left" |
Unsupported<br>
+
[[Image:unsupport.gif|Unsupported]]<br>
 
| headers="r3c1-t51 r1c3-t51" align="left" |
 
| headers="r3c1-t51 r1c3-t51" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r4c1-t51" headers="r1c1-t51" align="left" |
 
| id="r4c1-t51" headers="r1c1-t51" align="left" |
 
EIS Descriptors
 
EIS Descriptors
 
| headers="r4c1-t51 r1c2-t51" align="left" |
 
| headers="r4c1-t51 r1c2-t51" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
| headers="r4c1-t51 r1c3-t51" align="left" |
 
| headers="r4c1-t51 r1c3-t51" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r5c1-t51" headers="r1c1-t51" align="left" |
 
| id="r5c1-t51" headers="r1c1-t51" align="left" |
 
XML Descriptors
 
XML Descriptors
 
| headers="r5c1-t51 r1c2-t51" align="left" |
 
| headers="r5c1-t51 r1c2-t51" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
| headers="r5c1-t51 r1c3-t51" align="left" |
 
| headers="r5c1-t51 r1c3-t51" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
|}
 
|}
  
 
<br>
 
<br>
  
For more information, see [[Introduction%20to%20Descriptors%20(ELUG)|Descriptors and Inheritance]].
+
For more information, see [[Introduction%20to%20Descriptors%20(ELUG)#Descriptors and Inheritance|Descriptors and Inheritance]].
  
  
Line 2,992: Line 2,908:
 
==Configuring a Domain Object Method as an Event Handler==
 
==Configuring a Domain Object Method as an Event Handler==
  
You can associate a domain object method with any of the descriptor events shown in [[#Table 115-25|Descriptor Events]]. You can register any domain object method that complies with the following criteria:
+
You can associate a domain object method with any of the descriptor events shown in the [[#Table 115-25|Descriptor Events]] table. You can register any domain object method that complies with the following criteria:
 
+
 
* Is public.
 
* Is public.
 
* Returns void.
 
* Returns void.
Line 3,007: Line 2,922:
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
! id="r1c1-t52" align="left" valign="bottom" | '''Descriptor'''
 
! id="r1c1-t52" align="left" valign="bottom" | '''Descriptor'''
! id="r1c2-t52" align="left" valign="bottom" | '''[[#How to Configure a Domain Object Method as an Event Handler Using Workbench]]<br>'''
+
! id="r1c2-t52" align="left" valign="bottom" | '''[[#How to Configure a Domain Object Method as an Event Handler Using Workbench|Using the Workbench]]<br>'''
! id="r1c3-t52" align="left" valign="bottom" | '''[[#How to Configure a Domain Object Method as an Event Handler Using Java]]<br>'''
+
! id="r1c3-t52" align="left" valign="bottom" | '''[[#How to Configure a Domain Object Method as an Event Handler Using Java|Using Java]]<br>'''
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r2c1-t52" headers="r1c1-t52" align="left" |
 
| id="r2c1-t52" headers="r1c1-t52" align="left" |
 
Relational Descriptors
 
Relational Descriptors
 
| headers="r2c1-t52 r1c2-t52" align="left" |
 
| headers="r2c1-t52 r1c2-t52" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
| headers="r2c1-t52 r1c3-t52" align="left" |
 
| headers="r2c1-t52 r1c3-t52" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r3c1-t52" headers="r1c1-t52" align="left" |
 
| id="r3c1-t52" headers="r1c1-t52" align="left" |
 
Object-Relational Data Type Descriptors
 
Object-Relational Data Type Descriptors
 
| headers="r3c1-t52 r1c2-t52" align="left" |
 
| headers="r3c1-t52 r1c2-t52" align="left" |
Unsupported<br>
+
[[Image:unsupport.gif|Unsupported]]<br>
 
| headers="r3c1-t52 r1c3-t52" align="left" |
 
| headers="r3c1-t52 r1c3-t52" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r4c1-t52" headers="r1c1-t52" align="left" |
 
| id="r4c1-t52" headers="r1c1-t52" align="left" |
 
EIS Descriptors
 
EIS Descriptors
 
| headers="r4c1-t52 r1c2-t52" align="left" |
 
| headers="r4c1-t52 r1c2-t52" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
| headers="r4c1-t52 r1c3-t52" align="left" |
 
| headers="r4c1-t52 r1c3-t52" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r5c1-t52" headers="r1c1-t52" align="left" |
 
| id="r5c1-t52" headers="r1c1-t52" align="left" |
 
XML Descriptors
 
XML Descriptors
 
| headers="r5c1-t52 r1c2-t52" align="left" |
 
| headers="r5c1-t52 r1c2-t52" align="left" |
Unsupported<br>
+
[[Image:unsupport.gif|Unsupported]]<br>
 
| headers="r5c1-t52 r1c3-t52" align="left" |
 
| headers="r5c1-t52 r1c3-t52" align="left" |
Unsupported<br>
+
[[Image:unsupport.gif|Unsupported]]<br>
 
|}
 
|}
  
Line 3,043: Line 2,958:
 
For example, you can add a method <tt>handlePostDelete</tt> (that is public, returns void, and takes a single parameter of type <tt>DescriptorEvent</tt>) to your <tt>Employee</tt> object to handle <tt>PostDeleteEvent</tt> descriptor events. After you register that method with the <tt>DescriptorEventManager</tt> owned by the <tt>Employee</tt> object's descriptor as the handler for <tt>PostDeleteEvent</tt> descriptor events, whenever the EclipseLink runtime performs a post-delete operation on an instance of the <tt>Employee</tt> object, the runtime dispatches a <tt>PostDeleteEvent</tt> to the <tt>handlePostDelete</tt> method on the instance of the <tt>Employee</tt> object associated with that <tt>PostDeleteEvent</tt>.
 
For example, you can add a method <tt>handlePostDelete</tt> (that is public, returns void, and takes a single parameter of type <tt>DescriptorEvent</tt>) to your <tt>Employee</tt> object to handle <tt>PostDeleteEvent</tt> descriptor events. After you register that method with the <tt>DescriptorEventManager</tt> owned by the <tt>Employee</tt> object's descriptor as the handler for <tt>PostDeleteEvent</tt> descriptor events, whenever the EclipseLink runtime performs a post-delete operation on an instance of the <tt>Employee</tt> object, the runtime dispatches a <tt>PostDeleteEvent</tt> to the <tt>handlePostDelete</tt> method on the instance of the <tt>Employee</tt> object associated with that <tt>PostDeleteEvent</tt>.
  
The '''Descriptor Event ID''' column in [[#Table 115-25|Descriptor Events]] lists the <tt>DescriptorEventManager</tt> field name used to identify a particular event. The <tt>DescriptorEvent</tt> method <tt>getEventCode</tt> returns this value. For example:
+
The '''Descriptor Event ID''' column in the [[#Table 115-25|Descriptor Events]] table lists the <tt>DescriptorEventManager</tt> field name used to identify a particular event. The <tt>DescriptorEvent</tt> method <tt>getEventCode</tt> returns this value. For example:
  
 
   
 
   
Line 3,158: Line 3,073:
 
<br>
 
<br>
  
Alternatively, you can configure a descriptor event listener as an event handler (see [[#Configuring a Descriptor Event Listener as an Event Handler]).
+
Alternatively, you can configure a descriptor event listener as an event handler (see [[#Configuring a Descriptor Event Listener as an Event Handler|Configuring a Descriptor Event Listener as an Event Handler]]).
  
  
Line 3,167: Line 3,082:
  
 
# Select a descriptor in the '''Navigator'''. Its properties appear in the Editor.If the '''Events''' advanced property is not visible for the descriptor, then right-click the descriptor and choose '''Select Advanced Properties''' > '''Events''' from context menu or from the '''Selected''' menu.
 
# Select a descriptor in the '''Navigator'''. Its properties appear in the Editor.If the '''Events''' advanced property is not visible for the descriptor, then right-click the descriptor and choose '''Select Advanced Properties''' > '''Events''' from context menu or from the '''Selected''' menu.
# Click the '''Event''' tab in the '''Editor'''.<br>'''''Figure 115-35 Events Tab'''''<br>[[Image:descevt.gif|Description of Figure 115-35 follows]]<br>
+
# Click the '''Event''' tab in the '''Editor'''.<br><span id="Figure 115-35"></span>''''' Events Tab'''''<br>[[Image:descevt.gif|Description of follows]]<br>
 
# Select the appropriate method category from the list on the left.
 
# Select the appropriate method category from the list on the left.
# Choose the appropriate [topicid:descriptor.events;descriptor.events.delete domain object method] for each method in that category.
+
# Choose the appropriate domain object method for each method in that category.
  
 
Use this table to enter data in the following fields to select the appropriate domain object method:
 
Use this table to enter data in the following fields to select the appropriate domain object method:
Line 3,244: Line 3,159:
 
===How to Configure a Domain Object Method as an Event Handler Using Java===
 
===How to Configure a Domain Object Method as an Event Handler Using Java===
  
[[#Example 115-17|Domain Object Method as a Descriptor Event Handler]] shows a domain object class with method <tt>handlePostDelete</tt> defined to handle <tt>PostDeleteEvent</tt> descriptor events. [[#Example 115-18|Registering a Domain Object Method as a Descriptor Event Handler]] shows how to register this method as the <tt>PostDeleteEvent</tt> event handler. Whenever the EclipseLink runtime performs a post-delete operation on an instance of <tt>Employee</tt>, the runtime will dispatch a <tt>PostDeleteEvent</tt> to the <tt>DescriptorEventManager</tt> owned by the <tt>Employee</tt> object's descriptor. The <tt>DescriptorEventManager</tt> will then invoke the <tt>handlePostDelete</tt> method on the instance of <tt>Employee</tt> associated with that <tt>PostDeleteEvent</tt>.
+
The [[#Example 115-17|Domain Object Method as a Descriptor Event Handler]] example shows a domain object class with method <tt>handlePostDelete</tt> defined to handle <tt>PostDeleteEvent</tt> descriptor events. The [[#Example 115-18|Registering a Domain Object Method as a Descriptor Event Handler]] example shows how to register this method as the <tt>PostDeleteEvent</tt> event handler. Whenever the EclipseLink runtime performs a post-delete operation on an instance of <tt>Employee</tt>, the runtime will dispatch a <tt>PostDeleteEvent</tt> to the <tt>DescriptorEventManager</tt> owned by the <tt>Employee</tt> object's descriptor. The <tt>DescriptorEventManager</tt> will then invoke the <tt>handlePostDelete</tt> method on the instance of <tt>Employee</tt> associated with that <tt>PostDeleteEvent</tt>.
  
  
Line 3,264: Line 3,179:
 
==Configuring a Descriptor Event Listener as an Event Handler==
 
==Configuring a Descriptor Event Listener as an Event Handler==
  
You can create your own <tt>DescriptorEventListner</tt> and register it with a <tt>DescriptorEventManger</tt> in a descriptor amendment method. You can also configure a <tt>DescriptorEventListner</tt> to be notified of events through the Java event model.
+
You can create your own <tt>DescriptorEventListner</tt> and register it with a <tt>DescriptorEventManager</tt> in a descriptor amendment method. You can also configure a <tt>DescriptorEventListner</tt> to be notified of events through the Java event model.
  
You can register any object that implements the <tt>DescriptorEventListener</tt> interface with the <tt>DescriptorEventManager</tt> owned by a domain object's descriptor to handle any descriptor event type (see [[#Table 115-27|Descriptor Events]]). To quickly implement this interface, you can extend abstract class <tt>DescriptorEventAdapter</tt> and override only the methods for the events you are interested in.
+
You can register any object that implements the <tt>DescriptorEventListener</tt> interface with the <tt>DescriptorEventManager</tt> owned by a domain object's descriptor to handle any descriptor event type (see the [[#Table 115-27|Descriptor Events]] table). To quickly implement this interface, you can extend abstract class <tt>DescriptorEventAdapter</tt> and override only the methods for the events you are interested in.
  
 
This table summarizes which descriptors support descriptor event listener configuration.
 
This table summarizes which descriptors support descriptor event listener configuration.
Line 3,277: Line 3,192:
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
! id="r1c1-t55" align="left" valign="bottom" | '''Descriptor'''
 
! id="r1c1-t55" align="left" valign="bottom" | '''Descriptor'''
! id="r1c2-t55" align="left" valign="bottom" | '''How to Use Workbench'''
+
! id="r1c2-t55" align="left" valign="bottom" | '''[[#How to Configure a Descriptor Event Listener as an Event Handler Using Workbench|Using the Workbench]]<br>'''
! id="r1c3-t55" align="left" valign="bottom" | '''[[#How to Configure a Descriptor Event Listener as an Event Handler Using Java]]<br>'''
+
! id="r1c3-t55" align="left" valign="bottom" | '''[[#How to Configure a Descriptor Event Listener as an Event Handler Using Java|Using Java]]<br>'''
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r2c1-t55" headers="r1c1-t55" align="left" |
 
| id="r2c1-t55" headers="r1c1-t55" align="left" |
 
Relational Descriptors
 
Relational Descriptors
 
| headers="r2c1-t55 r1c2-t55" align="left" |
 
| headers="r2c1-t55 r1c2-t55" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
| headers="r2c1-t55 r1c3-t55" align="left" |
 
| headers="r2c1-t55 r1c3-t55" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r3c1-t55" headers="r1c1-t55" align="left" |
 
| id="r3c1-t55" headers="r1c1-t55" align="left" |
 
Object-Relational Data Type Descriptors
 
Object-Relational Data Type Descriptors
 
| headers="r3c1-t55 r1c2-t55" align="left" |
 
| headers="r3c1-t55 r1c2-t55" align="left" |
Unsupported<br>
+
[[Image:unsupport.gif|Unsupported]]<br>
 
| headers="r3c1-t55 r1c3-t55" align="left" |
 
| headers="r3c1-t55 r1c3-t55" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r4c1-t55" headers="r1c1-t55" align="left" |
 
| id="r4c1-t55" headers="r1c1-t55" align="left" |
 
EIS Descriptors
 
EIS Descriptors
 
| headers="r4c1-t55 r1c2-t55" align="left" |
 
| headers="r4c1-t55 r1c2-t55" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
| headers="r4c1-t55 r1c3-t55" align="left" |
 
| headers="r4c1-t55 r1c3-t55" align="left" |
Supported<br>
+
[[Image:support.gif|Supported]]<br>
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r5c1-t55" headers="r1c1-t55" align="left" |
 
| id="r5c1-t55" headers="r1c1-t55" align="left" |
 
XML Descriptors
 
XML Descriptors
 
| headers="r5c1-t55 r1c2-t55" align="left" |
 
| headers="r5c1-t55 r1c2-t55" align="left" |
Unsupported<br>
+
[[Image:unsupport.gif|Unsupported]]<br>
 
| headers="r5c1-t55 r1c3-t55" align="left" |
 
| headers="r5c1-t55 r1c3-t55" align="left" |
Unsupported<br>
+
[[Image:unsupport.gif|Unsupported]]<br>
 
|}
 
|}
  
Line 3,313: Line 3,228:
 
For example, you create a <tt>DescriptorEventListener</tt> to handle <tt>PostBuildEvent</tt> descriptor events for <tt>Employee</tt> objects. After you register this <tt>DescriptorEventListener</tt> with the <tt>DescriptorEventManager</tt> owned by the <tt>Employee</tt> object's descriptor, whenever the EclipseLink runtime performs a post-build operation on an instance of <tt>Employee</tt>, the runtime dispatches a <tt>PostBuilEvent</tt> to the event listener's <tt>postBuild</tt> method.
 
For example, you create a <tt>DescriptorEventListener</tt> to handle <tt>PostBuildEvent</tt> descriptor events for <tt>Employee</tt> objects. After you register this <tt>DescriptorEventListener</tt> with the <tt>DescriptorEventManager</tt> owned by the <tt>Employee</tt> object's descriptor, whenever the EclipseLink runtime performs a post-build operation on an instance of <tt>Employee</tt>, the runtime dispatches a <tt>PostBuilEvent</tt> to the event listener's <tt>postBuild</tt> method.
  
[[#Table 115-27|Descriptor Events]] lists the <tt>DescriptorEventListener</tt> methods associated with each descriptor event. The '''Descriptor Event Listener Method''' column lists the <tt>DescriptorEventListener</tt> methods associated with each <tt>DescriptorEvent</tt>.
+
The [[#Table 115-27|Descriptor Events]] table lists the <tt>DescriptorEventListener</tt> methods associated with each descriptor event. The '''Descriptor Event Listener Method''' column lists the <tt>DescriptorEventListener</tt> methods associated with each <tt>DescriptorEvent</tt>.
  
  
Line 3,426: Line 3,341:
  
  
 +
===How to Configure a Descriptor Event Listener as an Event Handler Using Workbench===
  
===How to Configure a Descriptor Event Listener as an Event Handler Using Java===
+
For more information, see [[#How to Configure a Domain Object Method as an Event Handler Using Workbench|Using the Workbench]].
  
[[#Example 115-19|DescriptorEventListener]] shows a <tt>DescriptorEventListener</tt> that handles <tt>PostBuildEvent</tt> descriptor events. [[#Example 115-20|Registering a DescriptorEventListener with the DescriptorEventManager]] shows how to register this <tt>DescriptorEventListener</tt> with the <tt>Employee</tt> object's descriptor. Whenever the EclipseLink runtime performs a post-build operation on an instance of <tt>Employee</tt>, the runtime will dispatch a post build event to the corresponding <tt>DescriptorEventListener</tt> method on each registered event listener (in this case, it calls the <tt>postBuild</tt> method).
+
 
 +
===How to Configure a Descriptor Event Listener as an Event Handler Using Java===
 +
The [[#Example 115-19|DescriptorEventListener]] example shows a <tt>DescriptorEventListener</tt> that handles <tt>PostBuildEvent</tt> descriptor events. The [[#Example 115-20|Registering a DescriptorEventListener with the DescriptorEventManager]] example shows how to register this <tt>DescriptorEventListener</tt> with the <tt>Employee</tt> object's descriptor. Whenever the EclipseLink runtime performs a post-build operation on an instance of <tt>Employee</tt>, the runtime will dispatch a post build event to the corresponding <tt>DescriptorEventListener</tt> method on each registered event listener (in this case, it calls the <tt>postBuild</tt> method).
  
  
Line 3,447: Line 3,365:
  
 
==Configuring Locking Policy==
 
==Configuring Locking Policy==
You can configure a descriptor with a locking policy that prevents one user writing over another user's work. This table summarizes which descriptors support locking policies.
+
 
 +
You can configure a descriptor with a locking policy that prevents one user writing over another user's work.
 +
 
 +
This table summarizes which descriptors support locking policies.
 +
 
  
 
<span id="Table 115-28"></span>
 
<span id="Table 115-28"></span>
 
''''' Descriptor Support for Locking Policy'''''
 
''''' Descriptor Support for Locking Policy'''''
 +
 
{| class="RuleFormalMax" dir="ltr" title="Descriptor Support for Locking Policy" summary="This table summarizes which descriptors support which locking policies." width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
 
{| class="RuleFormalMax" dir="ltr" title="Descriptor Support for Locking Policy" summary="This table summarizes which descriptors support which locking policies." width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
 
|- align="left" valign="top"
 
|- align="left" valign="top"
Line 3,457: Line 3,380:
 
! id="r1c3-t57" align="left" valign="bottom" | '''[[Introduction%20to%20Descriptors%20(ELUG)#Optimistic Field Locking Policies|Optimistic Field Locking Policies]]<br>'''
 
! id="r1c3-t57" align="left" valign="bottom" | '''[[Introduction%20to%20Descriptors%20(ELUG)#Optimistic Field Locking Policies|Optimistic Field Locking Policies]]<br>'''
 
! id="r1c4-t57" align="left" valign="bottom" | '''[[Introduction%20to%20Descriptors%20(ELUG)#Pessimistic Locking Policy|Pessimistic Locking Policy]]<br>'''
 
! id="r1c4-t57" align="left" valign="bottom" | '''[[Introduction%20to%20Descriptors%20(ELUG)#Pessimistic Locking Policy|Pessimistic Locking Policy]]<br>'''
! id="r1c5-t57" align="left" valign="bottom" | '''[[#How to Configure Locking Policy Using Workbench|Workbench]]<br>'''
+
! id="r1c5-t57" align="left" valign="bottom" | '''[[#How to Configure Locking Policy Using Workbench|Using the Workbench]]<br>'''
! id="r1c6-t57" align="left" valign="bottom" | '''[[#How to Configure Locking Policy Using Java|Java]]<br>'''
+
! id="r1c6-t57" align="left" valign="bottom" | '''[[#How to Configure Locking Policy Using Java|Using Java]]<br>'''
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r2c1-t57" headers="r1c1-t57" align="left" |
 
| id="r2c1-t57" headers="r1c1-t57" align="left" |
Relational Descriptors <sup>Foot 1 </sup>
+
Relational Descriptors<sup> 1 </sup>
 
| headers="r2c1-t57 r1c2-t57" align="left" |
 
| headers="r2c1-t57 r1c2-t57" align="left" |
Supported<br>
+
[[Image:support.gif|Supported.]]<br>
 
| headers="r2c1-t57 r1c3-t57" align="left" |
 
| headers="r2c1-t57 r1c3-t57" align="left" |
Supported<br>
+
[[Image:support.gif|Supported.]]<br>
 
| headers="r2c1-t57 r1c4-t57" align="left" |
 
| headers="r2c1-t57 r1c4-t57" align="left" |
Supported<br>
+
[[Image:support.gif|Supported.]]<br>
 
| headers="r2c1-t57 r1c5-t57" align="left" |
 
| headers="r2c1-t57 r1c5-t57" align="left" |
Supported<br>
+
[[Image:support.gif|Supported.]]<br>
 
| headers="r2c1-t57 r1c6-t57" align="left" |
 
| headers="r2c1-t57 r1c6-t57" align="left" |
Supported<br>
+
[[Image:support.gif|Supported.]]<br>
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r3c1-t57" headers="r1c1-t57" align="left" |
 
| id="r3c1-t57" headers="r1c1-t57" align="left" |
 
Object-Relational Data Type Descriptors
 
Object-Relational Data Type Descriptors
 
| headers="r3c1-t57 r1c2-t57" align="left" |
 
| headers="r3c1-t57 r1c2-t57" align="left" |
Supported<br>
+
[[Image:support.gif|Supported.]]<br>
 
| headers="r3c1-t57 r1c3-t57" align="left" |
 
| headers="r3c1-t57 r1c3-t57" align="left" |
Supported<br>
+
[[Image:support.gif|Supported.]]<br>
 
| headers="r3c1-t57 r1c4-t57" align="left" |
 
| headers="r3c1-t57 r1c4-t57" align="left" |
Supported<br>
+
[[Image:support.gif|Supported.]]<br>
 
| headers="r3c1-t57 r1c5-t57" align="left" |
 
| headers="r3c1-t57 r1c5-t57" align="left" |
Unsupported<br>
+
[[Image:unsupport.gif|Unsupported.]]<br>
 
| headers="r3c1-t57 r1c6-t57" align="left" |
 
| headers="r3c1-t57 r1c6-t57" align="left" |
Supported<br>
+
[[Image:support.gif|Supported.]]<br>
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r4c1-t57" headers="r1c1-t57" align="left" |
 
| id="r4c1-t57" headers="r1c1-t57" align="left" |
EIS Descriptors <sup>Foot 2 </sup>
+
EIS Descriptors <sup> 2 </sup>
 
| headers="r4c1-t57 r1c2-t57" align="left" |
 
| headers="r4c1-t57 r1c2-t57" align="left" |
Supported<br>
+
[[Image:support.gif|Supported.]]<br>
 
| headers="r4c1-t57 r1c3-t57" align="left" |
 
| headers="r4c1-t57 r1c3-t57" align="left" |
Unsupported<br>
+
[[Image:unsupport.gif|Unsupported.]]<br>
 
| headers="r4c1-t57 r1c4-t57" align="left" |
 
| headers="r4c1-t57 r1c4-t57" align="left" |
Supported<br>
+
[[Image:support.gif|Supported.]]<br>
 
| headers="r4c1-t57 r1c5-t57" align="left" |
 
| headers="r4c1-t57 r1c5-t57" align="left" |
Supported<br>
+
[[Image:support.gif|Supported.]]<br>
 
| headers="r4c1-t57 r1c6-t57" align="left" |
 
| headers="r4c1-t57 r1c6-t57" align="left" |
Supported<br>
+
[[Image:support.gif|Supported.]]<br>
 +
|- align="left" valign="top"
 +
| id="r5c1-t57" headers="r1c1-t57" align="left" |
 +
XML Descriptors
 +
| headers="r5c1-t57 r1c2-t57" align="left" |
 +
[[Image:unsupport.gif|Unsupported.]]<br>
 +
| headers="r5c1-t57 r1c3-t57" align="left" |
 +
[[Image:unsupport.gif|Unsupported.]]<br>
 +
| headers="r5c1-t57 r1c4-t57" align="left" |
 +
[[Image:unsupport.gif|Unsupported.]]<br>
 +
| headers="r5c1-t57 r1c5-t57" align="left" |
 +
[[Image:unsupport.gif|Unsupported.]]<br>
 +
| headers="r5c1-t57 r1c6-t57" align="left" |
 +
[[Image:unsupport.gif|Unsupported.]]<br>
 
|}
 
|}
 +
 +
<br><sup> 1 </sup>[[Creating%20a%20Relational%20Descriptor%20(ELUG)#Creating Relational Class Descriptors|Relational Class Descriptors]] only.<br><sup> 2 </sup>[[Creating%20an%20EIS%20Descriptor%20(ELUG)#EIS Root Descriptors|EIS Root Descriptors]] only.<br>
 +
 +
We recommend that you use a locking policy. You should use a locking policy in any multiuser environment to prevent one user writing over another user's changes. Although locking can be particularly important if multiple servers or multiple applications access the same data, even in a single server application, the same locking issue still exists. In a multiple-server environment, locking is still relevant even if your application uses cache refreshing or cache coordination.
 +
 +
If you are building a three-tier application, in order to correctly lock an object, you must obtain the lock before the object is sent to client to be edited. The type of locking you choose has an influence on how you can achieve this (see [[Introduction%20to%20Descriptors%20(ELUG)#Locking in a Three-Tier Application|Locking in a Three-Tier Application]]).
 +
 +
 +
 +
===How to Configure Locking Policy UsingWorkbench===
 +
To specify a descriptor's locking policy, use this procedure:
 +
 +
# In the '''Navigator''', select a relational or EIS root descriptor.If the '''Locking''' advanced property is not visible for the descriptor, right-click the descriptor and choose '''Select Advanced Properties''' '''>''' '''Locking''' from the context menu or from the '''Selected''' menu.
 +
# Click the '''Locking''' tab.<br>'''''Locking Tab for a Descriptor'''''<br>[[Image:rellock.gif|Locking Tab for a Descriptor]]<br><br><br>''''' Locking Tab for an EIS Root Descriptor'''''<br>[[Image:eislock.gif|Locking Tab for an EIS Root Descriptor]]<br><br>
 +
# Enter data in each field on the Locking tab.
 +
 +
Use this table to enter data in the following fields on the tab of the appropriate type:
 +
 +
{| class="HRuleInformal" dir="ltr" title="This table lists the attributes on the Locking tab." summary="This table defines each field on the Locking tab for a descriptor." width="100%" border="1" frame="hsides" rules="rows" cellpadding="3" frame="hsides" rules="rows"
 +
|- align="left" valign="top"
 +
! id="r1c1-t58" align="left" valign="bottom" | '''Field'''
 +
! id="r1c2-t58" align="left" valign="bottom" | '''Description'''
 +
|- align="left" valign="top"
 +
| id="r2c1-t58" headers="r1c1-t58" align="left" | '''Optimistic Locking'''
 +
| headers="r2c1-t58 r1c2-t58" align="left" | Specify that the descriptor uses optimistic locking.
 +
|- align="left" valign="top"
 +
| id="r3c1-t58" headers="r1c1-t58" align="left" | ''' By Version'''
 +
| headers="r3c1-t58 r1c2-t58" align="left" | Specify to use optimistic locking, based on versioning.
 +
|- align="left" valign="top"
 +
| id="r4c1-t58" headers="r1c1-t58" align="left" | '''Database Field'''
 +
| headers="r4c1-t58 r1c2-t58" align="left" |
 +
Select the database field that contains the version value used for optimistic locking. This field appears for relational descriptors only.
 +
|- align="left" valign="top"
 +
| id="r5c1-t58" headers="r1c1-t58" align="left" | ''' XPath'''
 +
| headers="r5c1-t58 r1c2-t58" align="left" |
 +
Click '''Browse''' to define the path to the element or attribute that stores the version value. This field appears for EIS root descriptors only.Ensure that the attribute's type corresponds to the type of locking policy you choose (<tt>numeric</tt> for '''Version Locking''' and <tt>timestamp</tt> for '''Timestamp Locking''').
 +
|- align="left" valign="top"
 +
| id="r6c1-t58" headers="r1c1-t58" align="left" | ''' Version Locking'''
 +
| headers="r6c1-t58 r1c2-t58" align="left" | Specify that the descriptor uses numeric version locking. The version field (defined by the '''Database Field''', for relational descriptors, or the '''XPath''', for EIS root descriptors) must be a <tt>numeric</tt> type
 +
|- align="left" valign="top"
 +
| id="r7c1-t58" headers="r1c1-t58" align="left" | '''Timestamp Locking'''
 +
| headers="r7c1-t58 r1c2-t58" align="left" | Specify that the descriptor uses time stamp version locking, based on time stamp. The version field (defined by the '''Database Field''', for relational descriptors, or the '''XPath''', for EIS root descriptors) must be a <tt>timestamp</tt> type.
 +
|- align="left" valign="top"
 +
| id="r8c1-t58" headers="r1c1-t58" align="left" | '''Store Version in Cache'''
 +
| headers="r8c1-t58 r1c2-t58" align="left" |
 +
Specify whether or not you want to store the version information in the cache. If you choose not to define a mapping for the version field, then you must enable this option to configure the descriptor to store the version value in the EclipseLink cache.
 +
 +
If you choose to define a mapping for the version field, then you must disable this option in order to store the version value in the object.<br>For more information, see [[Introduction%20to%20Descriptors%20(ELUG)#Optimistic Locking in a Three-Tier Application|Optimistic Locking in a Three-Tier Application]].
 +
|- align="left" valign="top"
 +
| id="r9c1-t58" headers="r1c1-t58" align="left" |
 +
''' By Fields''' <sup> 1 </sup>
 +
| headers="r9c1-t58 r1c2-t58" align="left" |
 +
Specify to use optimistic locking, based on database fields. These fields appear for relational descriptors only.
 +
|- align="left" valign="top"
 +
| id="r10c1-t58" headers="r1c1-t58" align="left" | '''All Fields'''
 +
| headers="r10c1-t58 r1c2-t58" align="left" | Select ''all'' fields for optimistic locking.
 +
|- align="left" valign="top"
 +
| id="r11c1-t58" headers="r1c1-t58" align="left" | ''' Changed Fields'''
 +
| headers="r11c1-t58 r1c2-t58" align="left" | Select ''only the changed'' fields for optimistic locking.
 +
|- align="left" valign="top"
 +
| id="r12c1-t58" headers="r1c1-t58" align="left" | '''Selected Fields'''
 +
| headers="r12c1-t58 r1c2-t58" align="left" | Click '''Add''' to select ''specific'' database fields for optimistic locking.
 +
|- align="left" valign="top"
 +
| id="r13c1-t58" headers="r1c1-t58" align="left" | '''Pessimistic Locking'''
 +
| headers="r13c1-t58 r1c2-t58" align="left" |
 +
Ignore this option as it is EJB CMP-specific.
 +
|- align="left" valign="top"
 +
| id="r14c1-t58" headers="r1c1-t58" align="left" | ''' Wait for Lock'''
 +
| headers="r14c1-t58 r1c2-t58" align="left" |
 +
Ignore this option as it is EJB CMP-specific.
 +
|}
 +
 +
<br><sup> 1 </sup> You cannot use field locking with the <tt>AttributeChangeTrackingPolicy</tt> (see [[Introduction%20to%20EclipseLink%20Transactions (ELUG)#Attribute Change Tracking Policy|Attribute Change Tracking Policy]]).<br>
 +
 +
===How to Configure Locking Policy Using Java===
 +
 +
This section describes the following:
 +
 +
* [[#Configuring an Optimistic Locking Policy|Configuring an Optimistic Locking Policy]]
 +
* [[#Configuring Optimistic Locking Policy Cascading|Configuring Optimistic Locking Policy Cascading]]
 +
 +
 +
 +
====Configuring an Optimistic Locking Policy====
 +
 +
Use the <tt>ClassDescriptor</tt> method <tt>setOptimisticLockingPolicy</tt> to set an instance of the appropriate optimistic field locking policy:
 +
 +
* <tt>AllFieldsLockingPolicy</tt>
 +
* <tt>ChangedFieldsLockingPolicy</tt>
 +
* <tt>SelectedFieldsLockingPolicy</tt>
 +
* <tt>VersionLockingPolicy</tt>
 +
* <tt>TimestampLockingPolicy</tt>
 +
 +
Use the <tt>ClassDescriptor</tt> method <tt>getOptimisticLockingPolicy</tt> to get the selected locking policy type and configure it.
 +
 +
 +
 +
====Configuring Optimistic Locking Policy Cascading====
 +
 +
If you are using a <tt>VersionLockingPolicy</tt>, you can enable cascading to configure EclipseLink to automatically force a version field update on a parent object when its privately owned child object's version field changes. Use <tt>VersionLockingPolicy</tt> method <tt>setIsCascaded</tt> passing in a <tt>boolean</tt> of <tt>true</tt> to enable cascading, or <tt>false</tt> to disable cascading.
 +
 +
For more information, see [[Introduction%20to%20Descriptors%20(ELUG)#Optimistic Version Locking Policies and Cascading|Optimistic Version Locking Policies and Cascading]].
 +
 +
==Configuring Returning Policy==
 +
 +
Using a <tt>ReturningPolicy</tt>, you can obtain field values from the data source when inserting or updating an object. EclipseLink uses the values that the data source returns to update the object attributes that map to these fields. You can specify which fields to return for inserts and updates. For insert fields, you can also specify whether or not to include the field value in the insert operation.
 +
 +
A <tt>ReturningPolicy</tt> is useful when the data source provides default or initial field values through defaults, triggers, or stored procedures. You can also use a <tt>ReturningPolicy</tt> to allow the data source to assign a sequence or primary key value.
 +
 +
Any object attribute that you do not configure in a descriptor's <tt>ReturningPolicy</tt> receives the default behavior: in the context of a unit of work, if the attribute has changed, its value is written to the database. If the SQL statement invokes a trigger or stored procedure that modifies the database field, the database generated value is not reflected by the object.
 +
 +
Use caution when deciding on whether or not to use a <tt>ReturningPolicy</tt>, as doing so may effect insert or update performance and is not compatible with batch writing (see [[Optimizing%20the%20EclipseLink%20Application%20(ELUG)#How to Use Batch Writing for Optimization|How to Use Batch Writing for Optimization]]).
 +
 +
By default, you can use a <tt>ReturningPolicy</tt> with an Oracle Database, in which case, EclipseLink uses the Oracle <tt>RETURNING</tt> clause (see [[#How to Configure Returning Policy Using Workbench|Using Workbench]]).
 +
 +
You can use a <tt>ReturningPolicy</tt> with a non-Oracle database if you configure your descriptor's insert or update query to use a stored procedure that returns the desired returned values as output parameters (see [[#How to Configure Returning Policy Using Java|Using Java]]).
 +
 +
This table summarizes which descriptors support returning policy configuration.
 +
 +
 +
<span id="Table 115-29"></span>
 +
''''' Descriptor Support for Fetch Group Configuration'''''
 +
 +
{| class="RuleFormal" dir="ltr" title="Descriptor Support for Fetch Group Configuration" summary="This table summarizes which descriptors support Fetch Group Configuration" width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
 +
|- align="left" valign="top"
 +
! id="r1c1-t59" align="left" valign="bottom" | '''Descriptor'''
 +
! id="r1c2-t59" align="left" valign="bottom" | '''[[#How to Configure Returning Policy Using Workbench|Using Workbench]]<br>'''
 +
! id="r1c3-t59" align="left" valign="bottom" | '''[[#How to Configure Returning Policy Using Java|Using Java]]<br>'''
 +
|- align="left" valign="top"
 +
| id="r2c1-t59" headers="r1c1-t59" align="left" |
 +
Relational Descriptors
 +
| headers="r2c1-t59 r1c2-t59" align="left" |
 +
[[Image:support.gif|Supported.]]<br>
 +
| headers="r2c1-t59 r1c3-t59" align="left" |
 +
[[Image:support.gif|Supported.]]<br>
 +
|- align="left" valign="top"
 +
| id="r3c1-t59" headers="r1c1-t59" align="left" |
 +
Object-Relational Data Type Descriptors
 +
| headers="r3c1-t59 r1c2-t59" align="left" |
 +
[[Image:unsupport.gif|Unsupported]]<br>
 +
| headers="r3c1-t59 r1c3-t59" align="left" |
 +
[[Image:support.gif|Supported.]]<br>
 +
|- align="left" valign="top"
 +
| id="r4c1-t59" headers="r1c1-t59" align="left" |
 +
EIS Descriptors<sup> 1 </sup>
 +
| headers="r4c1-t59 r1c2-t59" align="left" |
 +
[[Image:support.gif|Supported.]]<br>
 +
| headers="r4c1-t59 r1c3-t59" align="left" |
 +
[[Image:support.gif|Supported.]]<br>
 +
|- align="left" valign="top"
 +
| id="r5c1-t59" headers="r1c1-t59" align="left" |
 +
XML Descriptors
 +
| headers="r5c1-t59 r1c2-t59" align="left" |
 +
[[Image:unsupport.gif|Unsupported]]<br>
 +
| headers="r5c1-t59 r1c3-t59" align="left" |
 +
[[Image:unsupport.gif|Unsupported]]<br>
 +
|}
 +
 +
<br><sup> 1 </sup>[[Creating%20an%20EIS%20Descriptor%20(ELUG)#EIS Root Descriptors|EIS Root Descriptors]] only.<br>
 +
 +
 +
 +
===How to Configure Returning Policy Using Workbench===
 +
To specify the return policy for a descriptor, use this procedure:
 +
 +
# Select a descriptor in the '''Navigator'''. Its properties appear in the Editor.If the '''Returning''' advanced property is not visible for the descriptor, right-click the descriptor and choose '''Select Advanced Properties''' > '''Returning''' from the context menu or from the '''Selected''' menu.
 +
# Click the '''Returning''' tab in the '''Editor'''.<br>'''''Returning Tab'''''<br>[[Image:rettab.gif|Returning Tab]]<br><br>
 +
# Complete the insert and update policies of the Returning tab.
 +
 +
Use the following information to enter data in each field on the tab:
 +
{| class="HRuleInformal" dir="ltr" title="This table identifies each field on the tab." summary="This table identifies each field on the tab." width="100%" border="1" frame="hsides" rules="rows" cellpadding="3" frame="hsides" rules="rows"
 +
|- align="left" valign="top"
 +
! id="r1c1-t60" align="left" valign="bottom" | '''Field'''
 +
! id="r1c2-t60" align="left" valign="bottom" | '''Description'''
 +
|- align="left" valign="top"
 +
| id="r2c1-t60" headers="r1c1-t60" align="left" | '''Insert'''
 +
| headers="r2c1-t60 r1c2-t60" align="left" | These options apply to insert operations:
 +
|- align="left" valign="top"
 +
| id="r3c1-t60" headers="r1c1-t60" align="left" | '''Name'''
 +
| headers="r3c1-t60 r1c2-t60" align="left" | Click '''Add''' to add a database field to this <tt>ReturningPolicy</tt> for insert operations.
 +
|- align="left" valign="top"
 +
| id="r4c1-t60" headers="r1c1-t60" align="left" | '''Return-only'''
 +
| headers="r4c1-t60 r1c2-t60" align="left" |
 +
When selected, EclipseLink only returns a value for this field; it will not include the field in the insert. When not selected, EclipseLink returns a value for this field and includes the value in the insert.
 +
|- align="left" valign="top"
 +
| id="r5c1-t60" headers="r1c1-t60" align="left" | '''Update'''
 +
| headers="r5c1-t60 r1c2-t60" align="left" | These options apply to update operations:
 +
|- align="left" valign="top"
 +
| id="r6c1-t60" headers="r1c1-t60" align="left" | '''Name'''
 +
| headers="r6c1-t60 r1c2-t60" align="left" | Click '''Add''' to add a database field to this <tt>ReturningPolicy</tt> for update operations
 +
|}
 +
 +
<br>
 +
 +
To remove a database field from the descriptor's <tt>ReturningPolicy</tt>, select the field in the '''Insert''' or '''Update''' window and click '''Remove'''.
 +
 +
<br>
 +
 +
{| class="Note oac_no_warn" width="80%" border="1" frame="hsides" rules="groups" cellpadding="3" frame="hsides" rules="groups"
 +
| align="left" |
 +
'''Note:''' If you are using Workbench, you cannot configure a returning policy for an attribute mapped with a transformation mapping (see [[Introduction%20to%20Relational%20Mappings%20(ELUG)#Transformation Mapping|Transformation Mapping]]).
 +
|}
 +
 +
 +
 +
 +
 +
===How to Configure Returning Policy Using Java===
 +
 +
You use a <tt>ReturningPolicy</tt> to configure how EclipseLink handles returning with the attributes of an object on a field-by-field basis. This table describes the <tt>ReturnPolicy</tt> methods you use to tell EclipseLink how to handle a particular database field. Each method takes a <tt>String</tt> or a <tt>DatabaseField</tt> type parameter as field name.
 +
 +
 +
<span id="Table 115-30"></span>
 +
''''' Return Policy Methods'''''
 +
 +
{| class="HRuleFormalMax" dir="ltr" title="Return Policy Methods" summary="This table describes the important methods of ReturnPolicy." width="100%" border="1" frame="hsides" rules="rows" cellpadding="3" frame="hsides" rules="rows"
 +
|- align="left" valign="top"
 +
! id="r1c1-t62" align="left" valign="bottom" | '''Method'''
 +
! id="r1c2-t62" align="left" valign="bottom" | '''Applies to SQL Statements of Type...'''
 +
! id="r1c3-t62" align="left" valign="bottom" | '''Writes Current Value of Field to Database?'''
 +
! id="r1c4-t62" align="left" valign="bottom" | '''Returns Database- Generated Result?'''
 +
|- align="left" valign="top"
 +
| id="r2c1-t62" headers="r1c1-t62" align="left" |
 +
<tt>addFieldForInsert</tt>
 +
| headers="r2c1-t62 r1c2-t62" align="left" |
 +
INSERT
 +
| headers="r2c1-t62 r1c3-t62" align="left" |
 +
Yes
 +
| headers="r2c1-t62 r1c4-t62" align="left" |
 +
Yes
 +
|- align="left" valign="top"
 +
| id="r3c1-t62" headers="r1c1-t62" align="left" |
 +
<tt>addFieldForInsertReturnOnly</tt>
 +
| headers="r3c1-t62 r1c2-t62" align="left" |
 +
INSERT
 +
| headers="r3c1-t62 r1c3-t62" align="left" |
 +
No
 +
| headers="r3c1-t62 r1c4-t62" align="left" |
 +
Yes
 +
|- align="left" valign="top"
 +
| id="r4c1-t62" headers="r1c1-t62" align="left" |
 +
<tt>addFieldForUpdate</tt>
 +
| headers="r4c1-t62 r1c2-t62" align="left" |
 +
UPDATE
 +
| headers="r4c1-t62 r1c3-t62" align="left" |
 +
Yes
 +
| headers="r4c1-t62 r1c4-t62" align="left" |
 +
Yes
 +
|}
 +
 +
<br>
 +
 +
You configure a descriptor with a <tt>ReturningPolicy</tt> using <tt>ClassDescriptor</tt> method <tt>setReturningPolicy</tt>.
 +
 +
==Configuring Instantiation Policy==
 +
 +
The EclipseLink runtime instantiates new instances of a class according to the instantiation policy you configure on the class's descriptor.
 +
 +
This table summarizes which descriptors support an instantiation policy.
 +
 +
 +
<span id="Table 115-31"></span>
 +
''''' Descriptor Support for Instantiation Policy'''''
 +
 +
{| class="RuleFormal" dir="ltr" title="Descriptor Support for Instantiation Policy" summary="This table summarizes which descriptors support instantiation policy." width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
 +
|- align="left" valign="top"
 +
! id="r1c1-t63" align="left" valign="bottom" | '''Descriptor'''
 +
! id="r1c2-t63" align="left" valign="bottom" | '''[[#How to Configure Instantiation Policy Using Workbench|Using Workbench]]<br>'''
 +
! id="r1c3-t63" align="left" valign="bottom" | '''[[#How to Configure Instantiation Policy Using Java|Using Java]]<br>'''
 +
|- align="left" valign="top"
 +
| id="r2c1-t63" headers="r1c1-t63" align="left" |
 +
Relational Descriptors
 +
| headers="r2c1-t63 r1c2-t63" align="left" |
 +
[[Image:support.gif|Supported.]]<br>
 +
| headers="r2c1-t63 r1c3-t63" align="left" |
 +
[[Image:support.gif|Supported.]]<br>
 +
|- align="left" valign="top"
 +
| id="r3c1-t63" headers="r1c1-t63" align="left" |
 +
Object-Relational Data Type Descriptors
 +
| headers="r3c1-t63 r1c2-t63" align="left" |
 +
[[Image:unsupport.gif|Unsupported.]]<br>
 +
| headers="r3c1-t63 r1c3-t63" align="left" |
 +
[[Image:support.gif|Supported.]]<br>
 +
|- align="left" valign="top"
 +
| id="r4c1-t63" headers="r1c1-t63" align="left" |
 +
EIS Descriptors
 +
| headers="r4c1-t63 r1c2-t63" align="left" |
 +
[[Image:support.gif|Supported.]]<br>
 +
| headers="r4c1-t63 r1c3-t63" align="left" |
 +
[[Image:support.gif|Supported.]]<br>
 +
|- align="left" valign="top"
 +
| id="r5c1-t63" headers="r1c1-t63" align="left" |
 +
XML Descriptors
 +
| headers="r5c1-t63 r1c2-t63" align="left" |
 +
[[Image:support.gif|Supported.]]<br>
 +
| headers="r5c1-t63 r1c3-t63" align="left" |
 +
[[Image:support.gif|Supported.]]<br>
 +
|}
 +
 +
<br>
 +
 +
You can specify one of the following types of instantiation policy:
 +
* Default: EclipseLink creates a new instance of a class by calling the class's default constructor.
 +
* Method: EclipseLink creates a new instance of a class by calling a public static method that you define on the class descriptor.
 +
* Factory: EclipseLink creates a new instance of a class by calling the appropriate methods on a separate class that you implement according to the Factory design pattern.
 +
 +
 +
 +
===How to Configure Instantiation Policy Using Workbench===
 +
To set the instantiation policy for a descriptor, use this procedure:
 +
 +
# In the '''Navigator''', select a descriptor.If the Instantiation advanced property is not visible for the descriptor, right-click the descriptor and choose '''Select Advanced Properties''' > '''Instantiation''' from the context menu or from the '''Selected''' menu.
 +
# Click the '''Instantiation''' tab.<br>''''' Instantiation Tab'''''<br>[[Image:instant.gif|Instantiation Tab]]<br><br>
 +
# Complete each field on the '''Instantiation''' tab.
 +
 +
Use the following information to enter data in each field on the tab:
 +
{| class="HRuleInformal" dir="ltr" title="This table defines each field on the Instantiation tab." summary="This table defines each field on the Instantiation tab." width="100%" border="1" frame="hsides" rules="rows" cellpadding="3" frame="hsides" rules="rows"
 +
|- align="left" valign="top"
 +
! id="r1c1-t64" align="left" valign="bottom" | '''Field'''
 +
! id="r1c2-t64" align="left" valign="bottom" | '''Description'''
 +
|- align="left" valign="top"
 +
| id="r2c1-t64" headers="r1c1-t64" align="left" | '''Use Default Constructor'''
 +
| headers="r2c1-t64 r1c2-t64" align="left" | Specify if the default constructor of the class instantiates a new instance.
 +
|- align="left" valign="top"
 +
| id="r3c1-t64" headers="r1c1-t64" align="left" | '''Use Method'''
 +
| headers="r3c1-t64 r1c2-t64" align="left" | Specify a method to execute to create objects from the database.
 +
|- align="left" valign="top"
 +
| id="r4c1-t64" headers="r1c1-t64" align="left" |
 +
: ''' Method'''
 +
| headers="r4c1-t64 r1c2-t64" align="left" | Select the name of a method to be executed to create objects from the database. The method must be a public, static method on the descriptor's class and must return a new instance of the object.
 +
|- align="left" valign="top"
 +
| id="r5c1-t64" headers="r1c1-t64" align="left" | '''Use Factory'''
 +
| headers="r5c1-t64 r1c2-t64" align="left" | Specify an object factory method.
 +
|- align="left" valign="top"
 +
| id="r6c1-t64" headers="r1c1-t64" align="left" | '''Factory Class'''
 +
| headers="r6c1-t64 r1c2-t64" align="left" | Select the class of the factory object that creates the new instances.
 +
|- align="left" valign="top"
 +
| id="r7c1-t64" headers="r1c1-t64" align="left" | '''Factory Method'''
 +
| headers="r7c1-t64 r1c2-t64" align="left" | Select the method to be used to obtain a factory object. Choose <tt><nothing></tt> to use the default constructor.
 +
|- align="left" valign="top"
 +
| id="r8c1-t64" headers="r1c1-t64" align="left" | '''Instantiation Method'''
 +
| headers="r8c1-t64 r1c2-t64" align="left" | Select the method to be called on the factory object to obtain a new instance that will be populated with data from the data source.
 +
|}
 +
 +
<br>
 +
 +
===How to Configure Instantiation Policy Using Java===
 +
Use one of the following <tt>ClassDescriptor</tt> methods to set the appropriate type of instantiation policy:
 +
* <tt>useDefaultConstructorInstantiationPolicy</tt>
 +
* <tt>useMethodInstantiationPolicy</tt>
 +
* <tt>useFactoryInstantiationPolicy</tt>
 +
 +
 +
 +
==Configuring Copy Policy==
 +
The EclipseLink unit of work feature must be able to produce an exact copy (clone) persistent objects. This table summarizes which descriptors support a copy policy.
 +
 +
 +
<span id="Table 115-32"></span>
 +
 +
{| class="RuleFormal" dir="ltr" title="Configuring Descriptors with a Copy Policy" summary="This table summarizes which descriptors support copy policy." width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
 +
|- align="left" valign="top"
 +
! id="r1c1-t65" align="left" valign="bottom" | '''Descriptor'''
 +
! id="r1c2-t65" align="left" valign="bottom" | '''[[#How to Configure Copy Policy Using Workbench|Using the Workbench]]<br>'''
 +
! id="r1c3-t65" align="left" valign="bottom" | '''[[#How to Configure Copy Policy Using Java|Using Java]]<br>'''
 +
|- align="left" valign="top"
 +
| id="r2c1-t65" headers="r1c1-t65" align="left" |
 +
Relational Descriptors
 +
| headers="r2c1-t65 r1c2-t65" align="left" |
 +
[[Image:support.gif|Supported.]]<br>
 +
| headers="r2c1-t65 r1c3-t65" align="left" |
 +
[[Image:support.gif|Supported.]]<br>
 +
|- align="left" valign="top"
 +
| id="r3c1-t65" headers="r1c1-t65" align="left" |
 +
Object-Relational Data Type Descriptors
 +
| headers="r3c1-t65 r1c2-t65" align="left" |
 +
[[Image:unsupport.gif|Unsupported.]]<br>
 +
| headers="r3c1-t65 r1c3-t65" align="left" |
 +
[[Image:support.gif|Supported.]]<br>
 +
|- align="left" valign="top"
 +
| id="r4c1-t65" headers="r1c1-t65" align="left" |
 +
EIS Descriptors
 +
| headers="r4c1-t65 r1c2-t65" align="left" |
 +
[[Image:support.gif|Supported.]]<br>
 +
| headers="r4c1-t65 r1c3-t65" align="left" |
 +
[[Image:support.gif|Supported.]]<br>
 +
|- align="left" valign="top"
 +
| id="r5c1-t65" headers="r1c1-t65" align="left" |
 +
XML Descriptors
 +
| headers="r5c1-t65 r1c2-t65" align="left" |
 +
[[Image:support.gif|Supported.]]<br>
 +
| headers="r5c1-t65 r1c3-t65" align="left" |
 +
[[Image:support.gif|Supported.]]<br>
 +
|}
 +
 +
<br>
 +
 +
EclipseLink supports the following two ways of copying objects:
 +
* Instantiation policy: By default, EclipseLink creates a new copy of an object by using the currently configured instantiation policy (see [[#Configuring Instantiation Policy|Configuring Instantiation Policy]]).
 +
* Method: EclipseLink creates a new copy of an object by calling a method on the object that you specify. For example, you can specify the object's <tt>clone</tt> method (or any other appropriate method on the object). Note that the clone method should return a shallow clone of the object.
 +
 +
 +
 +
===How to Configure Copy Policy Using Workbench===
 +
To specify the copy policy for a descriptor, use this procedure:
 +
# Select a descriptor in the '''Navigator'''. Its properties appear in the Editor.If the '''Copying''' advanced property is not visible for the descriptor, right-click the descriptor and choose '''Select Advanced Properties''' > '''Copying''' from the context menu or from the '''Selected''' menu.
 +
# Click the '''Copying''' tab in the '''Editor'''.<br>''''' Copying Tab'''''<br>[[Image:copying.gif|Copying Tab]]<br><br>
 +
# Complete each field on the Copying tab.
 +
 +
Use the following information to enter data in each field on the tab:
 +
{| class="HRuleInformal" dir="ltr" title="This table defines each field on the Copying tab." summary="This table defines each field on the Copying tab." width="100%" border="1" frame="hsides" rules="rows" cellpadding="3" frame="hsides" rules="rows"
 +
|- align="left" valign="top"
 +
! id="r1c1-t66" align="left" valign="bottom" | '''Field'''
 +
! id="r1c2-t66" align="left" valign="bottom" | '''Description'''
 +
|- align="left" valign="top"
 +
| id="r2c1-t66" headers="r1c1-t66" align="left" | '''Use Instantiation Policy'''
 +
| headers="r2c1-t66 r1c2-t66" align="left" |
 +
Creates a new instance of the object using the descriptor's instantiation policy (see [[#Configuring Instantiation Policy|Configuring Instantiation Policy]]).
 +
|- align="left" valign="top"
 +
| id="r3c1-t66" headers="r1c1-t66" align="left" | '''Use Clone Method'''
 +
| headers="r3c1-t66 r1c2-t66" align="left" | Specifies whether or not to call the <tt>clone</tt> method of the object. Select a method from the list.
 +
|}
 +
 +
 +
 +
===How to Configure Copy Policy Using Java===
 +
Use one of the following <tt>ClassDescriptor</tt> methods to set the appropriate type of copy policy:
 +
* <tt>useCloneCopyPolicy()</tt><nowiki>: the object must provide a </nowiki><tt>clone</tt> method
 +
* <tt>useCloneCopyPolicy(java.lang.String cloneMethodName)</tt>
 +
* <tt>useInstantiationCopyPolicy()</tt>
 +
 +
 +
 +
==Configuring Change Policy==
 +
Use a change policy to specify how EclipseLink should track changes made to objects after you register them with a unit of work. This table summarizes which descriptors support a change policy.
 +
 +
 +
<span id="Table 115-33"></span>
 +
 +
{| class="RuleFormalWideMax" dir="ltr" title="Descriptor Support for Change Policy" summary="This table summarizes which descriptors support for change policy." width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
 +
|- align="left" valign="top"
 +
! id="r1c1-t67" align="left" valign="bottom" | '''Descriptor'''
 +
! id="r1c2-t67" align="left" valign="bottom" | '''[[Introduction%20to%20EclipseLink%20Transactions (ELUG)#Deferred Change Detection Policy|Deferred Change Detection Policy]]<br>'''
 +
! id="r1c3-t67" align="left" valign="bottom" | '''[[Introduction%20to%20EclipseLink%20Transactions (ELUG)#Object-Level Change Tracking Policy|Object-Level Change Tracking Policy]]<br>'''
 +
! id="r1c4-t67" align="left" valign="bottom" | '''[[Introduction%20to%20EclipseLink%20Transactions (ELUG)#Attribute Change Tracking Policy|Attribute Change Tracking Policy]]<br>'''
 +
! id="r1c5-t67" align="left" valign="bottom" | '''Using the Workbench'''
 +
! id="r1c6-t67" align="left" valign="bottom" | '''[[#How to Configure Change Policy Using Java|Using Java]]<br>'''
 +
|- align="left" valign="top"
 +
| id="r2c1-t67" headers="r1c1-t67" align="left" |
 +
Relational Descriptors<sup> 1 </sup>
 +
| headers="r2c1-t67 r1c2-t67" align="left" |
 +
[[Image:support.gif|Supported.]]<br>
 +
| headers="r2c1-t67 r1c3-t67" align="left" |
 +
[[Image:support.gif|Supported.]]<br>
 +
| headers="r2c1-t67 r1c4-t67" align="left" |
 +
[[Image:support.gif|Supported.]]<br>
 +
| headers="r2c1-t67 r1c5-t67" align="left" |
 +
[[Image:unsupport.gif|Unsupported]]<br>
 +
| headers="r2c1-t67 r1c6-t67" align="left" |
 +
[[Image:support.gif|Supported.]]<br>
 +
|- align="left" valign="top"
 +
| id="r3c1-t67" headers="r1c1-t67" align="left" |
 +
Object-Relational Data Type Descriptors
 +
| headers="r3c1-t67 r1c2-t67" align="left" |
 +
[[Image:support.gif|Supported.]]<br>
 +
| headers="r3c1-t67 r1c3-t67" align="left" |
 +
[[Image:support.gif|Supported.]]<br>
 +
| headers="r3c1-t67 r1c4-t67" align="left" |
 +
[[Image:support.gif|Supported.]]<br>
 +
| headers="r3c1-t67 r1c5-t67" align="left" |
 +
[[Image:unsupport.gif|Unsupported]]<br>
 +
| headers="r3c1-t67 r1c6-t67" align="left" |
 +
[[Image:support.gif|Supported.]]<br>
 +
|- align="left" valign="top"
 +
| id="r4c1-t67" headers="r1c1-t67" align="left" |
 +
EIS Descriptors <sup> 2 </sup>
 +
| headers="r4c1-t67 r1c2-t67" align="left" |
 +
[[Image:support.gif|Supported.]]<br>
 +
| headers="r4c1-t67 r1c3-t67" align="left" |
 +
[[Image:support.gif|Supported.]]<br>
 +
| headers="r4c1-t67 r1c4-t67" align="left" |
 +
[[Image:support.gif|Supported.]]<br>
 +
| headers="r4c1-t67 r1c5-t67" align="left" |
 +
[[Image:unsupport.gif|Unsupported]]<br>
 +
| headers="r4c1-t67 r1c6-t67" align="left" |
 +
[[Image:support.gif|Supported.]]<br>
 +
|- align="left" valign="top"
 +
| id="r5c1-t67" headers="r1c1-t67" align="left" |
 +
XML Descriptors
 +
| headers="r5c1-t67 r1c2-t67" align="left" |
 +
[[Image:unsupport.gif|Unsupported]]<br>
 +
| headers="r5c1-t67 r1c3-t67" align="left" |
 +
[[Image:unsupport.gif|Unsupported]]<br>
 +
| headers="r5c1-t67 r1c4-t67" align="left" |
 +
[[Image:unsupport.gif|Unsupported]]<br>
 +
| headers="r5c1-t67 r1c5-t67" align="left" |
 +
[[Image:unsupport.gif|Unsupported]]<br>
 +
| headers="r5c1-t67 r1c6-t67" align="left" |
 +
[[Image:unsupport.gif|Unsupported]]<br>
 +
|}
 +
 +
<br><sup> 1 </sup>[[Creating%20a%20Relational%20Descriptor%20(ELUG)#Creating Relational Class Descriptors|Relational Class Descriptors]] only.<br><sup> 2 </sup>[[Creating%20an%20EIS%20Descriptor%20(ELUG)#EIS Root Descriptors|EIS Root Descriptors]] only.<br>
 +
 +
By default, EclipseLink uses the deferred change detection policy.
 +
 +
For JPA entities or POJO classes that you configure for weaving, EclipseLink weaves value holder indirection for one-to-one mappings. If you want EclipseLink to weave change tracking and your application includes collection mappings (one-to-many or many-to-many), then you must configure all collection mappings to use transparent indirect container indirection only (you may not configure your collection mappings to use eager loading nor value holder indirection).
 +
 +
Mutable basic mappings affect the overhead of change tracking. EclipseLink can only weave an attribute change tracking policy for immutable mappings.
 +
 +
EclipseLink logs a warning message at the <tt>CONFIG</tt> log level if you try to weave a descriptor that does not support change policy.
 +
 +
EclipseLink supports alternative change policies (policies other than <tt>DeferredChangeDetectionPolicy</tt>) for attributes that use a subset of the mappings that EclipseLink supports.
 +
 +
For JPA applications deployed to OC4J EclipseLink automatically uses the attribute change tracking policy.
 +
 +
For more information, see the following:
 +
* [[Introduction%20to%20EclipseLink%20Transactions (ELUG)#Unit of Work and Change Policy|Unit of Work and Change Policy]]
 +
* [[Introduction%20to%20EclipseLink%20Transactions (ELUG)#Change Policy Mapping Support|Change Policy Mapping Support]]
 +
* [[Introduction to EclipseLink%20Application%20Development%20(ELUG)#Using Weaving|Using Weaving]]
 +
* [[Using%20EclipseLink%20JPA%20Extensions%20(ELUG)#Using EclipseLink JPA Weaving|Using EclipseLink JPA Weaving]]
 +
* [[Introduction to EclipseLink%20Application%20Development%20(ELUG)#Using Method and Direct Field Access|Using Method and Direct Field Access]]
 +
* [[Introduction to EclipseLink%20Application%20Development%20(ELUG)#Mutability|Mutability]]
 +
 +
 +
 +
===How to Configure Change Policy Using Java===
 +
This section describes how to configure a descriptor with a change policy using Java, and how to implement persistent classes for those change policies that are intrusive. It includes information on configuring the following:
 +
* [[#Configuring Deferred Change Detection Policy|Configuring Deferred Change Detection Policy]]
 +
* [[#Configuring Object Change Tracking Policy|Configuring Object Change Tracking Policy]]
 +
* [[#Configuring Attribute Change Tracking Policy|Configuring Attribute Change Tracking Policy]]
 +
 +
 +
 +
====Configuring Deferred Change Detection Policy====
 +
The <tt>DeferredChangeDetectionPolicy</tt> provides good unit of work commit performance for a wide range of object change characteristics. It is the default change policy. For more information, see [[Introduction%20to%20EclipseLink%20Transactions (ELUG)#Deferred Change Detection Policy|Deferred Change Detection Policy]]).
 +
 +
Because it is the default, you do not need to explicitly configure this policy.
 +
 +
To configure EclipseLink to use a <tt>DeferredChangeDetectionPolicy</tt>, create a descriptor amendment method (see [[#Configuring Amendment Methods|Configuring Amendment Methods]]) that sets the change policy, as the [[#Example 115-21|Setting the ObjectChangeTrackingPolicy]] example illustrates.
 +
 +
 +
 +
====Configuring Object Change Tracking Policy====
 +
The <tt>ObjectChangeTrackingPolicy</tt> provides improved unit of work commit performance for objects with few attributes, or with many attributes and many changed attributes. For more information, see [[Introduction%20to%20EclipseLink%20Transactions (ELUG)#Object-Level Change Tracking Policy|Object-Level Change Tracking Policy]].
 +
 +
For JPA applications deployed to an application server, for which EclipseLink provides integration (see [[Integrating%20EclipseLink%20with%20an%20Application%20Server (ELUG)#Introduction to the Application Server Support|Introduction to the Application Server Support]]), when you configure an entity’s descriptor with an <tt>ObjectLevelChangeTrackingPolicy</tt>, EclipseLink automatically generates code of a concrete subclass to implement the EclipseLink <tt>ChangeTracker</tt> interface at deploy time. Configuring the <tt>ObjectLevelChangeTrackingPolicy</tt> prevents EclipseLink from automatically applying an <tt>AttributeChangeTrackingPolicy</tt> (see [[#Configuring Attribute Change Tracking Policy|Configuring Attribute Change Tracking Policy]]).
 +
 +
To configure EclipseLink to use an <tt>ObjectChangeTrackingPolicy</tt>, use this procedure:
 +
<ol>
 +
<li>Create a descriptor amendment method (see [[#Configuring Amendment Methods|Configuring Amendment Methods]]) that sets the change policy, as this example illustrates:<br>
 +
 +
<span id="Example 115-21"></span>
 +
''''' Setting the ObjectChangeTrackingPolicy'''''
 +
<div class="pre">
 +
descriptor.setObjectChangePolicy(new ObjectChangeTrackingPolicy());
 +
</div>
 +
</li>
 +
<li> For plain Java objects, code each of your persistent classes to implement the <tt>ChangeTracker</tt> interface, as this example illustrates:<br>
 +
 +
<span id="Example 115-22"></span>
 +
''''' Implementing the ChangeTracker Interface for the ObjectChangeTrackingPolicy'''''
 +
<div class="pre">
 +
public class Employee implements ChangeTracker {
 +
 +
    PropertyChangeListener listener;
 +
    String firstName;
 +
 +
    public PropertyChangeListener getEclipseLinkPropertyChangeListener() {
 +
      return this.listener;
 +
    }
 +
 +
    public void setEclipseLinkPropertyChangeListener(PropertyChangeListener listener) {
 +
      this.listener = listener;
 +
    }
 +
    ...
 +
    public void setFirstName(String firstName) {
 +
      propertyChange("firstName", getFirstName(), firstName);
 +
      this.firstName = firstName;
 +
    }
 +
    ...
 +
    public void propertyChange(String propertyName, Object oldValue, Object newValue) {
 +
        if (listener != null) {
 +
            if (oldValue != newValue) {
 +
                listener.propertyChange(
 +
                    new PropertyChangeEvent(this, propertyName, oldValue, newValue));
 +
            }
 +
        }
 +
    }
 +
}
 +
</div>
 +
</li>
 +
</ol>
 +
 +
 +
 +
====Configuring Attribute Change Tracking Policy====
 +
The <tt>AttributeChangeTrackingPolicy</tt> provides improved unit of work commit performance for objects with many attributes and few changed attributes. In general, this is the most efficient change policy. It is the default change policy for JPA applications. For more information, see [[Introduction%20to%20EclipseLink%20Transactions (ELUG)#Attribute Change Tracking Policy|Attribute Change Tracking Policy]]).
 +
 +
 +
{| class="Note oac_no_warn" width="80%" border="1" frame="hsides" rules="groups" cellpadding="3" frame="hsides" rules="groups"
 +
| align="left" |
 +
'''Note:''' You cannot use the <tt>AttributeChangeTrackingPolicy</tt> if you are using any instance of <tt>FieldsLockingPolicy</tt> (see [[Introduction%20to%20Descriptors%20(ELUG)#Optimistic Field Locking Policies|Optimistic Field Locking Policies]]).
 +
|}
 +
 +
 +
When you deploy an EclipseLink-enabled JPA application, EclipseLink automatically configures your persistent classes to use the <tt>AttributeChangeTrackingPolicy</tt> and, using bytecode weaving, configures your persistence classes to implement the EclipseLink <tt>ChangeTracker</tt> interface. In this case, you do not need to explicitly configure this change policy.
 +
 +
To configure EclipseLink to use an <tt>AttributeChangeTrackingPolicy</tt> for plain Java objects or other application servers, use this procedure:
 +
 +
<ol>
 +
<li> Create a descriptor amendment method (see [[#Configuring Amendment Methods|Configuring Amendment Methods]]) that sets the change policy, as this example illustrates:<br>
 +
 +
<span id="Example 115-23"></span>
 +
''''' Setting the DeferredChangeDetectionPolicy'''''
 +
<div class="pre">
 +
descriptor.setObjectChangePolicy(new AttributeChangeTrackingPolicy());
 +
</div></li>
 +
<li> Code each of your persistent classes to implement the <tt>ChangeTracker</tt> interface, as this example illustrates:<br>
 +
 +
<span id="Example 115-24"></span>
 +
 +
''''' Implementing the ChangeTracker Interface for the AttributeChangeTrackingPolicy'''''
 +
<div class="pre">
 +
public class Employee implements ChangeTracker {
 +
 +
    PropertyChangeListener listener;
 +
    String firstName;
 +
 +
    public PropertyChangeListener getEclipseLink PropertyChangeListener() {
 +
      return this.listener;
 +
    }
 +
 +
    public void setEclipseLinkPropertyChangeListener(PropertyChangeListener listener) {
 +
      this.listener = listener;
 +
    }
 +
    ...
 +
    public void setFirstName(String firstName) {
 +
      propertyChange("firstName", getFirstName(), firstName);
 +
      this.firstName = firstName;
 +
    }
 +
    ...
 +
    public void propertyChange(String propertyName, Object oldValue, Object newValue) {
 +
        if (listener != null) {
 +
            if (oldValue != newValue) {
 +
                listener.propertyChange(
 +
                    new PropertyChangeEvent(this, propertyName, oldValue, newValue));
 +
            }
 +
        }
 +
    }
 +
}
 +
</div>
 +
</li>
 +
</ol>
 +
 +
 +
 +
==Configuring a History Policy==
 +
If you want to use historical sessions (see [[Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Historical Sessions|Historical Sessions]]) to execute historical queries (see [[Introduction%20to%20EclipseLink%20Queries%20(ELUG)#Historical Queries|Historical Queries]]) against a historical schema of your own design, configure your descriptors with an EclipseLink <tt>HistoryPolicy</tt> that describes your historical schema.
 +
 +
If you are using an Oracle Database platform for Oracle9''i'' Database Server (or later), you can query the historical versions of objects automatically maintained by the Oracle Database without the need for a history policy. For more information, see [[Configuring%20Historical%20Sessions%20(ELUG)#How to Configure Historical Sessions Using an Oracle Platform|How to Configure Historical Sessions Using an Oracle Platform]].
 +
 +
This table summarizes which descriptors support history policy configuration.
 +
 +
 +
<span id="Table 115-34"></span>
 +
{| class="RuleFormal" dir="ltr" title="Descriptor Support for History Policy Configuration" summary="This table summarizes which descriptors support history policy configuration." width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
 +
|- align="left" valign="top"
 +
! id="r1c1-t69" align="left" valign="bottom" | '''Descriptor'''
 +
! id="r1c2-t69" align="left" valign="bottom" | '''How to Use Workbench'''
 +
! id="r1c3-t69" align="left" valign="bottom" | '''[[#How to Configure a History Policy Using Java|Using Java]]<br>'''
 +
|- align="left" valign="top"
 +
| id="r2c1-t69" headers="r1c1-t69" align="left" |
 +
Relational Descriptors
 +
| headers="r2c1-t69 r1c2-t69" align="left" |
 +
[[Image:unsupport.gif|Unsupported]]<br>
 +
| headers="r2c1-t69 r1c3-t69" align="left" |
 +
[[Image:support.gif|Supported.]]<br>
 +
|- align="left" valign="top"
 +
| id="r3c1-t69" headers="r1c1-t69" align="left" |
 +
Object-Relational Data Type Descriptors
 +
| headers="r3c1-t69 r1c2-t69" align="left" |
 +
[[Image:unsupport.gif|Unsupported]]<br>
 +
| headers="r3c1-t69 r1c3-t69" align="left" |
 +
[[Image:support.gif|Supported.]]<br>
 +
|- align="left" valign="top"
 +
| id="r4c1-t69" headers="r1c1-t69" align="left" |
 +
EIS Descriptors
 +
| headers="r4c1-t69 r1c2-t69" align="left" |
 +
[[Image:unsupport.gif|Unsupported]]<br>
 +
| headers="r4c1-t69 r1c3-t69" align="left" |
 +
[[Image:unsupport.gif|Unsupported]]<br>
 +
|- align="left" valign="top"
 +
| id="r5c1-t69" headers="r1c1-t69" align="left" |
 +
XML Descriptors
 +
| headers="r5c1-t69 r1c2-t69" align="left" |
 +
[[Image:unsupport.gif|Unsupported]]<br>
 +
| headers="r5c1-t69 r1c3-t69" align="left" |
 +
[[Image:unsupport.gif|Unsupported]]<br>
 +
|}
 +
 +
<br>
 +
 +
There are many ways to configure a historical database schema. EclipseLink supports several historical schema configurations that you can describe with a <tt>HistoryPolicy</tt> (see [[Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Historical Session Limitations|Historical Session Limitations]]).
 +
 +
 +
'''Example Historical Schema'''
 +
 +
As shown in the [[#Table 115-35|Example Table for EMPLOYEE]] and [[#Table 115-36|Example History Table EMPLOYEE_HIST]], a common approach is to define a special history table to store past versions of an object: one history table for each regular table that requires historical persistence. The history table typically has the same fields as the corresponding regular table plus fields (such as row start and end) used to define an interval that represents the life time of a particular version.
 +
 +
{| class="Note oac_no_warn" width="80%" border="1" frame="hsides" rules="groups" cellpadding="3" frame="hsides" rules="groups"
 +
| align="left" |
 +
'''Note:''' EclipseLink assumes that the current version of an object corresponds to the historical table row whose row end field is <tt>NULL</tt>.
 +
|}
 +
 +
 +
 +
EclipseLink will include the history tables described by a <tt>HistoryPolicy</tt> when you execute a historical query.
 +
 +
This table shows the schema for an <tt>EMPLOYEE</tt> table. The table currently contains one <tt>EMPLOYEE</tt> instance.
 +
 +
 +
<span id="Table 115-35"></span>
 +
''''' Example Table for EMPLOYEE'''''
 +
 +
{| class="Formal" dir="ltr" title="Example Table for EMPLOYEE" summary="This table represents a database table for an EMPLOYEE class" width="100%" border="1" frame="hsides" rules="groups" cellpadding="3" frame="hsides" rules="groups"
 +
|- align="left" valign="top"
 +
! id="r1c1-t71" align="left" valign="bottom" | '''EMP_ID'''
 +
! id="r1c2-t71" align="left" valign="bottom" | '''F_NAME'''
 +
! id="r1c3-t71" align="left" valign="bottom" | '''L_NAME'''
 +
! id="r1c4-t71" align="left" valign="bottom" | '''SALARY'''
 +
|- align="left" valign="top"
 +
| id="r2c1-t71" headers="r1c1-t71" align="left" |
 +
1
 +
| headers="r2c1-t71 r1c2-t71" align="left" |
 +
Jane
 +
| headers="r2c1-t71 r1c3-t71" align="left" |
 +
Doe
 +
| headers="r2c1-t71 r1c4-t71" align="left" |
 +
55000
 +
|}
 +
 +
<br>
 +
 +
This table shows one possible history table <tt>EMPLOYEE_HIST</tt> that stores historical versions of employees. The table contains the current <tt>EMPLOYEE</tt> (the version with a <tt>ROW_END</tt> value of <tt>NULL</tt>) and one historical version.
 +
 +
 +
<span id="Table 115-36"></span>
 +
''''' Example History Table EMPLOYEE_HIST'''''
 +
 +
{| class="HRuleFormal" dir="ltr" title="Example History Table EMPLOYEE_HIST" summary="This table represents a table used to store historical versions of EMPLOYEE objects." width="100%" border="1" frame="hsides" rules="rows" cellpadding="3" frame="hsides" rules="rows"
 +
|- align="left" valign="top"
 +
! id="r1c1-t72" align="left" valign="bottom" | '''EMP_ID'''
 +
! id="r1c2-t72" align="left" valign="bottom" | '''F_NAME'''
 +
! id="r1c3-t72" align="left" valign="bottom" | '''L_NAME'''
 +
! id="r1c4-t72" align="left" valign="bottom" | '''SALARY'''
 +
! id="r1c5-t72" align="left" valign="bottom" | '''ROW_START'''
 +
! id="r1c6-t72" align="left" valign="bottom" | '''ROW_END'''
 +
|- align="left" valign="top"
 +
| id="r2c1-t72" headers="r1c1-t72" align="left" |
 +
1
 +
| headers="r2c1-t72 r1c2-t72" align="left" |
 +
Jane
 +
| headers="r2c1-t72 r1c3-t72" align="left" |
 +
Doe
 +
| headers="r2c1-t72 r1c4-t72" align="left" |
 +
50000
 +
| headers="r2c1-t72 r1c5-t72" align="left" |
 +
29/08/2004
 +
| headers="r2c1-t72 r1c6-t72" align="left" |
 +
31/08/2004
 +
|- align="left" valign="top"
 +
| id="r3c1-t72" headers="r1c1-t72" align="left" |
 +
1
 +
| headers="r3c1-t72 r1c2-t72" align="left" |
 +
Jane
 +
| headers="r3c1-t72 r1c3-t72" align="left" |
 +
Doe
 +
| headers="r3c1-t72 r1c4-t72" align="left" |
 +
55000
 +
| headers="r3c1-t72 r1c5-t72" align="left" |
 +
31/08/2004
 +
| headers="r3c1-t72 r1c6-t72" align="left" |
 +
NULL
 +
|}
 +
 +
<br>
 +
 +
Because every record has a start and end interval, the history table can store multiple versions of the same object (with the same primary key). The unique identifier of a particular version is given by the existing primary key, plus the value of the start field. For example, in [[#Table 115-36|Example History Table EMPLOYEE_HIST]], the unique identifier of the current version is given by <tt>(EMP_ID, START) = (1, 31/08/2004)</tt>.
 +
 +
 +
 +
===How to Configure a History Policy Using Java===
 +
This example shows how to describe the schema shown in [[#Table 115-35|Example Table for EMPLOYEE]] and [[#Table 115-36|Example History Table EMPLOYEE_HIST]] using the EclipseLink <tt>HistoryPolicy</tt><nowiki>:</nowiki>
 +
 +
 +
<span id="Example 115-25"></span>
 +
''''' HistoryPolicy for One Table'''''
 +
HistoryPolicy policy = new HistoryPolicy();
 +
policy.addStartFieldName("ROW_START");
 +
policy.addEndFieldName("ROW_END");
 +
policy.addHistoryTableName("EMPLOYEE", "EMPLOYEE_HIST");
 +
 +
'''// Assuming database triggers or stored procedures update history tables'''
 +
policy.setShouldHandleWrites(false);
 +
 +
employeeDescriptor.setHistoryPolicy(policy);
 +
 +
 +
 +
You can specify more than one table with a <tt>HistoryPolicy</tt> as shown in this examle. In this example, all history tables have a start field named <tt>ROW_START</tt> but the <tt>EMPLOYEE_HIST</tt> and <tt>SALARY_HIST</tt> tables have different end fields. To avoid ambiguity, the end field names are prefixed with their respective history table names.
 +
 +
<br>
 +
 +
<span id="Example 115-26"></span>
 +
''''' HistoryPolicy for Multiple Tables'''''
 +
HistoryPolicy policy = new HistoryPolicy();
 +
policy.addStartFieldName("ROW_START");
 +
policy.addEndFieldName("EMPLOYEE_HIST.ROW_END");
 +
policy.addEndFieldName("SALARY_HIST.VALID_UNTIL");
 +
policy.addHistoryTableName("EMPLOYEE", "EMPLOYEE_HIST");
 +
policy.addHistoryTableName("SALARY", "SALARY_HIST");
 +
'''// Assuming database triggers or stored procedures update history tables'''
 +
policy.setShouldHandleWrites(false);
 +
 +
employeeDescriptor.setHistoryPolicy(policy);
 +
 +
 +
 +
====Configuring Write Responsibility====
 +
Use <tt>HistoryPolicy</tt> method <tt>setShouldHandleWrites</tt> to specify whether or not EclipseLink is responsible for writing data to history tables. By default, <tt>setShouldHandleWrites</tt> is set to <tt>true</tt>.
 +
 +
Either the database or EclipseLink can be responsible for writing data to the history tables.
 +
 +
You can configure the database to write data to history tables by way of triggers or stored procedures that customize create, insert, and delete operations to modify both the regular table and the history table appropriately.
 +
 +
 +
 +
==Configuring Wrapper Policy==
 +
EclipseLink lets you use wrappers (or proxies) in cases where the persistent class is not the same class that is to be presented to users.
 +
 +
For example, in the EJB specification prior to 3.0, the entity bean class (the class that implements <tt>javax.ejb.EntityBean</tt>) is persistent, but is hidden from users who interact with a class that implements <tt>javax.ejb.EJBObject</tt> (local or remote interface class). In this example, the <tt>EJBObject</tt> acts as a proxy (or wrapper) for the <tt>EntityBean</tt>.
 +
 +
In cases where such a wrapper is used, EclipseLink continues to make the class specified in the descriptor persistent, but returns the appropriate instance of the wrapper whenever a persistent object is requested.
 +
 +
This table summarizes which descriptors support a wrapper policy.
 +
 +
 +
<span id="Table 115-37"></span>
 +
'''''Descriptor Support for Wrapper Policy'''''
 +
 +
{| class="RuleFormal" dir="ltr" title="Descriptor Support for Wrapper Policy" summary="This table summarizes which descriptors support wrapper policy." width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
 +
|- align="left" valign="top"
 +
! id="r1c1-t73" align="left" valign="bottom" | '''Descriptor'''
 +
! id="r1c2-t73" align="left" valign="bottom" | '''How to Use Workbench'''
 +
! id="r1c3-t73" align="left" valign="bottom" | '''[[#How to Configure Wrapper Policy Using Java|Using Java]]<br>'''
 +
|- align="left" valign="top"
 +
| id="r2c1-t73" headers="r1c1-t73" align="left" |
 +
Relational Descriptors
 +
| headers="r2c1-t73 r1c2-t73" align="left" |
 +
[[Image:unsupport.gif|Unsupported]]<br>
 +
| headers="r2c1-t73 r1c3-t73" align="left" |
 +
[[Image:support.gif|Supported.]]<br>
 +
|- align="left" valign="top"
 +
| id="r3c1-t73" headers="r1c1-t73" align="left" |
 +
Object-Relational Data Type Descriptors
 +
| headers="r3c1-t73 r1c2-t73" align="left" |
 +
[[Image:unsupport.gif|Unsupported]]<br>
 +
| headers="r3c1-t73 r1c3-t73" align="left" |
 +
[[Image:support.gif|Supported.]]<br>
 +
|- align="left" valign="top"
 +
| id="r4c1-t73" headers="r1c1-t73" align="left" |
 +
EIS Descriptors
 +
| headers="r4c1-t73 r1c2-t73" align="left" |
 +
[[Image:unsupport.gif|Unsupported]]<br>
 +
| headers="r4c1-t73 r1c3-t73" align="left" |
 +
[[Image:support.gif|Supported.]]<br>
 +
|- align="left" valign="top"
 +
| id="r5c1-t73" headers="r1c1-t73" align="left" |
 +
XML Descriptors
 +
| headers="r5c1-t73 r1c2-t73" align="left" |
 +
[[Image:unsupport.gif|Unsupported]]<br>
 +
| headers="r5c1-t73 r1c3-t73" align="left" |
 +
[[Image:unsupport.gif|Unsupported]]<br>
 +
|}
 +
 +
<br>
 +
 +
Use a wrapper policy to tell EclipseLink how to create wrappers for a particular persistent class, and how to obtain the underlying persistent object from a given wrapper instance.
 +
 +
If you specify a wrapper policy, EclipseLink uses the policy to ''wrap'' and ''unwrap'' persistent objects as required:
 +
* Wrapper policies implement the interface <tt>org.eclipse.persistence.descriptors.WrapperPolicy</tt>.
 +
* A wrapper policy is specified by setting the wrapper policy for the EclipseLink descriptor.
 +
* By default, no wrapper policy is used (the wrapper policy for a descriptor is null by default).
 +
 +
<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>  Wrapper policies are advanced EclipseLink options. Using a wrapper policy may not be compatible with some Workbench features.
 +
|}
 +
 +
<br>
 +
 +
Wrapper policies cannot be set using the Workbench and can be set only using Java code (see [[#How to Configure Wrapper Policy Using Java|Using Java]]).
 +
 +
 +
 +
===How to Configure Wrapper Policy Using Java===
 +
Use the <tt>ClassDescriptor</tt> method <tt>setWrapperPolicy</tt> to set the appropriate instance of <tt>WrapperPolicy</tt>.
 +
 +
 +
 +
==Configuring Fetch Groups==
 +
By default, when you execute an object-level read query for a particular object class, EclipseLink returns all the persistent attributes mapped in the object's descriptor. With this single query, all the object's persistent attributes are defined, and calling their <tt>get</tt> methods returns the value directly from the object.
 +
 +
When you are interested in only some of the attributes of an object, it may be more efficient to return only a subset of the object's attributes using a fetch group.
 +
 +
Using a fetch group, you can define a subset of an object's attributes and associate the fetch group with either a <tt>ReadObjectQuery</tt> or <tt>ReadAllQuery</tt> query. When you execute the query, EclipseLink retrieves only the attributes in the fetch group. EclipseLink automatically executes a query to fetch all the attributes excluded from this subset when and if you call a <tt>get</tt> method on any one of the excluded attributes.
 +
 +
You can define more than one fetch group for a class. You can optionally designate at most one such fetch group as the default fetch group. If you execute either a <tt>ReadObjectQuery</tt> or <tt>ReadAllQuery</tt> query without specifying a fetch group, EclipseLink will use the default fetch group, unless you configure the query otherwise (see [[Using%20Advanced%20Query%20API%20(ELUG)#How to Configure Default Fetch Group Behavior|How to Configure Default Fetch Group Behavior]]).
 +
 +
You can use fetch groups in JPA projects for EJB objects, as well as for POJO classes. For POJO classes, use partial object querying (see [[Introduction%20to%20EclipseLink%20Queries%20(ELUG)#Partial Object Queries|Partial Object Queries]]).
 +
 +
Before using fetch groups, we recommend that you perform a careful analysis of system use. In many cases, the extra queries required to load attributes not in the fetch group could well offset the gain from the partial attribute loading. For more information about optimizing read performance, see [[Optimizing%20the%20EclipseLink%20Application%20(ELUG)#Read Optimization Examples|Read Optimization Examples]].
 +
 +
This table summarizes which descriptors support fetch group configuration.
 +
 +
<span id="Table 115-38"></span>
 +
{| class="RuleFormal" dir="ltr" title="Descriptor Support for Fetch Group Configuration" summary="This table summarizes which descriptors support fetch group configuration." width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
 +
|- align="left" valign="top"
 +
! id="r1c1-t75" align="left" valign="bottom" | '''Descriptor'''
 +
! id="r1c2-t75" align="left" valign="bottom" | '''Using Workbench'''
 +
! id="r1c3-t75" align="left" valign="bottom" | '''[[#How to Configure Fetch Groups Using Java|Using Java]]<br>'''
 +
|- align="left" valign="top"
 +
| id="r2c1-t75" headers="r1c1-t75" align="left" |
 +
Relational Descriptors
 +
| headers="r2c1-t75 r1c2-t75" align="left" |
 +
[[Image:unsupport.gif|Unsupported]]<br>
 +
| headers="r2c1-t75 r1c3-t75" align="left" |
 +
[[Image:support.gif|Supported.]]<br>
 +
|- align="left" valign="top"
 +
| id="r3c1-t75" headers="r1c1-t75" align="left" |
 +
Object-Relational Data Type Descriptors
 +
| headers="r3c1-t75 r1c2-t75" align="left" |
 +
[[Image:unsupport.gif|Unsupported]]<br>
 +
| headers="r3c1-t75 r1c3-t75" align="left" |
 +
[[Image:support.gif|Supported.]]<br>
 +
|- align="left" valign="top"
 +
| id="r4c1-t75" headers="r1c1-t75" align="left" |
 +
EIS Descriptors
 +
| headers="r4c1-t75 r1c2-t75" align="left" |
 +
[[Image:unsupport.gif|Unsupported]]<br>
 +
| headers="r4c1-t75 r1c3-t75" align="left" |
 +
[[Image:unsupport.gif|Unsupported]]<br>
 +
|- align="left" valign="top"
 +
| id="r5c1-t75" headers="r1c1-t75" align="left" |
 +
XML Descriptors
 +
| headers="r5c1-t75 r1c2-t75" align="left" |
 +
[[Image:unsupport.gif|Unsupported]]<br>
 +
| headers="r5c1-t75 r1c3-t75" align="left" |
 +
[[Image:unsupport.gif|Unsupported]]<br>
 +
|}
 +
 +
<br>
 +
 +
For JPA entities or POJO classes that you configure for weaving, EclipseLink uses fetch groups to improve performance.
 +
 +
This section describes how to create a fetch group, store it in a descriptor, and optionally designate a fetch group as the default fetch group for its descriptor reference class.
 +
 +
For more information, see the following:
 +
* [[Introduction%20to%20Descriptors%20(ELUG)#Fetch Groups|Fetch Groups]]
 +
* [[Introduction%20to%20EclipseLink%20Queries%20(ELUG)#Fetch Groups and Object-Level Read Queries|Fetch Groups and Object-Level Read Queries]]
 +
* [[Using%20Advanced%20Query%20API%20(ELUG)#How to Configure Default Fetch Group Behavior|How to Configure Default Fetch Group Behavior]]
 +
* [[Introduction to EclipseLink%20Application%20Development%20(ELUG)#Using Weaving|Using Weaving]]
 +
* [[Using%20EclipseLink%20JPA%20Extensions%20(ELUG)#Using EclipseLink JPA Weaving|Using EclipseLink JPA Weaving]]
 +
 +
 +
 +
===How to Configure Fetch Groups Using Java===
 +
To configure a fetch group, Use a [[#Configuring Amendment Methods|descriptor amendment method]] as this example shows.
 +
 +
 +
<span id="Example 115-27"></span>
 +
''''' Configuring a Fetch Group'''''
 +
'''//Create a FetchGroupManager for the descriptor'''
 +
 +
descriptor.setFetchGroupManager(new FetchGroupManager());
 +
'''// Create a FetchGroup'''
 +
FetchGroup group = new FetchGroup("nameOnly");
 +
'''// Add attributes to FetchGroup. Alternatively, use'''
 +
'''// FetchGroup method addAttributes, passing in a Set of String attribute names'''
 +
group.addAttribute("firstName");
 +
group.addAttribute("lastName");
 +
'''// Add the FetchGroup to the FetchGroupManager'''
 +
descriptor.getFetchGroupManager().addFetchGroup(group);
 +
'''//Set the default fetch group'''
 +
descriptor.getFetchGroupManager().setDefaultFetchGroup(group);
 +
 +
 +
 +
Each instance of <tt>FetchGroup</tt> that you store in a descriptor must be configured with a fetch group name that is unique for that descriptor (that is, each descriptor owns a set of named fetch groups).
 +
 +
When configuring fetch groups, note that the primary key fields and other required fields (such as inheritance type and optimistic lock version) are always included in all fetch groups.Fetch groups can include direct and relationship attributes. Including a relationship attribute in a fetch group does not cause the relationship to be joined or instantiated: joining and indirection are set independently of fetch groups.
 +
 +
After you add a fetch group to a descriptor, you can configure a <tt>ReadObjectQuery</tt> or <tt>ReadAllQuery</tt> query with this fetch group by name (<tt>nameOnly</tt>) or rely on EclipseLink to use this fetch group by default. For more information, see [[Using%20Advanced%20Query%20API%20(ELUG)#Using Queries with Fetch Groups|Using Queries with Fetch Groups]].
 +
 +
==Configuring a Descriptor Customizer Class==
 +
A descriptor customizer class is a Java class that implements the <tt>org.eclipse.persistence.internal.sessions.factories.DescriptorCustomizer</tt> interface and provides a default (zero-argument) constructor. You can use a descriptor customizer to customize a descriptor at run time on a loaded session before login occurs, similar to how you can use an amendment method (see [[#Configuring Amendment Methods|Configuring Amendment Methods]]).
 +
 +
This table summarizes which sessions support customizer class configuration.
 +
 +
 +
<span id="Table 115-39"></span>
 +
{| class="RuleFormal" dir="ltr" title="Descriptor 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-t76" align="left" valign="bottom" | '''Descriptor'''
 +
! id="r1c2-t76" align="left" valign="bottom" | '''How to Configure Customizer Class Using Workbench'''
 +
! id="r1c3-t76" align="left" valign="bottom" | '''[[#How to Configure Customizer Class Using Java|Using Java]]<br>'''
 +
|- align="left" valign="top"
 +
| id="r2c1-t76" headers="r1c1-t76" align="left" |
 +
Relational Descriptors
 +
| headers="r2c1-t76 r1c2-t76" align="left" |
 +
[[Image:unsupport.gif|Unsupported]]<br>
 +
| headers="r2c1-t76 r1c3-t76" align="left" |
 +
[[Image:support.gif|Supported.]]<br>
 +
|- align="left" valign="top"
 +
| id="r3c1-t76" headers="r1c1-t76" align="left" |
 +
Object-Relational Data Type Descriptors
 +
| headers="r3c1-t76 r1c2-t76" align="left" |
 +
[[Image:unsupport.gif|Unsupported]]<br>
 +
| headers="r3c1-t76 r1c3-t76" align="left" |
 +
[[Image:support.gif|Supported.]]<br>
 +
|- align="left" valign="top"
 +
| id="r4c1-t76" headers="r1c1-t76" align="left" |
 +
EIS Descriptors
 +
| headers="r4c1-t76 r1c2-t76" align="left" |
 +
[[Image:unsupport.gif|Unsupported]]<br>
 +
| headers="r4c1-t76 r1c3-t76" align="left" |
 +
[[Image:support.gif|Supported.]]<br>
 +
|- align="left" valign="top"
 +
| id="r5c1-t76" headers="r1c1-t76" align="left" |
 +
XML Descriptors
 +
| headers="r5c1-t76 r1c2-t76" align="left" |
 +
[[Image:unsupport.gif|Unsupported]]<br>
 +
| headers="r5c1-t76 r1c3-t76" align="left" |
 +
[[Image:support.gif|Supported.]]<br>
 +
|}
 +
 +
For more information, see [[Introduction%20to%20Descriptors%20(ELUG)#Descriptor Customization|Descriptor Customization]].
 +
 +
 +
 +
===How to Configure Customizer Class Using Java===
 +
When using Java, create a customize class that implements the <tt>org.eclipse.persistence.internal.sessions.factories.DescriptorCustomizer</tt> interface. This example illustrates the creation of a descriptor customizer.
 +
 +
<br>
 +
<span id="Example 115-28"></span>
 +
''''' Creating a SessionCustomizer Class'''''
 +
 +
 +
import org.eclipse.persistence.internal.sessions.factories.DescriptorCustomizer;
 +
import org.eclipse.persistence.descriptors.ClassDescriptor;
 +
 +
public class EmployeeDescriptorCustomizer implements DescriptorCustomizer {
 +
 +
    public void customize(ClassDescriptor descriptor) {
 +
        descriptor.setReadOnly();
 +
    }
 +
}
 +
 +
 +
 +
==Configuring Amendment Methods==
 +
Some EclipseLink descriptor features cannot be configured from the Workbench. To use these features, you must write a Java method to amend the descriptor after it is loaded as part of the project. This method must have the following characteristics:
 +
* Be public static.
 +
* Take a single parameter of type <tt>org.persistence.descriptors.structures.ClassDescriptor</tt>.
 +
 +
In the implementation of this method, you can configure advanced features of the descriptor using any of the public descriptor and mapping API.
 +
 +
This table summarizes which descriptors support amendment methods.
 +
 +
<span id="Table 115-40"></span>
 +
{| class="RuleFormal" dir="ltr" title="Descriptor Support for Amendment Methods" summary="This table summarizes which descriptors support for amendment methods." width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
 +
|- align="left" valign="top"
 +
! id="r1c1-t77" align="left" valign="bottom" | '''Descriptor'''
 +
! id="r1c2-t77" align="left" valign="bottom" | '''[[#How to Configure Amendment Methods Using Workbench|Using the Workbench]]<br>'''
 +
! id="r1c3-t77" align="left" valign="bottom" | '''How to Use Java'''
 +
|- align="left" valign="top"
 +
| id="r2c1-t77" headers="r1c1-t77" align="left" |
 +
Relational Descriptors
 +
| headers="r2c1-t77 r1c2-t77" align="left" |
 +
[[Image:support.gif|Supported.]]<br>
 +
| headers="r2c1-t77 r1c3-t77" align="left" |
 +
[[Image:unsupport.gif|Unsupported]]<br>
 +
|- align="left" valign="top"
 +
| id="r3c1-t77" headers="r1c1-t77" align="left" |
 +
Object-Relational Data Type Descriptors
 +
| headers="r3c1-t77 r1c2-t77" align="left" |
 +
[[Image:unsupport.gif|Unsupported]]<br>
 +
| headers="r3c1-t77 r1c3-t77" align="left" |
 +
[[Image:unsupport.gif|Unsupported]]<br>
 +
|- align="left" valign="top"
 +
| id="r4c1-t77" headers="r1c1-t77" align="left" |
 +
EIS Descriptors
 +
| headers="r4c1-t77 r1c2-t77" align="left" |
 +
[[Image:support.gif|Supported.]]<br>
 +
| headers="r4c1-t77 r1c3-t77" align="left" |
 +
[[Image:unsupport.gif|Unsupported]]<br>
 +
|- align="left" valign="top"
 +
| id="r5c1-t77" headers="r1c1-t77" align="left" |
 +
XML Descriptors
 +
| headers="r5c1-t77 r1c2-t77" align="left" |
 +
[[Image:support.gif|Supported.]]<br>
 +
| headers="r5c1-t77 r1c3-t77" align="left" |
 +
[[Image:unsupport.gif|Unsupported]]<br>
 +
|}
 +
 +
 +
This section describes how to associate an amendment method with a descriptor.
 +
 +
For more information about how to implement an amendment method, see [[Introduction%20to%20Descriptors%20(ELUG)#Amendment and After-Load Methods|Amendment and After-Load Methods]].
 +
 +
Alternatively, you can use a descriptor customizer class (see [[#Configuring a Descriptor Customizer Class|Configuring a Descriptor Customizer Class]].
 +
 +
To customize a session, use a session customizer class (see [[Configuring%20a%20Session%20(ELUG)#Configuring a Session Customizer Class|Configuring a Session Customizer Class|Configuring a Session Customizer Class]]).
 +
 +
 +
 +
===How to Configure Amendment Methods Using Workbench===
 +
To use an amendment method with a descriptor (after it is loaded as part of the project) use this procedure:
 +
# Select a descriptor in the '''Navigator'''. Its properties appear in the Editor.If the '''After load''' advanced property is not visible for the descriptor, right-click the descriptor and choose '''Select Advanced Properties''' > '''After Load''' from context menu or from the '''Selected''' menu.
 +
# Click the '''After Load''' tab in the '''Editor'''.<br>''''' After Load Tab'''''<br>[[Image:aftrload.gif|After Load Tab]]<br><br>
 +
# Complete each field on the  After Load tab.
 +
 +
 +
 +
{| class="HRuleInformal" dir="ltr" title="This table defines each field on the After Load tab." summary="This table defines each field on the After Load tab." width="100%" border="1" frame="hsides" rules="rows" cellpadding="3" frame="hsides" rules="rows"
 +
|- align="left" valign="top"
 +
! id="r1c1-t78" align="left" valign="bottom" | '''Field'''
 +
! id="r1c2-t78" align="left" valign="bottom" | '''Description'''
 +
|- align="left" valign="top"
 +
| id="r2c1-t78" headers="r1c1-t78" align="left" | '''Class'''
 +
| headers="r2c1-t78 r1c2-t78" align="left" | Click '''Browse''' and choose the class of the method to execute.
 +
|- align="left" valign="top"
 +
| id="r3c1-t78" headers="r1c1-t78" align="left" | '''Static Method'''
 +
| headers="r3c1-t78 r1c2-t78" align="left" | Use the '''Static Method''' list to choose the static method to execute at run time, after loading the descriptor. The method must be public static and take a single attribute of type <tt>org.eclipse.persistence.descriptors.ClassDescriptor</tt>.
 +
|}
 +
 +
<br>
 +
  
  
Line 3,506: Line 4,592:
  
 
[[Category: EclipseLink User's Guide]]
 
[[Category: EclipseLink User's Guide]]
[[Category: Draft]]
+
[[Category: Release 1]]
 
[[Category: Task]]
 
[[Category: Task]]

Latest revision as of 09:22, 1 May 2009