Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Difference between revisions of "Configuring a Relational Descriptor (ELUG)"
m (New page: <div style="margin:5px;float:right;border:1px solid #000000;padding:5px">__TOC__ Related Topics</div> This section descri...) |
m (227400) |
||
(15 intermediate revisions by the same user not shown) | |||
Line 2: | Line 2: | ||
[[Special:Whatlinkshere/Creating a Relational Descriptor (ELUG)|Related Topics]]</div> | [[Special:Whatlinkshere/Creating a Relational Descriptor (ELUG)|Related Topics]]</div> | ||
− | + | For information on how to create relational descriptors, see [[Creating%20a%20Relational%20Descriptor%20(ELUG)|Creating a Relational Descriptor]]. | |
− | + | ||
− | For information on how to | + | |
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
This table lists the default configurable options for a relational descriptor. | This table lists the default configurable options for a relational descriptor. | ||
Line 16: | Line 8: | ||
<span id="Table 28-1"><span> | <span id="Table 28-1"><span> | ||
− | + | {| class="RuleFormalMax" dir="ltr" title="Configurable Options for Relational Descriptor" summary="This table lists the configurable options common to Relational Descriptors and indicates if the option can be configured with the EclipseLink Workbench, Java, or both." width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all" | |
− | + | ||
− | {| class="RuleFormalMax" dir="ltr" title="Configurable Options for Relational Descriptor" summary="This table lists the configurable options common to Relational Descriptors | + | |
|- align="left" valign="top" | |- align="left" valign="top" | ||
! id="r1c1-t2" align="left" valign="bottom" | '''Option to Configure''' | ! id="r1c1-t2" align="left" valign="bottom" | '''Option to Configure''' | ||
Line 25: | Line 15: | ||
|- align="left" valign="top" | |- align="left" valign="top" | ||
| id="r2c1-t2" headers="r1c1-t2" align="left" | | | id="r2c1-t2" headers="r1c1-t2" align="left" | | ||
− | + | [[#Configuring Associated Tables|Associated tables]] | |
| headers="r2c1-t2 r1c2-t2" align="left" | | | headers="r2c1-t2 r1c2-t2" align="left" | | ||
[[Image:support.gif|Supported]] | [[Image:support.gif|Supported]] | ||
Line 32: | Line 22: | ||
|- align="left" valign="top" | |- align="left" valign="top" | ||
| id="r3c1-t2" headers="r1c1-t2" align="left" | | | id="r3c1-t2" headers="r1c1-t2" align="left" | | ||
− | + | [[Configuring%20a%20Descriptor%20(ELUG)#Configuring Primary Keys|Primary keys ]] | |
| headers="r3c1-t2 r1c2-t2" align="left" | | | headers="r3c1-t2 r1c2-t2" align="left" | | ||
[[Image:support.gif|Supported]] | [[Image:support.gif|Supported]] | ||
Line 39: | Line 29: | ||
|- align="left" valign="top" | |- align="left" valign="top" | ||
| id="r4c1-t2" headers="r1c1-t2" align="left" | | | id="r4c1-t2" headers="r1c1-t2" align="left" | | ||
− | + | [[#Configuring Sequencing at the Descriptor Level|Sequencing ]] | |
| headers="r4c1-t2 r1c2-t2" align="left" | | | headers="r4c1-t2 r1c2-t2" align="left" | | ||
[[Image:support.gif|Supported]] | [[Image:support.gif|Supported]] | ||
Line 46: | Line 36: | ||
|- align="left" valign="top" | |- align="left" valign="top" | ||
| id="r5c1-t2" headers="r1c1-t2" align="left" | | | id="r5c1-t2" headers="r1c1-t2" align="left" | | ||
− | + | [[Configuring%20a%20Descriptor%20(ELUG)#Configuring Read-Only Descriptors|Read-only descriptors ]] | |
| headers="r5c1-t2 r1c2-t2" align="left" | | | headers="r5c1-t2 r1c2-t2" align="left" | | ||
[[Image:support.gif|Supported]] | [[Image:support.gif|Supported]] | ||
Line 53: | Line 43: | ||
|- align="left" valign="top" | |- align="left" valign="top" | ||
| id="r6c1-t2" headers="r1c1-t2" align="left" | | | id="r6c1-t2" headers="r1c1-t2" align="left" | | ||
− | + | [[Configuring%20a%20Descriptor%20(ELUG)#Configuring Unit of Work Conforming at the Descriptor Level|Unit of work conforming ]] | |
| headers="r6c1-t2 r1c2-t2" align="left" | | | headers="r6c1-t2 r1c2-t2" align="left" | | ||
[[Image:support.gif|Supported]] | [[Image:support.gif|Supported]] | ||
Line 60: | Line 50: | ||
|- align="left" valign="top" | |- align="left" valign="top" | ||
| id="r7c1-t2" headers="r1c1-t2" align="left" | | | id="r7c1-t2" headers="r1c1-t2" align="left" | | ||
− | + | [[Configuring%20a%20Descriptor%20(ELUG)#Configuring Descriptor Alias|Descriptor alias ]] | |
| headers="r7c1-t2 r1c2-t2" align="left" | | | headers="r7c1-t2 r1c2-t2" align="left" | | ||
[[Image:support.gif|Supported]] | [[Image:support.gif|Supported]] | ||
Line 67: | Line 57: | ||
|- align="left" valign="top" | |- align="left" valign="top" | ||
| id="r8c1-t2" headers="r1c1-t2" align="left" | | | id="r8c1-t2" headers="r1c1-t2" align="left" | | ||
− | + | [[Configuring%20a%20Descriptor%20(ELUG)#Configuring Descriptor Comments|Descriptor comments ]] | |
| headers="r8c1-t2 r1c2-t2" align="left" | | | headers="r8c1-t2 r1c2-t2" align="left" | | ||
[[Image:support.gif|Supported]] | [[Image:support.gif|Supported]] | ||
Line 74: | Line 64: | ||
|- align="left" valign="top" | |- align="left" valign="top" | ||
| id="r9c1-t2" headers="r1c1-t2" align="left" | | | id="r9c1-t2" headers="r1c1-t2" align="left" | | ||
− | + | [[Using%20Workbench%20(ELUG)#How to Configure Classes|Classes]] | |
| headers="r9c1-t2 r1c2-t2" align="left" | | | headers="r9c1-t2 r1c2-t2" align="left" | | ||
[[Image:support.gif|Supported]] | [[Image:support.gif|Supported]] | ||
Line 81: | Line 71: | ||
|- align="left" valign="top" | |- align="left" valign="top" | ||
| id="r10c1-t2" headers="r1c1-t2" align="left" | | | id="r10c1-t2" headers="r1c1-t2" align="left" | | ||
− | + | [[Configuring%20a%20Descriptor%20(ELUG)#Configuring Named Queries at the Descriptor Level|Named queries ]] | |
| headers="r10c1-t2 r1c2-t2" align="left" | | | headers="r10c1-t2 r1c2-t2" align="left" | | ||
[[Image:support.gif|Supported]] | [[Image:support.gif|Supported]] | ||
Line 88: | Line 78: | ||
|- align="left" valign="top" | |- align="left" valign="top" | ||
| id="r11c1-t2" headers="r1c1-t2" align="left" | | | id="r11c1-t2" headers="r1c1-t2" align="left" | | ||
− | + | [[#Configuring Custom SQL Queries for Basic Persistence Operations|Custom SQL queries for basic persistence operations ]] | |
| headers="r11c1-t2 r1c2-t2" align="left" | | | headers="r11c1-t2 r1c2-t2" align="left" | | ||
[[Image:support.gif|Supported]] | [[Image:support.gif|Supported]] | ||
Line 95: | Line 85: | ||
|- align="left" valign="top" | |- align="left" valign="top" | ||
| id="r12c1-t2" headers="r1c1-t2" align="left" | | | id="r12c1-t2" headers="r1c1-t2" align="left" | | ||
− | + | [[Configuring%20a%20Descriptor%20(ELUG)#Configuring Query Timeout at the Descriptor Level|Query timeout ]] | |
| headers="r12c1-t2 r1c2-t2" align="left" | | | headers="r12c1-t2 r1c2-t2" align="left" | | ||
[[Image:support.gif|Supported]] | [[Image:support.gif|Supported]] | ||
Line 102: | Line 92: | ||
|- align="left" valign="top" | |- align="left" valign="top" | ||
| id="r13c1-t2" headers="r1c1-t2" align="left" | | | id="r13c1-t2" headers="r1c1-t2" align="left" | | ||
− | + | [[Configuring%20a%20Descriptor%20(ELUG)#Configuring Cache Refreshing|Cache refreshing ]] | |
| headers="r13c1-t2 r1c2-t2" align="left" | | | headers="r13c1-t2 r1c2-t2" align="left" | | ||
[[Image:support.gif|Supported]] | [[Image:support.gif|Supported]] | ||
Line 109: | Line 99: | ||
|- align="left" valign="top" | |- align="left" valign="top" | ||
| id="r14c1-t2" headers="r1c1-t2" align="left" | | | id="r14c1-t2" headers="r1c1-t2" align="left" | | ||
− | + | [[Configuring%20a%20Descriptor%20(ELUG)#Configuring Query Keys|Query keys ]] | |
| headers="r14c1-t2 r1c2-t2" align="left" | | | headers="r14c1-t2 r1c2-t2" align="left" | | ||
[[Image:support.gif|Supported]] | [[Image:support.gif|Supported]] | ||
Line 116: | Line 106: | ||
|- align="left" valign="top" | |- align="left" valign="top" | ||
| id="r15c1-t2" headers="r1c1-t2" align="left" | | | id="r15c1-t2" headers="r1c1-t2" align="left" | | ||
− | + | [[Configuring%20a%20Descriptor%20(ELUG)#Configuring Interface Query Keys|Interface query keys ]] | |
| headers="r15c1-t2 r1c2-t2" align="left" | | | headers="r15c1-t2 r1c2-t2" align="left" | | ||
[[Image:support.gif|Supported.]] | [[Image:support.gif|Supported.]] | ||
Line 123: | Line 113: | ||
|- align="left" valign="top" | |- align="left" valign="top" | ||
| id="r16c1-t2" headers="r1c1-t2" align="left" | | | id="r16c1-t2" headers="r1c1-t2" align="left" | | ||
− | + | [[#Configuring Interface Alias|Interface alias ]] | |
| headers="r16c1-t2 r1c2-t2" align="left" | | | headers="r16c1-t2 r1c2-t2" align="left" | | ||
[[Image:support.gif|Supported]] | [[Image:support.gif|Supported]] | ||
Line 130: | Line 120: | ||
|- align="left" valign="top" | |- align="left" valign="top" | ||
| id="r17c1-t2" headers="r1c1-t2" align="left" | | | id="r17c1-t2" headers="r1c1-t2" align="left" | | ||
− | + | [[Configuring%20a%20Descriptor%20(ELUG)#Configuring Cache Type and Size at the Descriptor Level|Cache type and size ]] | |
| headers="r17c1-t2 r1c2-t2" align="left" | | | headers="r17c1-t2 r1c2-t2" align="left" | | ||
[[Image:support.gif|Supported]] | [[Image:support.gif|Supported]] | ||
Line 137: | Line 127: | ||
|- align="left" valign="top" | |- align="left" valign="top" | ||
| id="r18c1-t2" headers="r1c1-t2" align="left" | | | id="r18c1-t2" headers="r1c1-t2" align="left" | | ||
− | + | [[Configuring%20a%20Descriptor%20(ELUG)#Configuring Cache Isolation at the Descriptor Level|Cache isolation ]] | |
| headers="r18c1-t2 r1c2-t2" align="left" | | | headers="r18c1-t2 r1c2-t2" align="left" | | ||
[[Image:support.gif|Supported.]] | [[Image:support.gif|Supported.]] | ||
Line 144: | Line 134: | ||
|- align="left" valign="top" | |- align="left" valign="top" | ||
| id="r19c1-t2" headers="r1c1-t2" align="left" | | | id="r19c1-t2" headers="r1c1-t2" align="left" | | ||
− | + | [[Configuring%20a%20Descriptor%20(ELUG)#Configuring Cache Coordination Change Propagation at the Descriptor Level|Cache coordination change propagation]] | |
| headers="r19c1-t2 r1c2-t2" align="left" | | | headers="r19c1-t2 r1c2-t2" align="left" | | ||
[[Image:support.gif|Supported.]] | [[Image:support.gif|Supported.]] | ||
Line 151: | Line 141: | ||
|- align="left" valign="top" | |- align="left" valign="top" | ||
| id="r20c1-t2" headers="r1c1-t2" align="left" | | | id="r20c1-t2" headers="r1c1-t2" align="left" | | ||
− | + | [[Configuring%20a%20Descriptor%20(ELUG)#Configuring Cache Expiration at the Descriptor Level|Cache expiration ]] | |
| headers="r20c1-t2 r1c2-t2" align="left" | | | headers="r20c1-t2 r1c2-t2" align="left" | | ||
[[Image:support.gif|Supported.]] | [[Image:support.gif|Supported.]] | ||
Line 158: | Line 148: | ||
|- align="left" valign="top" | |- align="left" valign="top" | ||
| id="r21c1-t2" headers="r1c1-t2" align="left" | | | id="r21c1-t2" headers="r1c1-t2" align="left" | | ||
− | + | [[Configuring%20a%20Descriptor%20(ELUG)#Configuring Cache Existence Checking at the Descriptor Level|Cache existence Checking ]] | |
| headers="r21c1-t2 r1c2-t2" align="left" | | | headers="r21c1-t2 r1c2-t2" align="left" | | ||
[[Image:support.gif|Supported.]] | [[Image:support.gif|Supported.]] | ||
| headers="r21c1-t2 r1c3-t2" align="left" | | | headers="r21c1-t2 r1c3-t2" align="left" | | ||
[[Image:support.gif|Supported.]] | [[Image:support.gif|Supported.]] | ||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
|- align="left" valign="top" | |- align="left" valign="top" | ||
| id="r23c1-t2" headers="r1c1-t2" align="left" | | | id="r23c1-t2" headers="r1c1-t2" align="left" | | ||
− | + | [[#Configuring a Relational Descriptor as a Class or Aggregate Type|Relational descriptor as a class or aggregate type ]] | |
| headers="r23c1-t2 r1c2-t2" align="left" | | | headers="r23c1-t2 r1c2-t2" align="left" | | ||
[[Image:support.gif|Supported]] | [[Image:support.gif|Supported]] | ||
Line 179: | Line 162: | ||
|- align="left" valign="top" | |- align="left" valign="top" | ||
| id="r24c1-t2" headers="r1c1-t2" align="left" | | | id="r24c1-t2" headers="r1c1-t2" align="left" | | ||
− | + | [[Configuring%20a%20Descriptor%20(ELUG)#Configuring Reading Subclasses on Queries|Reading subclasses on queries ]] | |
| headers="r24c1-t2 r1c2-t2" align="left" | | | headers="r24c1-t2 r1c2-t2" align="left" | | ||
[[Image:support.gif|Supported]] | [[Image:support.gif|Supported]] | ||
Line 186: | Line 169: | ||
|- align="left" valign="top" | |- align="left" valign="top" | ||
| id="r25c1-t2" headers="r1c1-t2" align="left" | | | id="r25c1-t2" headers="r1c1-t2" align="left" | | ||
− | + | [[Configuring%20a%20Descriptor%20(ELUG)#Configuring Inheritance for a Child (Branch or Leaf) Class Descriptor|Inheritance for a child class descriptor ]] | |
| headers="r25c1-t2 r1c2-t2" align="left" | | | headers="r25c1-t2 r1c2-t2" align="left" | | ||
[[Image:support.gif|Supported.]] | [[Image:support.gif|Supported.]] | ||
Line 193: | Line 176: | ||
|- align="left" valign="top" | |- align="left" valign="top" | ||
| id="r26c1-t2" headers="r1c1-t2" align="left" | | | id="r26c1-t2" headers="r1c1-t2" align="left" | | ||
− | + | [[Configuring%20a%20Descriptor%20(ELUG)#Configuring Inheritance for a Parent (Root) Descriptor|Inheritance for a parent class descriptor]] | |
| headers="r26c1-t2 r1c2-t2" align="left" | | | headers="r26c1-t2 r1c2-t2" align="left" | | ||
[[Image:support.gif|Supported]] | [[Image:support.gif|Supported]] | ||
Line 200: | Line 183: | ||
|- align="left" valign="top" | |- align="left" valign="top" | ||
| id="r27c1-t2" headers="r1c1-t2" align="left" | | | id="r27c1-t2" headers="r1c1-t2" align="left" | | ||
− | + | [[Configuring%20a%20Descriptor%20(ELUG)#Configuring Inheritance Expressions for a Parent (Root) Class Descriptor|Inheritance expressions for a parent class descriptor]] | |
| headers="r27c1-t2 r1c2-t2" align="left" | | | headers="r27c1-t2 r1c2-t2" align="left" | | ||
[[Image:unsupport.gif|Unsupported.]] | [[Image:unsupport.gif|Unsupported.]] | ||
Line 207: | Line 190: | ||
|- align="left" valign="top" | |- align="left" valign="top" | ||
| id="r28c1-t2" headers="r1c1-t2" align="left" | | | id="r28c1-t2" headers="r1c1-t2" align="left" | | ||
− | + | [[Configuring%20a%20Descriptor%20(ELUG)#Configuring Inherited Attribute Mapping in a Subclass|Inherited attribute mapping in a subclass]] | |
| headers="r28c1-t2 r1c2-t2" align="left" | | | headers="r28c1-t2 r1c2-t2" align="left" | | ||
[[Image:support.gif|Supported.]] | [[Image:support.gif|Supported.]] | ||
Line 214: | Line 197: | ||
|- align="left" valign="top" | |- align="left" valign="top" | ||
| id="r29c1-t2" headers="r1c1-t2" align="left" | | | id="r29c1-t2" headers="r1c1-t2" align="left" | | ||
− | + | [[#Configuring Multitable Information|(see ]] | |
| headers="r29c1-t2 r1c2-t2" align="left" | | | headers="r29c1-t2 r1c2-t2" align="left" | | ||
[[Image:support.gif|Supported]] | [[Image:support.gif|Supported]] | ||
Line 221: | Line 204: | ||
|- align="left" valign="top" | |- align="left" valign="top" | ||
| id="r30c1-t2" headers="r1c1-t2" align="left" | | | id="r30c1-t2" headers="r1c1-t2" align="left" | | ||
− | + | [[Configuring%20a%20Descriptor%20(ELUG)#Configuring a Domain Object Method as an Event Handler|Domain object method as an event handler ]] | |
| headers="r30c1-t2 r1c2-t2" align="left" | | | headers="r30c1-t2 r1c2-t2" align="left" | | ||
[[Image:support.gif|Supported.]] | [[Image:support.gif|Supported.]] | ||
Line 228: | Line 211: | ||
|- align="left" valign="top" | |- align="left" valign="top" | ||
| id="r31c1-t2" headers="r1c1-t2" align="left" | | | id="r31c1-t2" headers="r1c1-t2" align="left" | | ||
− | + | [[Configuring%20a%20Descriptor%20(ELUG)#Configuring a Descriptor Event Listener as an Event Handler|Descriptor event listener as an event handler ]] | |
| headers="r31c1-t2 r1c2-t2" align="left" | | | headers="r31c1-t2 r1c2-t2" align="left" | | ||
[[Image:support.gif|Supported.]] | [[Image:support.gif|Supported.]] | ||
Line 235: | Line 218: | ||
|- align="left" valign="top" | |- align="left" valign="top" | ||
| id="r32c1-t2" headers="r1c1-t2" align="left" | | | id="r32c1-t2" headers="r1c1-t2" align="left" | | ||
− | + | [[Configuring%20a%20Descriptor%20(ELUG)#Configuring Locking Policy|Locking policy ]] | |
| headers="r32c1-t2 r1c2-t2" align="left" | | | headers="r32c1-t2 r1c2-t2" align="left" | | ||
[[Image:support.gif|Supported]] | [[Image:support.gif|Supported]] | ||
Line 242: | Line 225: | ||
|- align="left" valign="top" | |- align="left" valign="top" | ||
| id="r33c1-t2" headers="r1c1-t2" align="left" | | | id="r33c1-t2" headers="r1c1-t2" align="left" | | ||
− | + | [[Configuring%20a%20Descriptor%20(ELUG)#Configuring Returning Policy|Returning policy ]] | |
| headers="r33c1-t2 r1c2-t2" align="left" | | | headers="r33c1-t2 r1c2-t2" align="left" | | ||
[[Image:support.gif|Supported]] | [[Image:support.gif|Supported]] | ||
Line 249: | Line 232: | ||
|- align="left" valign="top" | |- align="left" valign="top" | ||
| id="r34c1-t2" headers="r1c1-t2" align="left" | | | id="r34c1-t2" headers="r1c1-t2" align="left" | | ||
− | + | [[Configuring%20a%20Descriptor%20(ELUG)#Configuring Instantiation Policy|Instantiation policy ]] | |
| headers="r34c1-t2 r1c2-t2" align="left" | | | headers="r34c1-t2 r1c2-t2" align="left" | | ||
[[Image:support.gif|Supported]] | [[Image:support.gif|Supported]] | ||
Line 256: | Line 239: | ||
|- align="left" valign="top" | |- align="left" valign="top" | ||
| id="r35c1-t2" headers="r1c1-t2" align="left" | | | id="r35c1-t2" headers="r1c1-t2" align="left" | | ||
− | + | [[Configuring%20a%20Descriptor%20(ELUG)#Configuring Copy Policy|Copy policy ]] | |
| headers="r35c1-t2 r1c2-t2" align="left" | | | headers="r35c1-t2 r1c2-t2" align="left" | | ||
[[Image:support.gif|Supported]] | [[Image:support.gif|Supported]] | ||
Line 263: | Line 246: | ||
|- align="left" valign="top" | |- align="left" valign="top" | ||
| id="r36c1-t2" headers="r1c1-t2" align="left" | | | id="r36c1-t2" headers="r1c1-t2" align="left" | | ||
− | + | [[Configuring%20a%20Descriptor%20(ELUG)#Configuring Change Policy|Change policy ]] | |
| headers="r36c1-t2 r1c2-t2" align="left" | | | headers="r36c1-t2 r1c2-t2" align="left" | | ||
[[Image:unsupport.gif|Unsupported.]] | [[Image:unsupport.gif|Unsupported.]] | ||
Line 270: | Line 253: | ||
|- align="left" valign="top" | |- align="left" valign="top" | ||
| id="r37c1-t2" headers="r1c1-t2" align="left" | | | id="r37c1-t2" headers="r1c1-t2" align="left" | | ||
− | + | [[Configuring%20a%20Descriptor%20(ELUG)#Configuring a History Policy|History policy ]] | |
| headers="r37c1-t2 r1c2-t2" align="left" | | | headers="r37c1-t2 r1c2-t2" align="left" | | ||
[[Image:unsupport.gif|Unsupported.]] | [[Image:unsupport.gif|Unsupported.]] | ||
Line 277: | Line 260: | ||
|- align="left" valign="top" | |- align="left" valign="top" | ||
| id="r38c1-t2" headers="r1c1-t2" align="left" | | | id="r38c1-t2" headers="r1c1-t2" align="left" | | ||
− | + | [[Configuring%20a%20Descriptor%20(ELUG)#Configuring Wrapper Policy|Wrapper policy ]] | |
| headers="r38c1-t2 r1c2-t2" align="left" | | | headers="r38c1-t2 r1c2-t2" align="left" | | ||
[[Image:unsupport.gif|Unsupported.]] | [[Image:unsupport.gif|Unsupported.]] | ||
Line 284: | Line 267: | ||
|- align="left" valign="top" | |- align="left" valign="top" | ||
| id="r39c1-t2" headers="r1c1-t2" align="left" | | | id="r39c1-t2" headers="r1c1-t2" align="left" | | ||
− | + | [[Configuring%20a%20Descriptor%20(ELUG)#Configuring Fetch Groups|Fetch groups ]] | |
| headers="r39c1-t2 r1c2-t2" align="left" | | | headers="r39c1-t2 r1c2-t2" align="left" | | ||
[[Image:unsupport.gif|Unsupported.]] | [[Image:unsupport.gif|Unsupported.]] | ||
Line 291: | Line 274: | ||
|- align="left" valign="top" | |- align="left" valign="top" | ||
| id="r40c1-t2" headers="r1c1-t2" align="left" | | | id="r40c1-t2" headers="r1c1-t2" align="left" | | ||
− | + | [[Configuring%20a%20Descriptor%20(ELUG)#Configuring Amendment Methods#Configuring Amendment Methods|Amendment methods ]] | |
| headers="r40c1-t2 r1c2-t2" align="left" | | | headers="r40c1-t2 r1c2-t2" align="left" | | ||
[[Image:support.gif|Supported]] | [[Image:support.gif|Supported]] | ||
Line 298: | Line 281: | ||
|- align="left" valign="top" | |- align="left" valign="top" | ||
| id="r41c1-t2" headers="r1c1-t2" align="left" | | | id="r41c1-t2" headers="r1c1-t2" align="left" | | ||
− | + | [[Configuring%20a%20Mapping%20(ELUG)#Configuring a Mapping|Mappings]] | |
| headers="r41c1-t2 r1c2-t2" align="left" | | | headers="r41c1-t2 r1c2-t2" align="left" | | ||
[[Image:support.gif|Supported]] | [[Image:support.gif|Supported]] | ||
Line 304: | Line 287: | ||
[[Image:support.gif|Supported]] | [[Image:support.gif|Supported]] | ||
|} | |} | ||
− | |||
Line 312: | Line 294: | ||
==Configuring Associated Tables== | ==Configuring Associated Tables== | ||
− | |||
Each relational class descriptor (see [[Creating%20a%20Relational%20Descriptor%20(ELUG)|Creating Relational Class Descriptors]]) must be associated with a database table for storing instances of that class. This does not apply to relational aggregate descriptors (see [[Creating%20a%20Relational%20Descriptor%20(ELUG)|Creating Relational Aggregate Descriptors]]). | Each relational class descriptor (see [[Creating%20a%20Relational%20Descriptor%20(ELUG)|Creating Relational Class Descriptors]]) must be associated with a database table for storing instances of that class. This does not apply to relational aggregate descriptors (see [[Creating%20a%20Relational%20Descriptor%20(ELUG)|Creating Relational Aggregate Descriptors]]). | ||
− | |||
Line 323: | Line 303: | ||
# 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, Associated Table Options<br>'''''[[Image:desasstbl.gif|Descriptor Info Tab, Associated Table Options]] | # Click the '''Descriptor Info''' tab. The Descriptor Info tab appears.<br>'''''Descriptor Info Tab, Associated Table Options<br>'''''[[Image:desasstbl.gif|Descriptor Info Tab, Associated Table Options]] | ||
− | # | + | # Use the '''Associated Table''' list to select a database table for the descriptor. You must associate a descriptor with a database table ''before'' specifying primary keys. |
− | + | See Also: | |
− | + | : [[#Configuring Associated Tables|Configuring Associated Tables]] | |
− | + | ||
− | : [[#Configuring Associated Tables]] | + | |
: [[Configuring%20a%20Descriptor%20(ELUG)|Configuring a Descriptor]] | : [[Configuring%20a%20Descriptor%20(ELUG)|Configuring a Descriptor]] | ||
− | |||
Line 343: | Line 320: | ||
Sequencing allows EclipseLink to automatically assign the primary key or ID of an object when the object is inserted. | Sequencing allows EclipseLink to automatically assign the primary key or ID of an object when the object is inserted. | ||
− | You configure EclipseLink sequencing at the | + | You configure EclipseLink sequencing at the [[Configuring%20a%20Relational%20Project%20(ELUG)#Configuring Sequencing at the Project Level|project level]] or [[Configuring%20a%20Database%20Login%20(ELUG)#Configuring Sequencing at the Session Level|session level]] to tell EclipseLink how to obtain sequence values: that is, what type of sequences to use. |
To enable sequencing, you must then configure EclipseLink sequencing at the descriptor level to tell EclipseLink into which table and column to write the sequence value when an instance of a descriptor's reference class is created. | To enable sequencing, you must then configure EclipseLink sequencing at the descriptor level to tell EclipseLink into which table and column to write the sequence value when an instance of a descriptor's reference class is created. | ||
Line 349: | Line 326: | ||
Only descriptors that have been configured with a sequence field and a sequence name will be assigned sequence numbers. | Only descriptors that have been configured with a sequence field and a sequence name will be assigned sequence numbers. | ||
− | The sequence field is the database field that the sequence number will be assigned to: this is almost always the | + | The sequence field is the database field that the sequence number will be assigned to: this is almost always the [[Configuring%20a%20Descriptor%20(ELUG)#Configuring Primary Keys|primary key field]]. The sequence name is the name of the sequence to be used for this descriptor. The purpose of the sequence name depends on the type of sequencing you are using: |
When using table sequencing, the sequence name refers to the row's SEQ_NAME value used to store this sequence. | When using table sequencing, the sequence name refers to the row's SEQ_NAME value used to store this sequence. | ||
Line 357: | Line 334: | ||
The sequence name can also refer to a custom sequence defined in the project. | The sequence name can also refer to a custom sequence defined in the project. | ||
− | For more information, see [[Introduction%20to%20Relational%20Projects%20(ELUG)|Sequencing in Relational Projects]]. | + | For more information, see [[Introduction%20to%20Relational%20Projects%20(ELUG)#Sequencing in Relational Projects|Sequencing in Relational Projects]]. |
− | + | ||
Line 370: | Line 346: | ||
Use the following information to specify sequencing options: | Use the following information to specify sequencing options: | ||
− | |||
{| class="HRuleInformal" dir="ltr" title="This table defines sequencing options on the Descriptor Info tab for a database project." summary="This table defines sequencing options on the Descriptor Info tab for a database project." width="100%" border="1" frame="hsides" rules="rows" cellpadding="3" frame="hsides" rules="rows" | {| class="HRuleInformal" dir="ltr" title="This table defines sequencing options on the Descriptor Info tab for a database project." summary="This table defines sequencing options on the Descriptor Info tab for a database project." width="100%" border="1" frame="hsides" rules="rows" cellpadding="3" frame="hsides" rules="rows" | ||
|- align="left" valign="top" | |- align="left" valign="top" | ||
Line 379: | Line 354: | ||
| headers="r2c1-t3 r1c2-t3" align="left" | Specify if this descriptor uses sequencing. If selected, specify the Name, Table, and Field for sequencing. | | headers="r2c1-t3 r1c2-t3" align="left" | Specify if this descriptor uses sequencing. If selected, specify the Name, Table, and Field for sequencing. | ||
|- align="left" valign="top" | |- align="left" valign="top" | ||
− | | id="r3c1-t3" headers="r1c1-t3" align="left" | '''Name''' | + | | id="r3c1-t3" headers="r1c1-t3" align="left" | |
+ | :'''Name''' | ||
| headers="r3c1-t3 r1c2-t3" align="left" | | | headers="r3c1-t3 r1c2-t3" align="left" | | ||
Enter the name of the sequence. | Enter the name of the sequence. | ||
− | * '''For table sequencing:''' Enter the name of the value in the sequence name column (for default table sequencing, the column named <tt>SEQ_NAME</tt>) of the sequence table (for default table sequencing, the table named <tt>SEQUENCE</tt>) that EclipseLink uses to look up the corresponding sequence count value (for default table sequencing, the corresponding value in the <tt>SEQ_COUNT</tt> column) for this descriptor's reference class. For more information, see [[Introduction%20to%20Relational%20Projects%20(ELUG)|Table Sequencing]]. | + | * '''For table sequencing:''' Enter the name of the value in the sequence name column (for default table sequencing, the column named <tt>SEQ_NAME</tt>) of the sequence table (for default table sequencing, the table named <tt>SEQUENCE</tt>) that EclipseLink uses to look up the corresponding sequence count value (for default table sequencing, the corresponding value in the <tt>SEQ_COUNT</tt> column) for this descriptor's reference class. For more information, see [[Introduction%20to%20Relational%20Projects%20(ELUG)#Table Sequencing|Table Sequencing]]. |
− | * '''For native sequencing (Oracle platform):''' Enter the name of the sequence object that Oracle Database creates to manage sequencing for this descriptor's reference class. For more information, see [[Introduction%20to%20Relational%20Projects%20(ELUG)|Native Sequencing with an Oracle Database Platform]] | + | * '''For native sequencing (Oracle platform):''' Enter the name of the sequence object that Oracle Database creates to manage sequencing for this descriptor's reference class. For more information, see [[Introduction%20to%20Relational%20Projects%20(ELUG)#Native Sequencing with an Oracle Database Platform|Native Sequencing with an Oracle Database Platform]] |
− | * '''For native sequencing (non-Oracle platform):''' For database compatibility, enter a generic name for the sequence, such as <tt>SEQ</tt>. For more information, see [[Introduction%20to%20Relational%20Projects%20(ELUG)|Native Sequencing with a Non-Oracle Database Platform]]. | + | * '''For native sequencing (non-Oracle platform):''' For database compatibility, enter a generic name for the sequence, such as <tt>SEQ</tt>. For more information, see [[Introduction%20to%20Relational%20Projects%20(ELUG)#Native Sequencing with a Non-Oracle Database Platform|Native Sequencing with a Non-Oracle Database Platform]]. |
|- align="left" valign="top" | |- align="left" valign="top" | ||
− | | id="r4c1-t3" headers="r1c1-t3" align="left" | '''Table''' | + | | id="r4c1-t3" headers="r1c1-t3" align="left" | |
+ | :'''Table''' | ||
| headers="r4c1-t3 r1c2-t3" align="left" | Specify the name of the database table that contains the field (see '''Field''') into which EclipseLink is to write the sequence value when a new instance of this descriptor's reference class is created. This is almost always this descriptor's primary table. | | headers="r4c1-t3 r1c2-t3" align="left" | Specify the name of the database table that contains the field (see '''Field''') into which EclipseLink is to write the sequence value when a new instance of this descriptor's reference class is created. This is almost always this descriptor's primary table. | ||
|- align="left" valign="top" | |- align="left" valign="top" | ||
− | | id="r5c1-t3" headers="r1c1-t3" align="left" | '''Field''' | + | | id="r5c1-t3" headers="r1c1-t3" align="left" | |
+ | :'''Field''' | ||
| headers="r5c1-t3 r1c2-t3" align="left" | | | headers="r5c1-t3 r1c2-t3" align="left" | | ||
Specify the name of the field in the specified table (see '''Table''') into which EclipseLink is to write the sequence value when a new instance of this descriptor's reference class is created. This field is almost always the class's primary key (see [[Configuring%20a%20Descriptor%20(ELUG)|Configuring Primary Keys]]). | Specify the name of the field in the specified table (see '''Table''') into which EclipseLink is to write the sequence value when a new instance of this descriptor's reference class is created. This field is almost always the class's primary key (see [[Configuring%20a%20Descriptor%20(ELUG)|Configuring Primary Keys]]). | ||
− | * '''For native sequencing (non-Oracle platform)'''<nowiki>: Ensure that your database schema specifies the correct type for this field (see </nowiki>[[Introduction%20to%20Relational%20Projects%20(ELUG)|Native Sequencing with a Non-Oracle Database Platform]]). | + | * '''For native sequencing (non-Oracle platform)'''<nowiki>: Ensure that your database schema specifies the correct type for this field (see </nowiki>[[Introduction%20to%20Relational%20Projects%20(ELUG)#Native Sequencing with a Non-Oracle Database Platform|Native Sequencing with a Non-Oracle Database Platform]]). |
|} | |} | ||
− | + | See Also: | |
− | + | ||
− | + | ||
− | : | + | |
: [[Configuring%20a%20Descriptor%20(ELUG)|Configuring a Descriptor]] | : [[Configuring%20a%20Descriptor%20(ELUG)|Configuring a Descriptor]] | ||
: [[Configuring%20a%20Relational%20Project%20(ELUG)|Configuring Sequencing at the Project Level]] | : [[Configuring%20a%20Relational%20Project%20(ELUG)|Configuring Sequencing at the Project Level]] | ||
: [[Configuring%20a%20Database%20Login%20(ELUG)|Configuring Sequencing at the Session Level]] | : [[Configuring%20a%20Database%20Login%20(ELUG)|Configuring Sequencing at the Session Level]] | ||
+ | |||
===How to Configure Sequencing at the Descriptor Level Using Java=== | ===How to Configure Sequencing at the Descriptor Level Using Java=== | ||
Line 412: | Line 388: | ||
<span id="Example 28-1"></span> | <span id="Example 28-1"></span> | ||
''''' Example Sequences''''' | ''''' Example Sequences''''' | ||
+ | <source lang="java"> | ||
dbLogin.addSequence(new TableSequence("EMP_SEQ", 25)); | dbLogin.addSequence(new TableSequence("EMP_SEQ", 25)); | ||
dbLogin.addSequence(new DefaultSequence("PHONE_SEQ", 30)); | dbLogin.addSequence(new DefaultSequence("PHONE_SEQ", 30)); | ||
dbLogin.addSequence(new UnaryTableSequence("ADD_SEQ", 55)); | dbLogin.addSequence(new UnaryTableSequence("ADD_SEQ", 55)); | ||
dbLogin.addSequence(new NativeSequence("NAT_SEQ", 10)); | dbLogin.addSequence(new NativeSequence("NAT_SEQ", 10)); | ||
− | + | </source> | |
− | + | ||
Using Java code, you can perform the following sequence configurations: | Using Java code, you can perform the following sequence configurations: | ||
− | + | * [[#Configuring a Sequence by Name|Configuring a Sequence by Name]] | |
− | * [[#Configuring a Sequence by Name]] | + | * [[#Configuring the Same Sequence for Multiple Descriptors|Configuring the Same Sequence for Multiple Descriptors]] |
− | * [[#Configuring the Same Sequence for Multiple Descriptors]] | + | * [[#Configuring the Platform Default Sequence|Configuring the Platform Default Sequence]] |
− | * [[#Configuring the Platform Default Sequence]] | + | |
− | + | ||
====Configuring a Sequence by Name==== | ====Configuring a Sequence by Name==== | ||
− | + | As the [[#Example 28-2|Associating a Sequence with a Descriptor]] example shows, you associate a sequence with a descriptor by sequence name. The sequence <tt>EMP_SEQ</tt> was added to the login for this project in the [[#Example 28-1|Example Sequences]] example. When a new instance of the <tt>Employee</tt> class is created, the EclipseLink runtime will use the sequence named <tt>EMP_SEQ</tt> (in this example, a <tt>TableSequence</tt>) to obtain a value for the <tt>EMP_ID</tt> field. | |
− | As [[#Example 28-2|Associating a Sequence with a Descriptor]] shows, you associate a sequence with a descriptor by sequence name. The sequence <tt>EMP_SEQ</tt> was added to the login for this project in [[#Example 28-1]]. When a new instance of the <tt>Employee</tt> class is created, the EclipseLink runtime will use the sequence named <tt>EMP_SEQ</tt> (in this example, a <tt>TableSequence</tt>) to obtain a value for the <tt>EMP_ID</tt> field. | + | |
<span id="Example 28-2"></span> | <span id="Example 28-2"></span> | ||
''''' Associating a Sequence with a Descriptor''''' | ''''' Associating a Sequence with a Descriptor''''' | ||
− | empDescriptor.setSequenceNumberFieldName("EMP_ID"); | + | <source lang="java"> |
+ | empDescriptor.setSequenceNumberFieldName("EMP_ID"); // primary key field | ||
empDescriptor.setSequenceNumberName("EMP_SEQ"); | empDescriptor.setSequenceNumberName("EMP_SEQ"); | ||
+ | </source> | ||
====Configuring the Same Sequence for Multiple Descriptors==== | ====Configuring the Same Sequence for Multiple Descriptors==== | ||
− | + | As the [[#Example 28-3|Configuring a Sequence for Multiple Descriptors]] example shows, you can associate the same sequence with more than one descriptor. In this example, both the <tt>Employee</tt> descriptor and <tt>Phone</tt> descriptor use the same <tt>NativeSequence</tt>. Having descriptors share the same sequence can improve pre-allocation performance. For more information on pre-allocation, see [[Introduction%20to%20Relational%20Projects%20(ELUG)#Sequencing and Preallocation Size|Sequencing and Preallocation Size]]. | |
− | As [[#Example 28-3|Configuring a Sequence for Multiple Descriptors]] shows, you can associate the same sequence with more than one descriptor. In this example, both the <tt>Employee</tt> descriptor and <tt>Phone</tt> descriptor use the same <tt>NativeSequence</tt>. Having descriptors share the same sequence can improve pre-allocation performance. For more information on pre-allocation, see [[Introduction%20to%20Relational%20Projects%20(ELUG)|Sequencing and Preallocation Size]]. | + | |
<span id="Example 28-3"></span> | <span id="Example 28-3"></span> | ||
'''''Configuring a Sequence for Multiple Descriptors''''' | '''''Configuring a Sequence for Multiple Descriptors''''' | ||
− | + | <source lang="java"> | |
− | + | empDescriptor.setSequenceNumberFieldName("EMP_ID"); // primary key field | |
− | empDescriptor.setSequenceNumberFieldName("EMP_ID"); | + | |
empDescriptor.setSequenceNumberName("NAT_SEQ"); | empDescriptor.setSequenceNumberName("NAT_SEQ"); | ||
− | phoneDescriptor.setSequenceNumberFieldName("PHONE_ID"); | + | phoneDescriptor.setSequenceNumberFieldName("PHONE_ID"); // primary key field |
phoneDescriptor.setSequenceNumberName("NAT_SEQ"); | phoneDescriptor.setSequenceNumberName("NAT_SEQ"); | ||
− | + | </source> | |
− | + | ||
====Configuring the Platform Default Sequence==== | ====Configuring the Platform Default Sequence==== | ||
− | In [[#Example 28-4|Configuring a Default Sequence]], you associate a nonexistent sequence (<tt>NEW_SEQ</tt>) with a descriptor. Because you did not add a sequence named <tt>NEW_SEQ</tt> to the login for this project in [[#Example 28-1]], the EclipseLink runtime will create a <tt>DefaultSequence</tt> named <tt>NEW_SEQ</tt> for this descriptor. For more information about <tt>DefaultSequence</tt>, see [[Introduction%20to%20Relational%20Projects%20(ELUG)|Default Sequencing]]. | + | In the [[#Example 28-4|Configuring a Default Sequence]] exmple, you associate a nonexistent sequence (<tt>NEW_SEQ</tt>) with a descriptor. Because you did not add a sequence named <tt>NEW_SEQ</tt> to the login for this project in the [[#Example 28-1|Example Sequences]] example, the EclipseLink runtime will create a <tt>DefaultSequence</tt> named <tt>NEW_SEQ</tt> for this descriptor. For more information about <tt>DefaultSequence</tt>, see [[Introduction%20to%20Relational%20Projects%20(ELUG)#Default Sequencing|Default Sequencing]]. |
<span id="Example 28-4"></span> | <span id="Example 28-4"></span> | ||
''''' Configuring a Default Sequence''''' | ''''' Configuring a Default Sequence''''' | ||
− | descriptor.setSequenceNumberFieldName("EMP_ID"); | + | <source lang="java"> |
+ | descriptor.setSequenceNumberFieldName("EMP_ID"); // primary key field | ||
descriptor.setSequenceNumberName("NEW_SEQ"); | descriptor.setSequenceNumberName("NEW_SEQ"); | ||
+ | </source> | ||
− | |||
+ | ==Configuring Custom SQL Queries for Basic Persistence Operations== | ||
You can use EclipseLink to define an SQL query for each basic persistence operation (insert, update, delete, read-object, read-all, or does-exist) so that when you query and modify your relational-mapped objects, the EclipseLink runtime will use the appropriate SQL query instead of the default SQL query. | You can use EclipseLink to define an SQL query for each basic persistence operation (insert, update, delete, read-object, read-all, or does-exist) so that when you query and modify your relational-mapped objects, the EclipseLink runtime will use the appropriate SQL query instead of the default SQL query. | ||
Line 475: | Line 449: | ||
The read-all SQL string must return all instances of the class and thus can take no arguments. | The read-all SQL string must return all instances of the class and thus can take no arguments. | ||
− | You can define a custom SQL string for insert, update, delete, read-object, and read-all using the Workbench | + | You can define a custom SQL string for insert, update, delete, read-object, and read-all [[#How to Configure Custom SQL Queries for Basic Persistence Operations Using Workbench|using the Workbench]]. |
+ | |||
+ | You can define a custom SQL string or <tt>Call</tt> object for insert, update, delete, read-object, read-all, and does-exist [[#How to Configure Custom SQL Queries for Basic Persistence Operations Using Java|using Java]]. Using a <tt>Call</tt>, you can define more complex SQL strings and invoke custom stored procedures. | ||
− | |||
{| 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 492: | Line 467: | ||
''''''Note''''': EclipseLink does not validate the SQL code that you enter. Enter the SQL code appropriate for your database platform (see [[Introduction%20to%20Data%20Access%20(ELUG)|Data Source Platform Types]]). | ''''''Note''''': EclipseLink does not validate the SQL code that you enter. Enter the SQL code appropriate for your database platform (see [[Introduction%20to%20Data%20Access%20(ELUG)|Data Source Platform Types]]). | ||
|} | |} | ||
− | |||
Line 501: | Line 475: | ||
# In the '''Navigator''', select a descriptor in a relational database project. | # In the '''Navigator''', select a descriptor in a relational database project. | ||
# Click the '''Queries''' tab in the '''Editor'''. | # Click the '''Queries''' tab in the '''Editor'''. | ||
− | # Click the '''Custom SQL''' tab.<br>'''''Queries, Custom SQL Tab'''''<br>[[Image:qrsqltab.gif|Queries, Custom SQL Tab]] | + | # Click the '''Custom SQL''' tab.<br>'''''Queries, Custom SQL Tab'''''<br>[[Image:qrsqltab.gif|Queries, Custom SQL Tab]]<br> |
− | # Enter data on each tab on the | + | # Enter data on each tab on the Custom SQL tab. |
Click the appropriate SQL function tab and type your own SQL string to control these actions for a descriptor. Use the following information to complete the tab: | Click the appropriate SQL function tab and type your own SQL string to control these actions for a descriptor. Use the following information to complete the tab: | ||
− | |||
Line 528: | Line 501: | ||
| id="r5c1-t6" headers="r1c1-t6" align="left" | '''Read Object''' | | id="r5c1-t6" headers="r1c1-t6" align="left" | '''Read Object''' | ||
| headers="r5c1-t6 r1c2-t6" align="left" | | | headers="r5c1-t6 r1c2-t6" align="left" | | ||
− | Defines the read SQL that EclipseLink uses in any <tt>ReadObjectQuery</tt>, whose selection criteria is based on the object's primary key. When you define a descriptor's '''read-object''' query, your implementation overrides any <tt>ReadObjectQuery</tt>, whose selection criteria is based on the object's primary key. EclipseLink generates dynamic SQL for all other <tt>Session</tt> <tt>readObject</tt> method signatures.To customize other <tt>Session</tt> <tt>readObject</tt> method signatures, define additional named queries and use them in your application instead of the <tt>Session</tt> methods. | + | Defines the read SQL that EclipseLink uses in any <tt>ReadObjectQuery</tt>, whose selection criteria is based on the object's primary key. When you define a descriptor's '''read-object''' query, your implementation overrides any <tt>ReadObjectQuery</tt>, whose selection criteria is based on the object's primary key. EclipseLink generates dynamic SQL for all other <tt>Session</tt> <tt>readObject</tt> method signatures. |
+ | |||
+ | To customize other <tt>Session</tt> <tt>readObject</tt> method signatures, define additional named queries and use them in your application instead of the <tt>Session</tt> methods. | ||
|- align="left" valign="top" | |- align="left" valign="top" | ||
| id="r6c1-t6" headers="r1c1-t6" align="left" | '''Read All''' | | id="r6c1-t6" headers="r1c1-t6" align="left" | '''Read All''' | ||
| headers="r6c1-t6 r1c2-t6" align="left" | | | headers="r6c1-t6 r1c2-t6" align="left" | | ||
− | Defines the read-all SQL that EclipseLink uses when you call <tt>Session</tt> method <tt>readAllObjects(java.lang.Class)</tt> passing in the <tt>java.lang.Class</tt> that this descriptor represents. When you define a descriptor's '''read-all''' query, your implementation overrides only the <tt>Session</tt> method <tt>readAll(java.lang.Class)</tt>, not the version that takes a <tt>Class</tt> and <tt>Expression</tt>. As a result, this query reads every single instance. EclipseLink generates dynamic SQL for all other <tt>Session</tt> <tt>readAll</tt> method signatures.To customize other <tt>Session</tt> <tt>readAll</tt> method signatures, define additional named queries and use them in your application instead of the Session methods. | + | Defines the read-all SQL that EclipseLink uses when you call <tt>Session</tt> method <tt>readAllObjects(java.lang.Class)</tt> passing in the <tt>java.lang.Class</tt> that this descriptor represents. When you define a descriptor's '''read-all''' query, your implementation overrides only the <tt>Session</tt> method <tt>readAll(java.lang.Class)</tt>, not the version that takes a <tt>Class</tt> and <tt>Expression</tt>. As a result, this query reads every single instance. EclipseLink generates dynamic SQL for all other <tt>Session</tt> <tt>readAll</tt> method signatures. |
+ | |||
+ | To customize other <tt>Session</tt> <tt>readAll</tt> method signatures, define additional named queries and use them in your application instead of the Session methods. | ||
|} | |} | ||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
Line 645: | Line 616: | ||
− | + | The [[#Example 28-5|Configuring a Descriptor Query Manager with Custom SQL Strings]] example shows how to implement an amendment method to configure a descriptor query manager to use custom SQL strings. Alternatively, using an <tt>SQLCall</tt>, you can specify more complex SQL strings using features such as in, out, and in-out parameters and parameter types (see [[Using%20Basic%20Query%20API%20(ELUG)#Using a SQLCall|Using a SQLCall]]). | |
− | [[#Example 28-5|Configuring a Descriptor Query Manager with Custom SQL Strings]] shows how to implement an amendment method to configure a descriptor query manager to use custom SQL strings. Alternatively, using an <tt>SQLCall</tt>, you can specify more complex SQL strings using features such as in, out, and in-out parameters and parameter types (see [[Using%20Basic%20Query%20API%20(ELUG)|Using a SQLCall]]). | + | |
<span id="Example 28-5"></span> | <span id="Example 28-5"></span> | ||
''''' Configuring a Descriptor Query Manager with Custom SQL Strings''''' | ''''' Configuring a Descriptor Query Manager with Custom SQL Strings''''' | ||
+ | <source lang="java"> | ||
public static void addToDescriptor(ClassDescriptor descriptor) { | public static void addToDescriptor(ClassDescriptor descriptor) { | ||
− | + | // Read-object by primary key procedure | |
descriptor.getQueryManager().setReadObjectSQLString( | descriptor.getQueryManager().setReadObjectSQLString( | ||
− | + | "select * from EMP where EMP_ID = #EMP_ID"); | |
− | + | // Read-all instances procedure | |
− | descriptor.getQueryManager().setReadAllSQLString( | + | descriptor.getQueryManager().setReadAllSQLString("select * from EMP"); |
− | + | ||
− | + | // Insert procedure | |
descriptor.getQueryManager().setInsertSQLString( | descriptor.getQueryManager().setInsertSQLString( | ||
− | + | "insert into EMP (EMP_ID, F_NAME, L_NAME, MGR_ID) values | |
− | + | (#EMP_ID, #F_NAME, #L_NAME, #MGR_ID)"); | |
− | + | // Update procedure | |
descriptor.getQueryManager().setUpdateSQLString( | descriptor.getQueryManager().setUpdateSQLString( | ||
− | + | "update EMP set (F_NAME, L_NAME, MGR_ID) values | |
− | + | (#F_NAME, #L_NAME, #MGR_ID) where EMP_ID = #EMP_ID"); | |
} | } | ||
− | + | </source> | |
− | + | ||
− | + | ||
− | [[#Example 28-6|Configuring a Descriptor Query Manager with Custom Stored Procedure Calls]] shows how to implement an amendment method to configure a descriptor query manager to use Oracle stored procedures using a <tt>StoredProcedureCall</tt> (see [Using%20Basic%20Query%20API%20(ELUG)|Using a StoredProcedureCall]). This example uses output cursors to return the result set (see [[Using%20Advanced%20Query%20API%20(ELUG)|Handling Cursor and Stream Query Results]]). | + | The [[#Example 28-6|Configuring a Descriptor Query Manager with Custom Stored Procedure Calls]] example shows how to implement an amendment method to configure a descriptor query manager to use Oracle stored procedures using a <tt>StoredProcedureCall</tt> (see [[Using%20Basic%20Query%20API%20(ELUG)#Using a StoredProcedureCall|Using a StoredProcedureCall]]). This example uses output cursors to return the result set (see [[Using%20Advanced%20Query%20API%20(ELUG)#Handling Cursor and Stream Query Results|Handling Cursor and Stream Query Results]]). |
<span id="Example 28-6"></span> | <span id="Example 28-6"></span> | ||
''''' Configuring a Descriptor Query Manager with Custom Stored Procedure Calls''''' | ''''' Configuring a Descriptor Query Manager with Custom Stored Procedure Calls''''' | ||
+ | <source lang="java"> | ||
public static void addToDescriptor(ClassDescriptor descriptor) { | public static void addToDescriptor(ClassDescriptor descriptor) { | ||
− | + | // Read-object by primary key procedure | |
StoredProcedureCall readCall = new StoredProcedureCall(); | StoredProcedureCall readCall = new StoredProcedureCall(); | ||
readCall.setProcedureName("READ_EMP"); | readCall.setProcedureName("READ_EMP"); | ||
readCall.addNamedArgument("P_EMP_ID", "EMP_ID"); | readCall.addNamedArgument("P_EMP_ID", "EMP_ID"); | ||
− | + | readCall.useNamedCursorOutputAsResultSet("RESULT_CURSOR"); | |
− | + | descriptor.getQueryManager().setReadObjectCall(readCall); | |
− | + | // Read-all instances procedure | |
StoredProcedureCall readAllCall = new StoredProcedureCall(); | StoredProcedureCall readAllCall = new StoredProcedureCall(); | ||
readAllCall.setProcedureName("READ_ALL_EMP"); | readAllCall.setProcedureName("READ_ALL_EMP"); | ||
readAllCall.useNamedCursorOutputAsResultSet("RESULT_CURSOR"); | readAllCall.useNamedCursorOutputAsResultSet("RESULT_CURSOR"); | ||
− | + | descriptor.getQueryManager().setReadAllCall(readAllCall ); | |
− | + | // Insert procedure | |
StoredProcedureCall insertCall = new StoredProcedureCall(); | StoredProcedureCall insertCall = new StoredProcedureCall(); | ||
insertCall.setProcedureName("INSERT_EMP"); | insertCall.setProcedureName("INSERT_EMP"); | ||
Line 704: | Line 673: | ||
descriptor.getQueryManager().setInsertCall(insertCall); | descriptor.getQueryManager().setInsertCall(insertCall); | ||
− | + | // Update procedure | |
StoredProcedureCall updateCall = new StoredProcedureCall(); | StoredProcedureCall updateCall = new StoredProcedureCall(); | ||
− | + | updateCall.setProcedureName("UPDATE_EMP"); | |
updateCall.addNamedArgument("P_EMP_ID", "EMP_ID"); | updateCall.addNamedArgument("P_EMP_ID", "EMP_ID"); | ||
updateCall.addNamedArgument("P_F_NAME", "F_NAME"); | updateCall.addNamedArgument("P_F_NAME", "F_NAME"); | ||
Line 713: | Line 682: | ||
descriptor.getQueryManager().setUpdateCall(updateCall); | descriptor.getQueryManager().setUpdateCall(updateCall); | ||
} | } | ||
− | + | </source> | |
==Configuring Interface Alias== | ==Configuring Interface Alias== | ||
− | + | An interface alias allows an interface to be used to refer to a descriptor instead of the implementation class. This can be useful for classes that have public interface and the applications desire to refer to the class using the public interface. Specifying the interface alias allows any queries executed on an EclipseLink session to use the interface as the reference class instead of the implementation class. | |
− | An interface alias allows an interface to be used to refer to a descriptor instead of the implementation class. This can be useful for classes that have public interface and the applications desire to refer to the class using the public interface. Specifying the interface alias allows any queries executed on | + | |
Each descriptor can have one interface alias. Use the interface in queries and relationship mappings. | Each descriptor can have one interface alias. Use the interface in queries and relationship mappings. | ||
− | |||
{| 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 use an interface alias, do not associate an interface descriptor with the interface. | |
|} | |} | ||
− | |||
This section includes information on configuring an interface alias. Interfaces cannot be ''created'' in the Workbench; you must add the Java package or class to your Workbench project before configuring it. | This section includes information on configuring an interface alias. Interfaces cannot be ''created'' in the Workbench; you must add the Java package or class to your Workbench project before configuring it. | ||
− | |||
===How to Configure Interface Alias Using Workbench=== | ===How to Configure Interface Alias Using Workbench=== | ||
− | |||
To specify an interface alias, use this procedure: | To specify an interface alias, use this procedure: | ||
− | |||
# In the '''Navigator''', select a descriptor.If the '''Interface Alias''' advanced property is not visible for the descriptor, right-click the descriptor and choose '''Select Advanced Properties''' > '''Interface Alias''' from context menu or from the Selected menu. | # In the '''Navigator''', select a descriptor.If the '''Interface Alias''' advanced property is not visible for the descriptor, right-click the descriptor and choose '''Select Advanced Properties''' > '''Interface Alias''' from context menu or from the Selected menu. | ||
− | # Click the '''Interface Alias''' tab.'''''<br>Interface Alias Tab'''''<br>[[Image:intralis.gif|Interface Alias Tab] | + | # Click the '''Interface Alias''' tab.'''''<br>Interface Alias Tab'''''<br>[[Image:intralis.gif|Interface Alias Tab]] |
− | + | # In the '''Interface Alias''' field, click '''Browse''' and select an interface. | |
− | In the '''Interface Alias''' field, click '''Browse''' and select an interface. | + | |
− | + | See Also: | |
: [[Configuring%20a%20Descriptor%20(ELUG)|Configuring a Descriptor]] | : [[Configuring%20a%20Descriptor%20(ELUG)|Configuring a Descriptor]] | ||
: [[Creating%20a%20Descriptor%20(ELUG)|Creating a Descriptor]] | : [[Creating%20a%20Descriptor%20(ELUG)|Creating a Descriptor]] | ||
: [[Introduction%20to%20Descriptors%20(ELUG)|Introduction to Descriptors]] | : [[Introduction%20to%20Descriptors%20(ELUG)|Introduction to Descriptors]] | ||
− | |||
===How to Configure Interface Alias Using Java=== | ===How to Configure Interface Alias Using Java=== | ||
− | + | To configure a descriptor with an interface alias using Java, create an amendment method (see [[Configuring%20a%20Descriptor%20(ELUG)#Configuring Amendment Methods|Configuring Amendment Methods]]) and use <tt>InterfacePolicy</tt> method <tt>addParentInterface</tt> as this example shows. | |
− | To configure a descriptor with an interface alias using Java, create an amendment method (see [[Configuring%20a%20Descriptor%20(ELUG)|Configuring Amendment Methods]]) and use <tt>InterfacePolicy</tt> method <tt>addParentInterface</tt> as this example shows. | + | |
<span id="Example 28-7"></span> | <span id="Example 28-7"></span> | ||
''''' Configuring an Interface Alias''''' | ''''' Configuring an Interface Alias''''' | ||
+ | <source lang="java"> | ||
public static void addToDescriptor(Descriptor descriptor) { | public static void addToDescriptor(Descriptor descriptor) { | ||
descriptor.getInterfacePolicy().addParentInterface(MyInterface.class); | descriptor.getInterfacePolicy().addParentInterface(MyInterface.class); | ||
} | } | ||
− | + | </source> | |
==Configuring a Relational Descriptor as a Class or Aggregate Type== | ==Configuring a Relational Descriptor as a Class or Aggregate Type== | ||
+ | By default, when you add a Java class to a relational project (see [[Configuring%20a%20Project%20(ELUG)#Configuring Project Classpath|Configuring Project Classpath]]), Workbench create a relational class descriptor for it. A class descriptor is applicable to any persistent object except an object that is owned by another in an aggregate relationship. In this case, you must describe the owned object with an aggregate descriptor. Using a class descriptor, you can configure any relational mapping except aggregate collection and aggregate object mappings. | ||
− | + | An aggregate object is an object that is strictly dependent on its owning object. Aggregate descriptors do not define a table, primary key, or many of the standard descriptor options as they obtain these from their owning descriptor. If you want to configure an aggregate mapping to associate data members in a target object with fields in a source object's underlying database tables (see [[Configuring%20a%20Relational%20Aggregate%20Collection%20Mapping%20(ELUG)|Configuring a Relational Aggregate Collection Mapping]] and [[Configuring%20a%20Relational%20Aggregate%20Object%20Mapping (ELUG)|Configuring a Relational Aggregate Object Mapping]]), you must designate the target object's descriptor as an aggregate. | |
− | + | ||
− | An aggregate object is an object that is strictly dependent on its owning object. Aggregate descriptors do not define a table, primary key, or many of the standard descriptor options as they obtain these from their owning descriptor. If you want to configure an aggregate mapping to associate data members in a target object with fields in a source object's underlying database tables (see [[Configuring%20a%20Relational%20Aggregate%20Collection%20Mapping%20(ELUG)| | + | |
Alternatively, you can remove the aggregate designation from a relational descriptor and return it to its default type. | Alternatively, you can remove the aggregate designation from a relational descriptor and return it to its default type. | ||
− | You can configure inheritance for a descriptor designated as an aggregate (see [[Configuring%20a%20Descriptor%20(ELUG)|Configuring Inheritance for a Child (Branch or Leaf) Class Descriptor]]), however, in this case, ''all'' the descriptors in the inheritance tree must be aggregates. Aggregate and class descriptors cannot exist in the same inheritance tree. For more information, see [[Introduction%20to%20Descriptors%20(ELUG) | + | You can configure inheritance for a descriptor designated as an aggregate (see [[Configuring%20a%20Descriptor%20(ELUG)#Configuring Inheritance for a Child (Branch or Leaf) Class Descriptor|Configuring Inheritance for a Child (Branch or Leaf) Class Descriptor]]), however, in this case, ''all'' the descriptors in the inheritance tree must be aggregates. Aggregate and class descriptors cannot exist in the same inheritance tree. For more information, see [[Introduction%20to%20Descriptors%20(ELUG)#Aggregate and Composite Descriptors and Inheritance|Aggregate and Composite Descriptors and Inheritance]]. |
− | + | ||
− | + | ||
+ | For more information, see [[Introduction%20to%20XML%20Descriptors%20(ELUG)#XML Descriptors and Aggregation|XML Descriptors and Aggregation]]. | ||
===How to Configure a Relational Descriptor as a Class or Aggregate Type Using Workbench=== | ===How to Configure a Relational Descriptor as a Class or Aggregate Type Using Workbench=== | ||
− | |||
To configure a relational descriptor as class or aggregate, use this procedure. | To configure a relational descriptor as class or aggregate, use this procedure. | ||
− | |||
# In the '''Navigator''', select a relational descriptor. | # In the '''Navigator''', select a relational descriptor. | ||
− | # Click the '''Class''' or '''Aggregate''' descriptor button on the mapping toolbar.You can also select the descriptor and choose '''Selected''' > '''Descriptor Type''' > '''Class''' or '''Aggregate''' from the menu or by right-clicking on the descriptor in the '''Navigator''' window and selecting '''Descriptor Type''' > '''Class''' or '''Aggregate''' from the context menu. | + | # Click the '''Class''' or '''Aggregate''' descriptor button on the mapping toolbar.<br>You can also select the descriptor and choose '''Selected''' > '''Descriptor Type''' > '''Class''' or '''Aggregate''' from the menu or by right-clicking on the descriptor in the '''Navigator''' window and selecting '''Descriptor Type''' > '''Class''' or '''Aggregate''' from the context menu. |
− | # [[Image:dtfmpbtn.gif|Direct to Field Mapping button]] If you select '''Aggregate''', specify each of the aggregate descriptor's attributes as a direct to field mapping. See [[Configuring%20a%20Relational%20Direct-to-Field% | + | # [[Image:dtfmpbtn.gif|Direct to Field Mapping button]] If you select '''Aggregate''', specify each of the aggregate descriptor's attributes as a direct to field mapping. See [[Configuring%20a%20Relational%20Direct-to-Field%20Mapping (ELUG)|Configuring a Relational Direct-to-Field Mapping]] for more information. |
− | [[Image:dtfmpbtn.gif|Direct to Field Mapping button]] Specify each of the aggregate descriptor's attributes as a direct to field mapping. See [[Configuring%20a%20Relational%20Direct-to-Field% | + | [[Image:dtfmpbtn.gif|Direct to Field Mapping button]] Specify each of the aggregate descriptor's attributes as a direct to field mapping. See [[Configuring%20a%20Relational%20Direct-to-Field%20Mapping (ELUG)|Configuring a Relational Direct-to-Field Mapping]] for more information. |
− | Although the attributes of a target class are not mapped directly to a data source until you configure an aggregate object mapping, you must still specify their mapping type in the target class's descriptor. This tells EclipseLink what type of mapping to use when you do configure the aggregate mapping in the source object's descriptor. For more information, see [[Introduction%20to%20Relational%20Descriptors%20(ELUG)|Aggregate and Composite Descriptors in Relational Projects]]. | + | Although the attributes of a target class are not mapped directly to a data source until you configure an aggregate object mapping, you must still specify their mapping type in the target class's descriptor. This tells EclipseLink what type of mapping to use when you do configure the aggregate mapping in the source object's descriptor. For more information, see [[Introduction%20to%20Relational%20Descriptors%20(ELUG)#Aggregate and Composite Descriptors in Relational Projects|Aggregate and Composite Descriptors in Relational Projects]]. |
− | + | See Also: | |
: [[Configuring%20a%20Descriptor%20(ELUG)|Configuring a Descriptor]] | : [[Configuring%20a%20Descriptor%20(ELUG)|Configuring a Descriptor]] | ||
− | : [[#Configuring a Relational Descriptor as a Class or Aggregate Type]] | + | : [[#Configuring a Relational Descriptor as a Class or Aggregate Type|Configuring a Relational Descriptor as a Class or Aggregate Type]] |
− | |||
+ | ===How to Configure a Relational Descriptor as a Class or Aggregate Type Using Java=== | ||
Using Java, to configure a relational descriptor as an aggregate, use <tt>ClassDescriptor</tt> method <tt>descriptorIsAggregate</tt>. | Using Java, to configure a relational descriptor as an aggregate, use <tt>ClassDescriptor</tt> method <tt>descriptorIsAggregate</tt>. | ||
Line 803: | Line 760: | ||
To configure a relational descriptor as a nonaggregate, use <tt>ClassDescriptor</tt> method <tt>descriptorIsNormal</tt>. | To configure a relational descriptor as a nonaggregate, use <tt>ClassDescriptor</tt> method <tt>descriptorIsNormal</tt>. | ||
− | |||
− | |||
+ | ==Configuring Multitable Information== | ||
+ | Descriptors can use multiple tables in mappings. Use multiple tables when either of the following occurs: | ||
* A subclass is involved in inheritance, and its superclass is mapped to one table, while the subclass has additional attributes that are mapped to a second table. | * A subclass is involved in inheritance, and its superclass is mapped to one table, while the subclass has additional attributes that are mapped to a second table. | ||
* A class is not involved in inheritance and its data is spread out across multiple tables. | * A class is not involved in inheritance and its data is spread out across multiple tables. | ||
− | When a descriptor has multiple tables, you must be able to join a row from the primary table to all the additional tables. By default, EclipseLink assumes that the primary key of the first, or primary, table is included in the additional tables, thereby joining the tables. EclipseLink also supports custom methods for joining tables. If the primary key field names of the multiple tables do not match, a foreign key can be used to join the tables. The foreign key can either be from the primary table to the secondary table, or from the secondary table to the primary table, or between two of the secondary tables (see [[#How to Configure Multitable Information Using Workbench | + | When a descriptor has multiple tables, you must be able to join a row from the primary table to all the additional tables. By default, EclipseLink assumes that the primary key of the first, or primary, table is included in the additional tables, thereby joining the tables. EclipseLink also supports custom methods for joining tables. If the primary key field names of the multiple tables do not match, a foreign key can be used to join the tables. The foreign key can either be from the primary table to the secondary table, or from the secondary table to the primary table, or between two of the secondary tables (see [[#How to Configure Multitable Information Using Workbench|How to Configure Multitable Information Using Workbench]]). |
− | + | ||
− | + | ||
+ | For complex multitable situations, a more complex join expression may be required. These include requiring the join to also check a type code, or using an outer-join. EclipseLink provides support for a multiple-table-join-expression for these cases (see [[#How to Configure Multitable Information Using Java|How to Configure Multitable Information Using Java]]). | ||
===How to Configure Multitable Information Using Workbench=== | ===How to Configure Multitable Information Using Workbench=== | ||
− | |||
To associate multiple tables with a descriptor, use this procedure. | To associate multiple tables with a descriptor, use this procedure. | ||
# In the '''Navigator''', select a descriptor.If the '''Multitable Info''' advanced property is not visible for the descriptor, right-click the descriptor and choose '''Select Advanced Properties''' > '''Multitable Info''' from the context menu or from the '''Selected''' menu. | # In the '''Navigator''', select a descriptor.If the '''Multitable Info''' advanced property is not visible for the descriptor, right-click the descriptor and choose '''Select Advanced Properties''' > '''Multitable Info''' from the context menu or from the '''Selected''' menu. | ||
# Click the '''Multitable Info''' tab.<br>'''''Multitable Info Tab'''''<br>[[Image:multiinf.gif|Multitable Info Tab]] | # Click the '''Multitable Info''' tab.<br>'''''Multitable Info Tab'''''<br>[[Image:multiinf.gif|Multitable Info Tab]] | ||
− | # Complete each field on the | + | # Complete each field on the '''Multitable Info''' tab. |
Use the following information to enter data in each field of the tab: | Use the following information to enter data in each field of the tab: | ||
− | |||
{| class="HRuleInformal" dir="ltr" title="This table defines each field on the Multitable Info tab." summary="This table defines each field on the Multitable Info tab." width="100%" border="1" frame="hsides" rules="rows" cellpadding="3" frame="hsides" rules="rows" | {| class="HRuleInformal" dir="ltr" title="This table defines each field on the Multitable Info tab." summary="This table defines each field on the Multitable Info tab." width="100%" border="1" frame="hsides" rules="rows" cellpadding="3" frame="hsides" rules="rows" | ||
|- align="left" valign="top" | |- align="left" valign="top" | ||
Line 841: | Line 795: | ||
Specify how each '''Additional Table''' is associated to the '''Primary Table'''<nowiki>: </nowiki> | Specify how each '''Additional Table''' is associated to the '''Primary Table'''<nowiki>: </nowiki> | ||
* '''Primary Keys Have Same Names'''–when associating tables by identically named primary keys, EclipseLink requires no additional configuration. | * '''Primary Keys Have Same Names'''–when associating tables by identically named primary keys, EclipseLink requires no additional configuration. | ||
− | * '''Reference'''–when associating an additional table to the primary table with a '''Reference''' (that is, a foreign key), you can specify the '''Table Reference''', as well as the '''Source''' and '''Target''' fields. Continue with [[#Associating Tables with References]]. | + | * '''Reference'''–when associating an additional table to the primary table with a '''Reference''' (that is, a foreign key), you can specify the '''Table Reference''', as well as the '''Source''' and '''Target''' fields. Continue with [[#Associating Tables with References|Associating Tables with References]]. |
|} | |} | ||
− | |||
Line 857: | Line 810: | ||
Choose a '''Table Reference''' that defines how the primary keys of the primary table relate to the primary keys of the selected table. Click '''Add''' to add a primary key association. | Choose a '''Table Reference''' that defines how the primary keys of the primary table relate to the primary keys of the selected table. Click '''Add''' to add a primary key association. | ||
− | |||
− | |||
− | |||
− | |||
===How to Configure Multitable Information Using Java=== | ===How to Configure Multitable Information Using Java=== | ||
− | |||
Using Java, configure a descriptor with multitable information using the following <tt>org.eclipse.persistence.descriptors.ClassDescriptor</tt> methods: | Using Java, configure a descriptor with multitable information using the following <tt>org.eclipse.persistence.descriptors.ClassDescriptor</tt> methods: | ||
− | |||
* <tt>addTableName(java.lang.String tableName)</tt> | * <tt>addTableName(java.lang.String tableName)</tt> | ||
* <tt>addForeignKeyFieldNameForMultipleTable(java.lang.String sourceForeignKeyFieldName, java.lang.String targetPrimaryKeyFieldName)</tt> | * <tt>addForeignKeyFieldNameForMultipleTable(java.lang.String sourceForeignKeyFieldName, java.lang.String targetPrimaryKeyFieldName)</tt> | ||
− | To specify a complex multiple-table-join-expression, create a descriptor amendment method (see [[Configuring%20a%20Descriptor%20(ELUG)|Configuring Amendment Methods]]) and add the join expression using <tt>org.eclipse.persistence.descriptors.DescriptorQueryManager</tt> method <tt>setMultipleTableJoinExpression</tt>. For more information, see [[Using%20Advanced%20Query%20API%20(ELUG)|Appending Additional Join Expressions]]. | + | To specify a complex multiple-table-join-expression, create a descriptor amendment method (see [[Configuring%20a%20Descriptor%20(ELUG)#Configuring Amendment Methods|Configuring Amendment Methods]]) and add the join expression using <tt>org.eclipse.persistence.descriptors.DescriptorQueryManager</tt> method <tt>setMultipleTableJoinExpression</tt>. For more information, see [[Using%20Advanced%20Query%20API%20(ELUG)#Appending Additional Join Expressions|Appending Additional Join Expressions]]. |
Line 882: | Line 829: | ||
[[Category: Task]] | [[Category: Task]] | ||
[[Category: Concept]] | [[Category: Concept]] | ||
+ | [[Category: ORM]] |
Latest revision as of 09:40, 20 May 2009
Contents
For information on how to create relational descriptors, see Creating a Relational Descriptor.
This table lists the default configurable options for a relational descriptor.
Option to Configure | Workbench | Java |
---|---|---|
For more information, see Introduction to Relational Descriptors.
Configuring Associated Tables
Each relational class descriptor (see Creating Relational Class Descriptors) must be associated with a database table for storing instances of that class. This does not apply to relational aggregate descriptors (see Creating Relational Aggregate Descriptors).
How to Configure Associated Tables Using Workbench
To associate a descriptor with a database table, use this procedure:
- Select a descriptor in the Navigator. Its properties appear in the Editor.
- Click the Descriptor Info tab. The Descriptor Info tab appears.
Descriptor Info Tab, Associated Table Options - Use the Associated Table list to select a database table for the descriptor. You must associate a descriptor with a database table before specifying primary keys.
See Also:
How to Configure Associated Tables Using Java
To configure a descriptor's associated table(s) using Java, use RelationalDescriptor methods setTableName or addTableName.
Configuring Sequencing at the Descriptor Level
Sequencing allows EclipseLink to automatically assign the primary key or ID of an object when the object is inserted.
You configure EclipseLink sequencing at the project level or session level to tell EclipseLink how to obtain sequence values: that is, what type of sequences to use.
To enable sequencing, you must then configure EclipseLink sequencing at the descriptor level to tell EclipseLink into which table and column to write the sequence value when an instance of a descriptor's reference class is created.
Only descriptors that have been configured with a sequence field and a sequence name will be assigned sequence numbers.
The sequence field is the database field that the sequence number will be assigned to: this is almost always the primary key field. The sequence name is the name of the sequence to be used for this descriptor. The purpose of the sequence name depends on the type of sequencing you are using:
When using table sequencing, the sequence name refers to the row's SEQ_NAME value used to store this sequence.
When using Oracle native sequencing, the sequence name refers to the Oracle sequence object that has been created in the database. When using native sequencing on other databases, the sequence name does not have any direct meaning, but should still be set for compatibility.
The sequence name can also refer to a custom sequence defined in the project.
For more information, see Sequencing in Relational Projects.
How to Configure Sequencing at the Descriptor Level Using Workbench
To configure sequencing for a descriptor, use this procedure:
- Select a descriptor in the Navigator. Its properties appear in the Editor.
- Click the Descriptor Info tab. The Descriptor Info tab appears.
Descriptor Info Tab, Sequencing Options - Complete the Sequencing options on the tab.
Use the following information to specify sequencing options:
Field | Description |
---|---|
Use Sequencing | Specify if this descriptor uses sequencing. If selected, specify the Name, Table, and Field for sequencing. |
|
Enter the name of the sequence.
|
|
Specify the name of the database table that contains the field (see Field) into which EclipseLink is to write the sequence value when a new instance of this descriptor's reference class is created. This is almost always this descriptor's primary table. |
|
Specify the name of the field in the specified table (see Table) into which EclipseLink is to write the sequence value when a new instance of this descriptor's reference class is created. This field is almost always the class's primary key (see Configuring Primary Keys).
|
See Also:
- Configuring a Descriptor
- Configuring Sequencing at the Project Level
- Configuring Sequencing at the Session Level
How to Configure Sequencing at the Descriptor Level Using Java
Using Java, you can configure sequencing to use multiple different types of sequence for different descriptors. You configure the sequence objects on the session's login and reference them from the descriptor by their name. The descriptor's sequence name refers to the sequence object's name you register in the session's login.
The following examples assume the session sequence configuration shown in this example:
Example Sequences
dbLogin.addSequence(new TableSequence("EMP_SEQ", 25)); dbLogin.addSequence(new DefaultSequence("PHONE_SEQ", 30)); dbLogin.addSequence(new UnaryTableSequence("ADD_SEQ", 55)); dbLogin.addSequence(new NativeSequence("NAT_SEQ", 10));
Using Java code, you can perform the following sequence configurations:
- Configuring a Sequence by Name
- Configuring the Same Sequence for Multiple Descriptors
- Configuring the Platform Default Sequence
Configuring a Sequence by Name
As the Associating a Sequence with a Descriptor example shows, you associate a sequence with a descriptor by sequence name. The sequence EMP_SEQ was added to the login for this project in the Example Sequences example. When a new instance of the Employee class is created, the EclipseLink runtime will use the sequence named EMP_SEQ (in this example, a TableSequence) to obtain a value for the EMP_ID field.
Associating a Sequence with a Descriptor
empDescriptor.setSequenceNumberFieldName("EMP_ID"); // primary key field empDescriptor.setSequenceNumberName("EMP_SEQ");
Configuring the Same Sequence for Multiple Descriptors
As the Configuring a Sequence for Multiple Descriptors example shows, you can associate the same sequence with more than one descriptor. In this example, both the Employee descriptor and Phone descriptor use the same NativeSequence. Having descriptors share the same sequence can improve pre-allocation performance. For more information on pre-allocation, see Sequencing and Preallocation Size.
Configuring a Sequence for Multiple Descriptors
empDescriptor.setSequenceNumberFieldName("EMP_ID"); // primary key field empDescriptor.setSequenceNumberName("NAT_SEQ"); phoneDescriptor.setSequenceNumberFieldName("PHONE_ID"); // primary key field phoneDescriptor.setSequenceNumberName("NAT_SEQ");
Configuring the Platform Default Sequence
In the Configuring a Default Sequence exmple, you associate a nonexistent sequence (NEW_SEQ) with a descriptor. Because you did not add a sequence named NEW_SEQ to the login for this project in the Example Sequences example, the EclipseLink runtime will create a DefaultSequence named NEW_SEQ for this descriptor. For more information about DefaultSequence, see Default Sequencing.
Configuring a Default Sequence
descriptor.setSequenceNumberFieldName("EMP_ID"); // primary key field descriptor.setSequenceNumberName("NEW_SEQ");
Configuring Custom SQL Queries for Basic Persistence Operations
You can use EclipseLink to define an SQL query for each basic persistence operation (insert, update, delete, read-object, read-all, or does-exist) so that when you query and modify your relational-mapped objects, the EclipseLink runtime will use the appropriate SQL query instead of the default SQL query.
SQL strings can include any fields that the descriptor maps, as well as arguments. You specify arguments in the SQL string using #<arg-name>, such as:
select * from EMP where EMP_ID = #EMP_ID
The insert and update SQL strings can take any field that the descriptor maps as an argument.
The read-object, delete and does-exist SQL strings can only take the primary key fields as arguments.
The read-all SQL string must return all instances of the class and thus can take no arguments.
You can define a custom SQL string for insert, update, delete, read-object, and read-all using the Workbench.
You can define a custom SQL string or Call object for insert, update, delete, read-object, read-all, and does-exist using Java. Using a Call, you can define more complex SQL strings and invoke custom stored procedures.
Note: When you customize the update persistence operation for an application that uses optimistic locking (see Configuring Locking Policy), the custom update string must not write the object if the row version field has changed since the initial object was read. In addition, it must increment the version field if it writes the object successfully. For example: update Employee set F_NAME = #F_NAME, VERSION = VERSION + 1 where (EMP_ID = #EMP_ID) AND (VERSION = #VERSION) The update string must also maintain the row count of the database. |
'Note: EclipseLink does not validate the SQL code that you enter. Enter the SQL code appropriate for your database platform (see Data Source Platform Types). |
How to Configure Custom SQL Queries for Basic Persistence Operations Using Workbench
To configure custom SQL queries for basic persistence operations:
- In the Navigator, select a descriptor in a relational database project.
- Click the Queries tab in the Editor.
- Click the Custom SQL tab.
Queries, Custom SQL Tab - Enter data on each tab on the Custom SQL tab.
Click the appropriate SQL function tab and type your own SQL string to control these actions for a descriptor. Use the following information to complete the tab:
Tab | Description |
---|---|
Insert | Defines the insert SQL that EclipseLink uses to insert a new object's data into the database. |
Update |
Defines the update SQL that EclipseLink uses to update any changed existing object's data in the database. When you define a descriptor's update query, you must conform to the following:
|
Delete | Defines the delete SQL that EclipseLink uses to delete an object. |
Read Object |
Defines the read SQL that EclipseLink uses in any ReadObjectQuery, whose selection criteria is based on the object's primary key. When you define a descriptor's read-object query, your implementation overrides any ReadObjectQuery, whose selection criteria is based on the object's primary key. EclipseLink generates dynamic SQL for all other Session readObject method signatures. To customize other Session readObject method signatures, define additional named queries and use them in your application instead of the Session methods. |
Read All |
Defines the read-all SQL that EclipseLink uses when you call Session method readAllObjects(java.lang.Class) passing in the java.lang.Class that this descriptor represents. When you define a descriptor's read-all query, your implementation overrides only the Session method readAll(java.lang.Class), not the version that takes a Class and Expression. As a result, this query reads every single instance. EclipseLink generates dynamic SQL for all other Session readAll method signatures. To customize other Session readAll method signatures, define additional named queries and use them in your application instead of the Session methods. |
How to Configure Custom SQL Queries for Basic Persistence Operations Using Java
The DescriptorQueryManager generates default SQL for the following persistence operations:
- Insert
- Update
- Delete
- Read-object
- Read-all
- Does-exist
Using Java code, you can use the descriptor query manager to provide custom SQL strings to perform these functions on a class-by-class basis.
Use ClassDescriptor method getQueryManager to acquire the DescriptorQueryManager, and then use the DescriptorQueryManager methods that this table lists.
Descriptor Query Manager Methods for Configuring Custom SQL
To Change the Default SQL for... | Use Descriptor Query Manager Method... |
---|---|
Insert |
setInsertQuery (InsertObjectQuery query) |
setInsertSQLString (String sqlString) | |
setInsertCall(Call call) | |
Update |
setUpdateQuery (UpdateObjectQuery query) |
setUpdateSQLString (String sqlString) | |
setUpdateCall(Call call) | |
Delete |
setDeleteQuery (DeleteObjectQuery query) |
setDeleteSQLString (String sqlString) | |
setDeleteCall(Call call) | |
Read |
setReadObjectQuery (ReadObjectQuery query) |
setReadObjectSQLString (String sqlString) | |
setReadObjectCall(Call call) | |
Read all |
setReadAllQuery (ReadAllQuery query) |
setReadAllSQLString (String sqlString) | |
setReadAllCall(Call call) | |
Does exist |
setDoesExistQuery(DoesExistQuery query) |
setDoesExistSQLString(String sqlString) | |
setDoesExistCall(Call call) |
The Configuring a Descriptor Query Manager with Custom SQL Strings example shows how to implement an amendment method to configure a descriptor query manager to use custom SQL strings. Alternatively, using an SQLCall, you can specify more complex SQL strings using features such as in, out, and in-out parameters and parameter types (see Using a SQLCall).
Configuring a Descriptor Query Manager with Custom SQL Strings
public static void addToDescriptor(ClassDescriptor descriptor) { // Read-object by primary key procedure descriptor.getQueryManager().setReadObjectSQLString( "select * from EMP where EMP_ID = #EMP_ID"); // Read-all instances procedure descriptor.getQueryManager().setReadAllSQLString("select * from EMP"); // Insert procedure descriptor.getQueryManager().setInsertSQLString( "insert into EMP (EMP_ID, F_NAME, L_NAME, MGR_ID) values (#EMP_ID, #F_NAME, #L_NAME, #MGR_ID)"); // Update procedure descriptor.getQueryManager().setUpdateSQLString( "update EMP set (F_NAME, L_NAME, MGR_ID) values (#F_NAME, #L_NAME, #MGR_ID) where EMP_ID = #EMP_ID"); }
The Configuring a Descriptor Query Manager with Custom Stored Procedure Calls example shows how to implement an amendment method to configure a descriptor query manager to use Oracle stored procedures using a StoredProcedureCall (see Using a StoredProcedureCall). This example uses output cursors to return the result set (see Handling Cursor and Stream Query Results).
Configuring a Descriptor Query Manager with Custom Stored Procedure Calls
public static void addToDescriptor(ClassDescriptor descriptor) { // Read-object by primary key procedure StoredProcedureCall readCall = new StoredProcedureCall(); readCall.setProcedureName("READ_EMP"); readCall.addNamedArgument("P_EMP_ID", "EMP_ID"); readCall.useNamedCursorOutputAsResultSet("RESULT_CURSOR"); descriptor.getQueryManager().setReadObjectCall(readCall); // Read-all instances procedure StoredProcedureCall readAllCall = new StoredProcedureCall(); readAllCall.setProcedureName("READ_ALL_EMP"); readAllCall.useNamedCursorOutputAsResultSet("RESULT_CURSOR"); descriptor.getQueryManager().setReadAllCall(readAllCall ); // Insert procedure StoredProcedureCall insertCall = new StoredProcedureCall(); insertCall.setProcedureName("INSERT_EMP"); insertCall.addNamedArgument("P_EMP_ID", "EMP_ID"); insertCall.addNamedArgument("P_F_NAME", "F_NAME"); insertCall.addNamedArgument("P_L_NAME", "L_NAME"); insertCall.addNamedArgument("P_MGR_ID", "MGR_ID"); descriptor.getQueryManager().setInsertCall(insertCall); // Update procedure StoredProcedureCall updateCall = new StoredProcedureCall(); updateCall.setProcedureName("UPDATE_EMP"); updateCall.addNamedArgument("P_EMP_ID", "EMP_ID"); updateCall.addNamedArgument("P_F_NAME", "F_NAME"); updateCall.addNamedArgument("P_L_NAME", "L_NAME"); updateCall.addNamedArgument("P_MGR_ID", "MGR_ID"); descriptor.getQueryManager().setUpdateCall(updateCall); }
Configuring Interface Alias
An interface alias allows an interface to be used to refer to a descriptor instead of the implementation class. This can be useful for classes that have public interface and the applications desire to refer to the class using the public interface. Specifying the interface alias allows any queries executed on an EclipseLink session to use the interface as the reference class instead of the implementation class.
Each descriptor can have one interface alias. Use the interface in queries and relationship mappings.
Note: If you use an interface alias, do not associate an interface descriptor with the interface. |
This section includes information on configuring an interface alias. Interfaces cannot be created in the Workbench; you must add the Java package or class to your Workbench project before configuring it.
How to Configure Interface Alias Using Workbench
To specify an interface alias, use this procedure:
- In the Navigator, select a descriptor.If the Interface Alias advanced property is not visible for the descriptor, right-click the descriptor and choose Select Advanced Properties > Interface Alias from context menu or from the Selected menu.
- Click the Interface Alias tab.
Interface Alias Tab - In the Interface Alias field, click Browse and select an interface.
See Also:
How to Configure Interface Alias Using Java
To configure a descriptor with an interface alias using Java, create an amendment method (see Configuring Amendment Methods) and use InterfacePolicy method addParentInterface as this example shows.
Configuring an Interface Alias
public static void addToDescriptor(Descriptor descriptor) { descriptor.getInterfacePolicy().addParentInterface(MyInterface.class); }
Configuring a Relational Descriptor as a Class or Aggregate Type
By default, when you add a Java class to a relational project (see Configuring Project Classpath), Workbench create a relational class descriptor for it. A class descriptor is applicable to any persistent object except an object that is owned by another in an aggregate relationship. In this case, you must describe the owned object with an aggregate descriptor. Using a class descriptor, you can configure any relational mapping except aggregate collection and aggregate object mappings.
An aggregate object is an object that is strictly dependent on its owning object. Aggregate descriptors do not define a table, primary key, or many of the standard descriptor options as they obtain these from their owning descriptor. If you want to configure an aggregate mapping to associate data members in a target object with fields in a source object's underlying database tables (see Configuring a Relational Aggregate Collection Mapping and Configuring a Relational Aggregate Object Mapping), you must designate the target object's descriptor as an aggregate.
Alternatively, you can remove the aggregate designation from a relational descriptor and return it to its default type.
You can configure inheritance for a descriptor designated as an aggregate (see Configuring Inheritance for a Child (Branch or Leaf) Class Descriptor), however, in this case, all the descriptors in the inheritance tree must be aggregates. Aggregate and class descriptors cannot exist in the same inheritance tree. For more information, see Aggregate and Composite Descriptors and Inheritance.
For more information, see XML Descriptors and Aggregation.
How to Configure a Relational Descriptor as a Class or Aggregate Type Using Workbench
To configure a relational descriptor as class or aggregate, use this procedure.
- In the Navigator, select a relational descriptor.
- Click the Class or Aggregate descriptor button on the mapping toolbar.
You can also select the descriptor and choose Selected > Descriptor Type > Class or Aggregate from the menu or by right-clicking on the descriptor in the Navigator window and selecting Descriptor Type > Class or Aggregate from the context menu. - If you select Aggregate, specify each of the aggregate descriptor's attributes as a direct to field mapping. See Configuring a Relational Direct-to-Field Mapping for more information.
Specify each of the aggregate descriptor's attributes as a direct to field mapping. See Configuring a Relational Direct-to-Field Mapping for more information.
Although the attributes of a target class are not mapped directly to a data source until you configure an aggregate object mapping, you must still specify their mapping type in the target class's descriptor. This tells EclipseLink what type of mapping to use when you do configure the aggregate mapping in the source object's descriptor. For more information, see Aggregate and Composite Descriptors in Relational Projects.
See Also:
How to Configure a Relational Descriptor as a Class or Aggregate Type Using Java
Using Java, to configure a relational descriptor as an aggregate, use ClassDescriptor method descriptorIsAggregate.
To configure a relational descriptor for use in an aggregate collection mapping, use ClassDescriptor method descriptorIsAggregateCollection.
To configure a relational descriptor as a nonaggregate, use ClassDescriptor method descriptorIsNormal.
Configuring Multitable Information
Descriptors can use multiple tables in mappings. Use multiple tables when either of the following occurs:
- A subclass is involved in inheritance, and its superclass is mapped to one table, while the subclass has additional attributes that are mapped to a second table.
- A class is not involved in inheritance and its data is spread out across multiple tables.
When a descriptor has multiple tables, you must be able to join a row from the primary table to all the additional tables. By default, EclipseLink assumes that the primary key of the first, or primary, table is included in the additional tables, thereby joining the tables. EclipseLink also supports custom methods for joining tables. If the primary key field names of the multiple tables do not match, a foreign key can be used to join the tables. The foreign key can either be from the primary table to the secondary table, or from the secondary table to the primary table, or between two of the secondary tables (see How to Configure Multitable Information Using Workbench).
For complex multitable situations, a more complex join expression may be required. These include requiring the join to also check a type code, or using an outer-join. EclipseLink provides support for a multiple-table-join-expression for these cases (see How to Configure Multitable Information Using Java).
How to Configure Multitable Information Using Workbench
To associate multiple tables with a descriptor, use this procedure.
- In the Navigator, select a descriptor.If the Multitable Info advanced property is not visible for the descriptor, right-click the descriptor and choose Select Advanced Properties > Multitable Info from the context menu or from the Selected menu.
- Click the Multitable Info tab.
Multitable Info Tab - Complete each field on the Multitable Info tab.
Use the following information to enter data in each field of the tab:
Field | Description |
---|---|
Primary Table | The primary table for this descriptor. This field is for display only. |
Additional Tables | Use Add and Remove to add or remove additional tables. |
Association to Primary Table |
Specify how each Additional Table is associated to the Primary Table:
|
Associating Tables with References
When associating a table using Reference, additional options appear. You must choose a reference that relates the correct fields in the primary table to the primary keys in the selected table.
Multitable Info Tab, Associated by Reference
Choose a Table Reference that defines how the primary keys of the primary table relate to the primary keys of the selected table. Click Add to add a primary key association.
How to Configure Multitable Information Using Java
Using Java, configure a descriptor with multitable information using the following org.eclipse.persistence.descriptors.ClassDescriptor methods:
- addTableName(java.lang.String tableName)
- addForeignKeyFieldNameForMultipleTable(java.lang.String sourceForeignKeyFieldName, java.lang.String targetPrimaryKeyFieldName)
To specify a complex multiple-table-join-expression, create a descriptor amendment method (see Configuring Amendment Methods) and add the join expression using org.eclipse.persistence.descriptors.DescriptorQueryManager method setMultipleTableJoinExpression. For more information, see Appending Additional Join Expressions.