119 Configuring a Descriptor

119.1 Configuring Common Descriptor Options

Table 119-2 lists the configurable options shared by two or more TopLink descriptor types. In addition to the configurable options described here, you must also configure the options described for the specific Descriptor Types, as shown in Table 119-1.

Table 119-2 Common Descriptor Options

Option to Configure	Oracle JDeveloper	TopLink Workbench	Java
Primary keys (see Section 119.2, "Configuring Primary Keys")
Read-only (see Section 119.3, "Configuring Read-Only Descriptors")
Unit of work conforming (see Section 119.4, "Configuring Unit of Work Conforming at the Descriptor Level")
Alias (see Section 119.5, "Configuring Descriptor Alias")
Comments (see Section 119.6, "Configuring Descriptor Comments")
Classes (see Section 5.7.2, "How to Configure Classes")
Named queries (see Section 119.7, "Configuring Named Queries at the Descriptor Level")
Query timeout (see Section 119.8, "Configuring Query Timeout at the Descriptor Level")
Cache refreshing (see Section 119.9, "Configuring Cache Refreshing")
Query keys (see Section 119.10, "Configuring Query Keys")
Interface query keys (see Section 119.11, "Configuring Interface Query Keys")
Cache type and size (see Section 119.12, "Configuring Cache Type and Size at the Descriptor Level")
Cache isolation (see Section 119.13, "Configuring Cache Isolation at the Descriptor Level")
Unit of work cache isolation (see Section 119.14, "Configuring Unit of Work Cache Isolation at the Descriptor Level")
Cache coordination change propagation (see Section 119.15, "Configuring Cache Coordination Change Propagation at the Descriptor Level")
Cache expiration (see Section 119.16, "Configuring Cache Expiration at the Descriptor Level")
Cache existence checking (see Section 119.17, "Configuring Cache Existence Checking at the Descriptor Level")
EJB information (see Section 119.18, "Configuring a Descriptor with EJB CMP and BMP Information")
Reading subclasses on queries (see Section 119.19, "Configuring Reading Subclasses on Queries")
Inheritance for a child class descriptor (see Section 119.20, "Configuring Inheritance for a Child (Branch or Leaf) Class Descriptor")
Inheritance for a parent class descriptor (see Section 119.21, "Configuring Inheritance for a Parent (Root) Descriptor")
Inheritance expressions for a parent class descriptor (see Section 119.22, "Configuring Inheritance Expressions for a Parent (Root) Class Descriptor")
Inherited attribute mapping in a subclass (see Section 119.23, "Configuring Inherited Attribute Mapping in a Subclass")
Domain object method as an event handler (see Section 119.24, "Configuring a Domain Object Method as an Event Handler")
Descriptor event listener as an event handler (seeSection 119.25, "Configuring a Descriptor Event Listener as an Event Handler")
Locking policy (see Section 119.26, "Configuring Locking Policy")
Returning policy (see Section 119.27, "Configuring Returning Policy")
Instantiation policy (see Section 119.28, "Configuring Instantiation Policy")
Copy policy (see Section 119.29, "Configuring Copy Policy")
Change policy (see Section 119.30, "Configuring Change Policy")
History policy (see Section 119.31, "Configuring a History Policy")
Wrapper policy (see Section 119.32, "Configuring Wrapper Policy")
Fetch groups (see Section 119.33, "Configuring Fetch Groups")
Amendment methods (see Section 119.35, "Configuring Amendment Methods")
Mapping (see Section 121, "Configuring a Mapping")

119.2 Configuring Primary Keys

A primary key is a unique identifier (made up of one or more persistent attributes) that distinguishes one instance of a class from all other instances of the same type. You use primary keys to define relationships and to define queries.

For the descriptors shown in Table 119-3, you must configure a primary key and you must ensure that your class contains one or more persistent fields suitable for this purpose.

Table 119-3 summarizes which descriptors support primary keys.

^Footnote 1 Relational class descriptors only (see Section 22.2.1.1, "Creating Relational Class Descriptors").

^Footnote 2 EIS root descriptors only (see Section 75.2.1.1, "EIS Root Descriptors").

For a relational class (non-aggregate) descriptor, choose any unique database field or set of unique database fields from the descriptor's associated table (see Section 23.2, "Configuring Associated Tables").

For an EIS root descriptor (see Section 76.6, "Configuring an EIS Descriptor as a Root or Composite Type"), choose any unique attribute or text node or set of unique attributes or text nodes from the descriptor's schema context (see Section 76.2, "Configuring Schema Context for an EIS Descriptor").

119.3 Configuring Read-Only Descriptors

You can configure a relational class or EIS root descriptor as read-only. This indicates that instances of the reference class will never be modified.

Read-only descriptors are usually used within a unit of work as a performance gain, because there is no need to register, clone, and merge the read-only classes. For more information, see Chapter 113, "Introduction to TopLink Transactions".

In a CMP project, you can declare an entity bean as read-only within the TopLink deployment XML file. For more information, see Section 119.3.1, "How to Use Read-Only EJB CMP Entity Beans".

Table 119-4 summarizes which descriptors support read-only configuration.

^Footnote 1 Relational class descriptors only (see Section 22.2.1.1, "Creating Relational Class Descriptors").

^Footnote 2 EIS root descriptors only (see Section 75.2.1.1, "EIS Root Descriptors")

119.4 Configuring Unit of Work Conforming at the Descriptor Level

Conforming is a query feature that lets you include new, changed, or deleted objects in queries within a unit of work prior to committing the transaction. This feature enables you to query against your relative logical or transaction view of a data source.

Table 119-5 summarizes which descriptors support descriptor level unit of work conforming.

Table 119-5 Descriptor Support for Unit of Work Conforming

Descriptor	How to Use Oracle JDeveloper	How to Configure Unit of Work Conforming at the Descriptor Level Using TopLink Workbench	How to Configure Unit of Work Conforming at the Descriptor Level Using Java
Relational DescriptorsFoot 1
Object-Relational Data Type Descriptors
EIS DescriptorsFoot 2
XML Descriptors

^Footnote 1 Relational class descriptors only (see Section 22.2.1.1, "Creating Relational Class Descriptors").

^Footnote 2 EIS root descriptors only (see Section 75.2.1.1, "EIS Root Descriptors")

When you configure a descriptor to conform results in a unit of work, when you execute a query in the unit of work, TopLink filters the data source result set to the changes currently made in the unit of work. TopLink adds new or changed objects that correspond to the query's selection criteria and removes changed objects that no longer correspond to the query's selection criteria.

Conforming can reduce performance. Before you enable a descriptor for conforming, be aware of its limitations (see Section 115.4.1, "How to Use Conforming") and make sure that conforming is actually necessary.

For examples, see the following:

• Section 115.4, "Using Conforming Queries and Descriptors"

• Section 115.4.4, "What You May Need to Know About Conforming Query Alternatives"

119.5 Configuring Descriptor Alias

In EJB CMP, use the descriptor alias to specify the value of the ejb-jar.xml attribute abstract-schema-name. This is the logical name that is referenced in EJB QL queries. You should configure a descriptor alias for each entity bean with container-managed persistence. The descriptor alias defaults to the class name without a path information.

Table 119-6 summarizes which descriptors support descriptor alias configuration.

Table 119-6 Descriptor Support for Descriptor Alias Configuration

Descriptor	How to Use Oracle JDeveloper	How to Configure Descriptor Alias Using TopLink Workbench	How to Configure Descriptor Alias Using Java
Relational Descriptors
Object-Relational Data Type Descriptors
EIS DescriptorsFoot 1
XML Descriptors

^Footnote 1 EIS root descriptors only (see Section 75.2.1.1, "EIS Root Descriptors").

For more information, see the following:

• Section 9.1.3, "ejb-jar.xml File"

• Section 108.15, "EJB 2.n CMP Finders"

119.6 Configuring Descriptor Comments

You can define a free-form textual comment for each descriptor. You can use these comments however you whish: for example, to record important project implementation details such as the purpose or importance of a descriptor.

Comments are stored in the TopLink Workbench project, in the TopLink deployment XML file. There is no Java API for this feature.

Table 119-7 summarizes which descriptors support descriptor comment configuration.

Table 119-7 Descriptor Support for Descriptor Comment Configuration

Descriptor	How to Use Oracle JDeveloper	How to Configure Descriptor Comments Using TopLink Workbench	How to Use Java
Relational Descriptors
Object-Relational Data Type Descriptors
EIS Descriptors
XML Descriptors

119.7 Configuring Named Queries at the Descriptor Level

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

If a named query is global to a Class, configure it at the descriptor level. Alternatively, you can configure a named query at the session level (see Section 89.13, "Configuring Named Queries at the Session Level").

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

For EJB CMP entity bean descriptors, you must define a named query for every finder defined for the corresponding entity bean.

Using Oracle JDeveloper or TopLink Workbench, you can configure named queries for a subset of query types and store them in a descriptor's DescriptorQueryManager (see Section 119.7.1, "How to Configure Named Queries at the Descriptor Level Using TopLink Workbench").

Using Java, you can create named queries for all query types and store them in a descriptor's DescriptorQueryManager (see Section 119.7.2, "How to Configure Named Queries at the Descriptor Level Using Java").

Table 119-4 summarizes which descriptors support named query configuration.

^Footnote 1 Relational class descriptors only (see Section 22.2.1.1, "Creating Relational Class Descriptors").

^Footnote 2 EIS root descriptors only (see Section 75.2.1.1, "EIS Root Descriptors").

For CMP projects, the ejb-jar.xml file stores query lists. You can define the queries in the file, and then read them into Oracle JDeveloper or TopLink Workbench, or define them on the Queries tab and write them to the file. See Section 19.7, "Working with the ejb-xml.File" for more information.

After you create a named query, you can execute it by name and class on the TopLink session (see Section 109.3, "Using Named Queries").

For more information about named queries, see Section 108.8, "Named Queries".

119.7.1 How to Configure Named Queries at the Descriptor Level Using TopLink Workbench

To create a named query, use this procedure

1. In the Navigator, select a descriptor. Its properties appear in the Editor.

2. Click the Queries tab in the Editor. The Queries tab appear with three additional tabs.

3. Click the Named Queries tab in the Queries tab. The Named Queries tab appears.

   Figure 119-6 Queries Tab–Named Queries Subtab

   
   Description of "Figure 119-6 Queries Tab–Named Queries Subtab"
   
   

Use the following information to complete each field on this tab:

Field	Description
Queries	Lists the existing queries for this descriptor. To create a new query, click Add (see Section 119.7.1.1, "Adding Named Queries"). To delete an existing query, select the query and click Delete. TopLink Workbench prompts for confirmation. To rename an existing query, select the query and click Rename. The Rename dialog box appears. Type a new name for the query and click OK.
Query Variety	Displays the variety of the currently selected query (see Section 119.7.1.1, "Adding Named Queries").
Quick View	Lists the parameters and joined attributes defined for the query. Clicking on a heading in the Quick View area selects the corresponding subtab. You can also remove parameters or attributes from the Quick View area by selecting the item and clicking Remove.

The Named Queries tab includes the following subtabs:

• General–See Section 119.7.1.2, "Configuring Named Query Type and Parameters".

• Selection Criteria–See Section 119.7.1.3, "Configuring Named Query Selection Criteria".

• Order–This tab appears for ReadAllQuery queries only. See Section 119.7.1.4, "Configuring Read All Query Order".

• Optimization–See Section 119.7.1.5, "Configuring Named Query Optimization".

• Attributes–This tab appears for ReportQuery queries only. See Section 119.7.1.6, "Configuring Named Query Attributes".

• Group/Order–This tab appears for ReportQuery queries only. Section 119.7.1.7, "Configuring Named Query Group/Order Options".

• Calls–This tab appears for EIS root descriptors only (for ReadAllQuery and ReadObjectQuery queries). See Section 119.7.1.8, "Creating an EIS Interaction for a Named Query".

• Options–See Section 119.7.1.9, "Configuring Named Query Options".

119.7.1.1 Adding Named Queries

Use this dialog box to create a new named query.

Figure 119-7 Add Named Query Dialog Box

Description of "Figure 119-7 Add Named Query Dialog Box"

Use the following information to complete the dialog box and create the named query:

Field	Description
Variety	For EJB CMP descriptors only, select the variety of query:
TopLink Named Query	Select to create a general purpose TopLink query of the type given by the Type area. You can execute this query by name on the TopLink session passing in the class and arguments (see Section 109.3, "Using Named Queries").
EJB Finder	Select to create a TopLink query of the type given by the Type area for use as the implementation of the EJB CMP finder method of the name you enter. The TopLink runtime executes this query when you call the EJB CMP finder method of the given name.
TopLink Reserved Finder	Select to create a TopLink query of the type given by the Type area for use as the implementation of the TopLink reserved finder method name you select. The TopLink runtime executes this query when you call the EJB CMP finder method of the given name. For more information, see Section 108.15.1, "Predefined Finders".
EJB Select	Select to create a TopLink query of the type given by the Type area for use as the implementation of the EJB CMP life cycle method ejbSelect. The TopLink runtime executes this query whenever the ejbSelect method is called.
Type	Select the type of query: ReadObject (ReadObjectQuery) ReadAll (ReadAllQuery) ReportFoot 1  (ReportQuery) Note: If Variety is set to TopLink Reserved Finder, you cannot select a query Type.
Name	The name of this query. If Variety is set to TopLink Named Query, you can specify any name. If Variety is set to EJB Finder, the name must be prefixed by find. If Variety is set to TopLink Reserved Finder, select from the list of available names that TopLink reserves. For more information, see Section 108.15.1, "Predefined Finders". If Variety is set to EJB Select, the name must be ejbSelect.

^Footnote 1 Relational descriptors only.

Enter the necessary information and click OK. TopLink Workbench adds the query to the list of queries in the Named Query tab.

119.7.1.2 Configuring Named Query Type and Parameters

Use this tab to select the query type and add or remove parameters.

Figure 119-8 Named Queries, General Tab

Description of "Figure 119-8 Named Queries, General Tab"

Use the following information to complete each field on this tab:

Field	Description
Type	Select the type of query from the list. You can create any of the following query types: ReadAllQuery ReadObjectQuery ReportQueryFoot 1  To create other types of query, you must use Java (see Section 119.7.2, "How to Configure Named Queries at the Descriptor Level Using Java"). When you change the type of an existing query, TopLink Workbench preserves any configuration that is common between the old and new type and warns you if changing the type will result in the loss of configuration that is not shared by the new type.
Parameters	For queries that take parameters, specify the parameters: To add a new parameter, click Add. The Add Query Parameter dialog box appears. Click Browse to select the type, specify a name, and click OK. To delete an existing parameter, select the parameter and click Remove. TopLink Workbench prompts for confirmation. To modify an existing parameter, select the parameter and click Edit. The Edit Query Parameter dialog box appears. Modify the name and type of the parameter and click OK. To change the order of the parameters, select an existing parameter and click Up or Down.
Type	Select the class of the parameter's type.
Name	Enter the name of the parameter.

^Footnote 1 Relational descriptors only.

119.7.1.3 Configuring Named Query Selection Criteria

Use this tab to specify the format of the named query and enter the query string.

Figure 119-9 Named Queries, Selection Criteria Tab

Description of "Figure 119-9 Named Queries, Selection Criteria Tab"

Use the following information to complete each field on this tab:

Field	Description
Type	Specify if query uses a TopLink Expression, SQL, or EJB QL.
Expression or Query String	If the Type is SQL or EJB QL, enter the query string (either SQL or EJB QL). TopLink Workbench does not validate the query string. See a note that follows this table for information on query syntax.

Note:

Use a combination of an escape character and a double-quote ( \" ) instead of just a double-quote ( " ) when defining your query using SQL or EJB QL. For example:

SELECT OBJECT(employee) FROM Employee employee WHERE employee.name = \"Bob\"

If you fail to do so, the generated Java code would look as follows:

query.setEJBQLString("SELECT OBJECT(employee) FROM Employee employee WHERE employee.name = "Bob"");

The preceding code produces an error at compile time.

If you define your query using the correct syntax, the generated Java code will contain no errors and be similar to the following:

query.setEJBQLString("SELECT OBJECT(employee) FROM Employee employee WHERE employee.name = \"Bob\"");

119.7.1.4 Configuring Read All Query Order

Use this tab to specify how the results of a read all query should be ordered by attribute name.

Figure 119-10 Named Queries, Order Tab

Description of "Figure 119-10 Named Queries, Order Tab"

Select one of the following actions:

• To add a new attribute by which to order query results, click Add. The Add Ordering Attribute dialog box appears. Select the mapped attribute to order by, specify ascending or descending order, and then click OK.

• To change the order of the order attributes, select an existing attribute and click Up or Down.

• To modify an existing order attribute's ordering options, select an existing attribute and click Edit.

• To remove an order attribute, select an existing attribute and click Remove.

119.7.1.5 Configuring Named Query Optimization

You can optimize a named query by configuring batch (ReadAllQuery only) or joining (ReadAllQuery and ReadObjectyQuery) attributes.

For more information on using batch reading, see Optimizing Queries, Section 12.12.9.2, "Reading Case 2: Batch Reading Objects", and Section 109.2.1.9, "Using Batch Reading".

For more information on joining, see Section 108.7.1.5, "Join Reading and Object-Level Read Queries" and Section 109.2.1.10, "Using Join Reading with ObjectLevelReadQuery".

Use this tab to specify batch reading and joining attributes.

Figure 119-11 Named Queries, Optimization Tab

Description of "Figure 119-11 Named Queries, Optimization Tab"

Select one of the following actions for Batch Read Attributes (ReadAllQuery only):

• To add a new batch read attribute, click Add. The Add Batch Read Attribute dialog box appears. Select the mapped attribute and click OK.

• To change the order of the batch read attributes, select an existing attribute and click Up or Down.

• To modify an existing batch read attribute's options, select an existing attribute and click Edit.

• To remove a batch read attribute, select an existing attribute and click Remove.

Select one of the following actions for Joined Attributes (ReadAllQuery and ReadObjectQuery):

• To add a new joined attribute, click Add. The Add Joined Attribute dialog box appears.

  Figure 119-12 Add Joined Attribute Dialog Box

  
  Description of "Figure 119-12 Add Joined Attribute Dialog Box"
  
  

  Select the mapped attribute. Optionally, enable or disable Allows Null or, for a Collection attribute, Allows None. Click OK.

• To change the order of the joined attributes, select an existing attribute and click Up or Down.

• To modify an existing joined attribute's options, select an existing attribute and click Edit.

• To remove a joined attribute, select an existing attribute and click Remove.

119.7.1.6 Configuring Named Query Attributes

For ReportQuery queries only, you can configure report query functions to apply to one or more attributes.

For more information about report queries, see Section 108.7.5, "Report Query".

Use this tab to configure report query attributes.

Figure 119-13 Named Queries, Attributes Tab

Description of "Figure 119-13 Named Queries, Attributes Tab"

Select one of the following actions for Attributes (ReportQuery only):

• To add a new report query attribute, click Add. The Add Joined Attribute dialog box appears. Continue with Section 119.7.1.6.1, "Adding Report Query Attributes".

• To change the order of the report query attribute attributes, select an existing attribute and click Up or Down.

• To modify an existing report query attribute's options, select an existing attribute and click Edit.

• To remove a report query attribute, select an existing attribute and click Remove.

Note:

You can only choose attributes that are configured with a direct mapping (converters included) or a user-defined query key.

119.7.1.6.1 Adding Report Query Attributes

Use this dialog box to add a report query attribute.

Figure 119-14 Add Report Query Attribute Dialog Box

Description of "Figure 119-14 Add Report Query Attribute Dialog Box"

Select the attribute you want in this report query and use the following table to complete the dialog box and add the report query attribute:

Option	'Description
Allows None or Allows Null	Use the Allows Null and Allows None options to define an expression with an outer join. Check the Allows Null option to use the ExpressionBuilder method getAllowingNull. Check the Allows None option for Collection attributes to use the ExpressionBuilder method anyOfAllowingNone. For more information, see Section 110.2.7.2, "Using TopLink Expression API for Joins".
Function	Select from the list of report query functions that TopLink provides. This function will be applied to the specified attribute. You must select an attribute for all functions, except Count. Alternatively, you can enter the name of a custom function that you implement in your database. For more information, see Expression method getFunction in the Oracle TopLink API Reference.
Name	The name associated with the calculated value. By default, the name is <AttributeName><FunctionName>.

Enter the necessary information and click OK. TopLink Workbench adds the report query attribute to the list of attributes in the Attribute tab.

119.7.1.7 Configuring Named Query Group/Order Options

For ReportQuery queries only, you can configure grouping and ordering attributes.

For more information about report queries, see Section 108.7.5, "Report Query".

Use this tab to specify grouping and ordering attributes.

Figure 119-15 Named Queries, Group/Order Tab

Description of "Figure 119-15 Named Queries, Group/Order Tab"

Select one of the following actions for Grouping Attributes (ReportQuery only):

• To add a new grouping attribute, click Add. The Add Grouping Attribute dialog appears. Select the desired mapped attribute and click OK.

• To change the order of the grouping attributes, select an existing attribute and click Up or Down.

• To modify an existing grouping attribute's options, select an existing attribute and click Edit.

• To remove a grouping attribute, select an existing attribute and click Remove.

Select one of the four following actions for Ordering Attributes (ReportQuery only):

• To add a new ordering attribute, click Add. The Add Ordering Attribute dialog box appears. Continue with Section 119.7.1.7.1, "Adding Ordering Attributes".

• To change the order of the ordering attributes, select an existing attribute and click Up or Down.

• To modify an existing ordering attribute's options, select an existing attribute and click Edit.

• To remove an ordering attribute, select an existing attribute and click Remove.

119.7.1.7.1 Adding Ordering Attributes

Use this dialog box to add a report query ordering attribute.

Figure 119-16 Add Ordering Attribute Dialog Box

Description of "Figure 119-16 Add Ordering Attribute Dialog Box"

Use the following information to complete the fields on the dialog box and add an ordering attribute:

Option	'Description
Selected Attribute	Select this option to view a list of the report query attributes you added (see Section 119.7.1.6, "Configuring Named Query Attributes"). Select an attribute and choose its ordering option in the Order field.
New Attribute	Select this option to view a list of all class attributes. Select an attribute and choose its ordering option in the Order field.
Order	Select ascending or descending.

Enter the necessary information and click OK. TopLink Workbench adds the report query attribute to the list of attributes in the Attribute tab.

119.7.1.8 Creating an EIS Interaction for a Named Query

For an EIS root descriptor, you can define EIS interactions to invoke methods on an EIS.

You can use TopLink to define an interaction as a named query for read object and read all object queries, as described here. These queries are not called for basic persistence operations (Section 76.5, "Configuring Custom EIS Interactions for Basic Persistence Operations"); you can call these additional queries by name in your application for special purposes.

Use this tab to define an interaction as a named query for read object and read all object queries.

Figure 119-17 Call Tab

Description of "Figure 119-17 Call Tab"

Use the following information to complete each field on the tab:

Field	Description
Interaction Type	Using TopLink Workbench, you can only use XML Interactions. You cannot change this field.
Function Name	Specify the name of the EIS function that this call type (Read Object or Read All) invokes on the EIS.
Input Record Name	Specify the name passed to the JCA adapter when creating the input record.
Input Root Element	Specify the root element name to use for the input DOM.
Input Arguments	Specify the query argument name to map to the interaction field or XPath nodes in the argument record. For example, if you are using XML records, use this option to map input argument name to the XPath name/first-name.
Output Arguments	Specify the result record field or XPath nodes to map the correct nodes in the record used by the descriptor's mappings. For example, if you are using XML records, use this option to map the output fname to name/first-name. Output arguments are not required if the interaction returns an XML result that matches the descriptor's mappings.
Input Result Path	Use this option if the EIS interaction expects the interaction arguments to be nested in the XML record. For example, specify arguments, if the arguments were to be nested under the root element exec-find-order, then under an arguments element.
Output Result Path	Use this option if the EIS interaction result record contains the XML data that maps to the objects in a nested structure. For example, specify order, if the results were return under a root element results, then under an order element.
Properties	Specify any properties required by your EIS platform. For example, property name operation (from AQPlatform.QUEUE_OPERATION) and property value enqueue (from AQPlatform.ENQUEUE).

119.7.1.9 Configuring Named Query Options

Use this tab to configure additional options for the query.

Figure 119-18 Named Queries, Options Tab

Description of "Figure 119-18 Named Queries, Options Tab"

Use the following information to complete each field on the tab:

Field	Description
Refresh Identity Map ResultsFootref 2	Refreshes the attributes of the object(s) resulting from the query. If cascading is used, the private parts of the objects will also be refreshed.
Cache StatementFoot 1	Caches the prepared statements. This requires full parameter binding as well (see Bind Parameters).
Bind ParametersFootref 1	By default, TopLink binds all of the query's parameters. Deselect this option to disable binding.
Cache UsageFoot 2	Selects how TopLink should use the session cache when a query is executed: Use descriptor settings Do not check cache Check cache by exact primary key Check cache by primary key Check cache then database Check cache only Conform results in unit of work For more information, see the following: Section 108.16.2.1, "Configuring Cache Usage for In-Memory Queries". Section 119.4, "Configuring Unit of Work Conforming at the Descriptor Level"
In Memory Query IndirectionFootref 2	Selects how TopLink should handle indirection (lazy loading) when an in-memory or conforming query is executed: Throw indirection exception–if this object uses indirection and indirection has not been triggered, TopLink will throw an exception. Trigger indirection–if this object uses indirection and indirection has not been triggered, TopLink will trigger indirection. Ignore exception return conformed–returns conforming if an untriggered value holder is encountered. That is, you expect results from the database to conform, and an untriggered value holder is taken to mean that the underlying attribute has not changed. Ignore exception return not conformed–returns not conforming if an untriggered value holder is encountered. For more information, see the following: Section 108.16.2.3, "Handling Exceptions Resulting from In-Memory Queries". Section 17.2.4, "Indirection (Lazy Loading)".
Return ChoiceFoot 3	Selects how TopLink should handle ReportQuery results: Result collection–return ReportQuery results as a Collection of ReportQueryResult objects. Single result–return only the first ReportQueryResult object (not wrapped in a Collection or Map). Use this option if you know that the ReportQuery returns only one row. Single value–return only a single value. Use this option if you know that the ReportQuery returns only one row that contains only one attribute. Single attribute–return only a single Collection of values. If the query returns multiple rows, but each row only has a single attribute, this option will return a Collection of values, instead of a Collection of ReportQueryResults. For more information, see Section 108.5.1, "Collection Query Results".
Retrieve Primary KeysFootref 3	Selects whether or not TopLink retrieves the primary key values within each result. You can use the primary keys to retrieve the real objects. None–do not retrieve primary keys All–retrieve primary keys for each object read; First–return only the first primary key value (in the case of a composite primary key). This can be used if you just want to know if something exists or not, but do not really care about the value.

^Footnote 1  For more information, see Section 12.11.5, "How to Use Parameterized SQL (Parameter Binding) and Prepared Statement Caching for Optimization".

^Footnote 2 For ReadObjectQuery and ReadAllQuery queries only.

^Footnote 3 For ReportQuery queries only.

Click Advanced to configure additional options. See Section 119.7.1.10, "Configuring Named Query Advanced Options".

See Also

Configuring Named Queries at the Descriptor Level

119.7.1.10 Configuring Named Query Advanced Options

To configure additional advanced query options, use this procedure.

1. From the Named Queries – Options tab, click Advanced. The Advanced Query Options dialog box appears.

   From the Named Queries – Options tab, click Advanced. The Advanced Query Options dialog box appears.

   Figure 119-19 Advanced Query Options Dialog Box

   
   Description of "Figure 119-19 Advanced Query Options Dialog Box"
   
   

2. Complete each field in the Advanced Query Options dialog box.

Use the following information to enter data in each field and click OK:

Field	Description
Maintain Cache	Specify whether to use the cache for the query or to build objects directly from the database result. You should only use this option if you are executing a partial object query (see Section 108.7.1.3, "Partial Object Queries"), whose results cannot be cached. For more information, see Section 108.16.4, "How to Disable the Identity Map Cache Update During a Read Query".
Use Wrapper Policy	Specify whether or not the named query will use the wrapper policy configured for this descriptor. For more information, see Section 119.32, "Configuring Wrapper Policy".
Prepare SQL Once	Specify the setShouldPrepare() for the named query. By default, TopLink optimizes queries to generate their SQL only once. You may need to disable this option for certain types of queries that require dynamic SQL based on their arguments, such as the following: Expressions that use equal where the argument value could be null. This may cause problems on databases that require IS NULL, instead of = NULL. Expressions that use in and use parameter binding. This will cause problems as the in values must be bound individually.
Cache Query Results	Specify the cacheQueryResults method for the query. The query will only access the database the first time it is executed. Subsequent execution will return exactly the original result. For more information, see Section 111.13.1, "How to Cache Results in a ReadQuery".
Refresh Remote Identity Map Results	Specify the refreshRemoteIdentityMapResult method for the query. TopLink can refresh the attributes of the object(s) resulting from the query. With cascading, TopLink will also refresh the private parts of the object(s).
Exclusive Connection	Specify whether or not the named query will use an exclusive connection. You can also configure exclusive connection acquisition at the session level (see Section 89.12, "Configuring Connection Policy".
Pessimistic Locking	Specify the specific pessimistic locking policy for the query or use the locking policy from the descriptor.
Distinct State	Specify if TopLink prints the DISTINCT clause, if a distinct has been set. The DISTINCT clause allows you to remove duplicates from the result set.
Query Timeout	Specify if the query will time out (or abort) after a specified number of seconds.
Maximum Rows	Specify if the query will limit the results to a specified number of rows. Use this to option for queries that could return an excessive number of objects.

public class EmployeeAmmendmentMethodClass {
....
    // Create named query with Employee as its reference class
    public static void createEmployeeQuery(ClassDescriptor descriptor) {
        ReadObjectQuery query = new ReadObjectQuery(Employee.class);
        ExpressionBuilder emp = query.getExpressionBuilder();
        Expression firstNameExpression =             emp.get("firstName").equal(emp.getParameter("firstName"));
        query.setSelectionCriteria(firstNameExpression);
        query.addArgument("firstName");

        descriptor.getQueryManager().addQuery(
                            "employeeReadByFirstName", query);
    }
}

119.8 Configuring Query Timeout at the Descriptor Level

You can specify how the TopLink runtime handles the duration of queries on a descriptor's reference class. Specifying a query timeout at the descriptor level applies to all queries on the descriptor's reference class. A query timeout ensures that your application does not block forever over a hung or lengthy query that does not return in a timely fashion.

Table 119-4 summarizes which descriptors support query timeout configuration.

^Footnote 1 Relational class descriptors only (see Section 22.2.1.1, "Creating Relational Class Descriptors").

You can also configure a timeout on a per-query basis. For more information, see the following:

• Section 119.7.1.10, "Configuring Named Query Advanced Options"

• Section 109.2.1.8, "Configuring Query Timeout at the Query Level"

119.9 Configuring Cache Refreshing

By default, TopLink caches objects read from a data source (see Chapter 102, "Introduction to Cache"). Subsequent queries for these objects will access the cache and thus improve performance by reducing data source access and avoiding the cost of rebuilding object's and their relationships. Even if a query, such as a read-all query, accesses the data source, if the objects corresponding to the records returned are in the cache, TopLink will use the cache objects.

This can lead to stale data in the application. Although using an appropriate locking policy (see Section 119.26, "Configuring Locking Policy") is the only way to ensure that stale or conflicting data does not get committed to the data source, sometimes certain data in the application changes so frequently that it is desirable to always refresh the data, instead of only refreshing the data when a conflict is detected.

You can specify how the TopLink runtime handles cache refreshing for all queries on a descriptor's reference class.

Table 119-4 summarizes which descriptors support query cache refresh configuration.

^Footnote 1 Relational class descriptors only (see Section 22.2.1.1, "Creating Relational Class Descriptors").

^Footnote 2 EIS root descriptors only (see Section 75.2.1.1, "EIS Root Descriptors").

Configuring descriptor-level cache refresh may affect performance. As an alternative, consider configuring the following:

• cache refresh on a query-by-query basis (see Section 108.16.5, "How to Refresh the Cache")

• cache expiration (see Section 119.16, "Configuring Cache Expiration at the Descriptor Level")

• isolated caching (see Section 102.2.7, "Cache Isolation")

For more information, see Section 12.10, "Optimizing Cache".

public void addToDescriptor(ClassDescriptor descriptor) {
    descriptor.setShouldRefreshCacheOnRemote(true);
    descriptor.setShouldDisableCacheHitsOnRemote(true);
}

119.10 Configuring Query Keys

A query key is a schema-independent alias for a database field name. For example, consider a class Employee with attribute firstName mapped directly to a database field F_NAME in database table EMPLOYEE. Without a query key, when you create a query or expression that involves Employee attribute firstName, you must use the database management system-specific field name F_NAME. This makes it more difficult to build a query and ties the query to the schema. With a query key, you can refer to this field using a schema-independent alias, such as firstName.

Table 119-11 summarizes which descriptors support query keys.

Table 119-11 Descriptor Support for Query Keys

Descriptor	How to Use Oracle JDeveloper	How to Configure Query Keys Using TopLink Workbench	How to Configure Query Keys Using Java
Relational Descriptors
Object-Relational Data Type Descriptors
EIS Descriptors
XML Descriptors

Using query keys offers the following advantages:

• Enhances code readability in TopLink expressions and simplifies expression development. You can compose expressions entirely within the context of your object model.

• Increases portability by making code independent of the database schema. If you rename a field in your schema, you can redefine the query key without changing any code that uses it.

• Query keys used with interface descriptors allow the implementor descriptor's tables to have different field names.

Query keys are automatically generated for all mapped attributes. The name of the query key is the name of the class attribute specified in your object model.

For information on how to use query keys in queries and expressions, see Section 108.2.7, "Query Keys".

When query keys are generated and how you can add or modify query keys depends on the type of mapping or descriptor involved:

• Direct Mappings

• Relationship Mappings

• Interface Descriptors

Direct Mappings

TopLink Workbench automatically generates query keys for all direct mappings at the time you create the mapping.

TopLink Workbench provides support for adding or modifying query keys for simple unmapped attributes that could be mapped by a direct mapping: for example, the version field used for optimistic locking or the type field used for inheritance. You cannot modify or remove automatically generated query keys.

Relationship Mappings

TopLink automatically generates query keys for all relationship mappings at run time.

For example, if you have a class Customer with attribute orders mapped in a one-to-many relationship to class PurchaseOrders, then the TopLink runtime will generate a query key named orders for this Customer attribute.

Neither Oracle JDeveloper nor TopLink Workbench currently support adding or modifying the query keys for relationship mappings. If you must add or modify such a query key, you must do so in Java code, using a descriptor amendment method.

Interface Descriptors

Interface descriptors (see Section 22.2.1.3, "Creating Relational Interface Descriptors") define only the query keys that are shared among their implementors. In the descriptor for an interface, only the name of the query key is specified.

TopLink Workbench provides support for choosing the implementors of an interface that share at least one common automatically generated query key (see Section 119.11, "Configuring Interface Query Keys").

// Add a query key for the foreign key field using the direct method
descriptor.addDirectQueryKey("managerId", "MANAGER_ID");

// The same query key can also be added through the addQueryKey method
DirectQueryKey directQueryKey = new DirectQueryKey();
directQueryKey.setName("managerId");
directQueryKey.setFieldName("MANAGER_ID");
descriptor.addQueryKey(directQueryKey);

// Add a one-to-one query key for the large project of which the
// employee is a leader (this assumes only one project)
OneToOneQueryKey projectQueryKey = new OneToOneQueryKey();
projectQueryKey.setName("managedLargeProject");
projectQueryKey.setReferenceClass(LargeProject.class);
ExpressionBuilder builder = new ExpressionBuilder();
projectQueryKey.setJoinCriteria(builder.getField(
    "PROJECT.LEADER_ID").equal(builder.getParameter("EMPLOYEE.EMP_ID")));
descriptor.addQueryKey(projectQueryKey);

// Add a one-to-many query key for the projects where the employee
// manages multiple projects 
OneToManyQueryKey projectsQueryKey = new OneToManyQueryKey();
projectsQueryKey.setName("managedProjects");
projectsQueryKey.setReferenceClass(Project.class);
ExpressionBuilder builder = new ExpressionBuilder();
projectsQueryKey.setJoinCriteria(builder.getField(
    "PROJECT.LEADER_ID").equal(builder.getParameter("EMPLOYEE.EMP_ID")));
descriptor.addQueryKey(projectsQueryKey);

// Add a many-to-many query key to an employee project that uses a join table
ManyToManyQueryKey projectsQueryKey = new ManyToManyQueryKey();
projectsQueryKey.setName("projects");
projectsQueryKey.setReferenceClass(Project.class);
ExpressionBuilder builder = new ExpressionBuilder();
projectsQueryKey.setJoinCriteria(
    builder.getTable("EMP_PROJ").getField("EMP_ID").equal(
    builder.getParameter("EMPLOYEE.EMP_ID").and(
    builder.getTable("EMP_PROJ").getField("PROJ_ID").equal(
    builder.getField("PROJECT.PROJ_ID")));
descriptor.addQueryKey(projectsQueryKey);

// Static amendment method in Address class, addresses do not know 
// their owners in the object model, however you can still
// query on their owner if a user-defined query key is defined
public static void addToDescriptor(Descriptor descriptor) {
    OneToOneQueryKey ownerQueryKey = new OneToOneQueryKey();
    ownerQueryKey.setName("owner");
    ownerQueryKey.setReferenceClass(Employee.class);
    ExpressionBuilder builder = new ExpressionBuilder();
    ownerQueryKey.setJoinCriteria(
        builder.getField("EMPLOYEE.ADDRESS_ID").equal(
        builder.getParameter("ADDRESS.ADDRESS_ID")));
    descriptor.addQueryKey(ownerQueryKey);
}

119.11 Configuring Interface Query Keys

A query key is a schema independent alias for a database field name. For more information about query keys, see Section 119.10, "Configuring Query Keys".

Interface descriptors (see Section 22.2.1.3, "Creating Relational Interface Descriptors") are defined only with query keys that are shared among their implementors. In the descriptor for an interface, only the name of the query key is specified.

In each implementor descriptor, the key must be defined with the appropriate field from one of the implementor descriptor's tables.

This allows queries and relationship mappings to be defined on the interface using the query key names.

Interface query keys are supported in relational database projects only.

Table 119-11 summarizes which descriptors support interface query keys.

Table 119-12 Descriptor Support for Interface Query Keys

Descriptor	How to Use Oracle JDeveloper	How to Configure Interface Query Keys Using TopLink Workbench	How to Configure Interface Query Keys Using Java
Relational Descriptors
Object-Relational Data Type Descriptors
EIS Descriptors
XML Descriptors

Consider an Employee that contains a contact of type Contact. The Contact class is an interface with two implementors: Phone and Email. The Phone class has attributes id and number. The Email class has attributes id and address. Figure 119-23 illustrates the generated keys:

Figure 119-23 Automatically Generated Query Keys for Phone and Email

Description of "Figure 119-23 Automatically Generated Query Keys for Phone and Email "

Both classes have an attribute, id, that is directly mapped to fields that have different names. However, a query key is generated for this attribute. For the Contact interface descriptor, you must indicate that the id query key must be defined for each of the implementors.

If either of the implementor classes did not have the id query key defined, Oracle JDeveloper and TopLink Workbench would flag that descriptor as deficient.

Now that a descriptor with a commonly shared query key has been defined for Contact, you can use it as the reference class for a variable one-to-one mapping (see Section 111.8, "Using Queries on Variable One-to-One Mappings").

For example, you can now create a variable one-to-one mapping for the contact attribute of Employee. When you edit the foreign key field information for the mapping, you must match the Employee descriptor's tables to query keys from the Contact interface descriptor.

Descriptor contactInterfaceDescriptor = new Descriptor();
contactInterfaceDescriptor.setJavaInterface(Contact.class);
contactInterfaceDescriptor.addAbstractQueryKey("id");

Descriptor emailClassDescriptor = new Descriptor();
emailClassDescriptor.setJavaClass(Email.class);
emailClassDescriptor.addDirectQueryKey("id", "E_ID");
emailClassDescriptor.getInterfacePolicy().addParentInterface(Contact.class);
emailClassDescriptor.setTableName("INT_EML");
emailClassDescriptor.setPrimaryKeyFieldName("E_ID");
emailClassDescriptor.setSequenceNumberName("SEQ");
emailClassDescriptor.setSequenceNumberFieldName("E_ID");
emailClassDescriptor.addDirectMapping("emailID", "E_ID");
emailClassDescriptor.addDirectMapping("address", "ADDR");

Descriptor phoneClassDescriptor = new Descriptor();
phoneClassDescriptor.setJavaClass(Phone.class);
phoneClassDescriptor.getInterfacePolicy().addParentInterface(Contact.class);
phoneClassDescriptor.addDirectQueryKey("id", "P_ID");
phoneClassDescriptor.setTableName("INT_PHN");
phoneClassDescriptor.setPrimaryKeyFieldName("P_ID");
phoneClassDescriptor.setSequenceNumberName("SEQ");
phoneClassDescriptor.setSequenceNumberFieldName("P_ID");
phoneClassDescriptor.addDirectMapping("phoneID", "P_ID");
phoneClassDescriptor.addDirectMapping("number", "P_NUM");

119.12 Configuring Cache Type and Size at the Descriptor Level

The TopLink cache is an in-memory repository that stores recently read or written objects based on class and primary key values. TopLink uses the cache to do the following:

• improve performance by holding recently read or written objects and accessing them in-memory to minimize database access;

• manage locking and isolation level;

• manage object identity.

Table 119-13 summarizes which descriptors support identity map configuration.

Table 119-13 Descriptor Support for Identity Map

Descriptor	How to Use Oracle JDeveloper	How to Configure Cache Type and Size at the Descriptor Level Using TopLink Workbench	How to Configure Cache Type and Size at the Descriptor Level Using Java
Relational DescriptorsFoot 1
Object-Relational Data Type Descriptors
EIS DescriptorsFoot 2
XML Descriptors

^Footnote 1 Relational class descriptors only (see Section 22.2.1.1, "Creating Relational Class Descriptors").

^Footnote 2 EIS root descriptors only (see Section 75.2.1.1, "EIS Root Descriptors").

This configuration overrides the default identity map configuration defined at the project level (see Section 117.10, "Configuring Cache Type and Size at the Project Level").

For detailed information on caching and object identity, and the recommended settings to maximize TopLink performance, see to Section 102.2.1, "Cache Type and Object Identity".

For more information about the cache, see Chapter 102, "Introduction to Cache".

119.13 Configuring Cache Isolation at the Descriptor Level

If you plan to use isolated sessions (see Section 102.2.7, "Cache Isolation"), you must configure descriptors as isolated for any object that you want confined to an isolated session cache.

Configuring a descriptor to be isolated means that TopLink will not store the object in the shared session cache and the object will not be shared across client sessions. Each client will have their own object read directly from the database. Objects in an isolated client session cache can reference objects in their parent server session's shared session cache, but no objects in the shared session cache can reference objects in an isolated client session cache. Isolation is required when using Oracle Database Virtual Private Database (VPD) support or database user-based read security. Isolation can also be used if caching is not desired across client sessions.

Table 119-13 summarizes which descriptors support cache isolation configuration.

Table 119-14 Descriptor Support for Cache Isolation Map

Descriptor	How to Use Oracle JDeveloper	How to Configure Cache Isolation at the Descriptor Level Using TopLink Workbench	How to Configure Cache Isolation at the Descriptor Level Using Java
Relational DescriptorsFoot 1
Object-Relational Data Type Descriptors
EIS DescriptorsFoot 2
XML Descriptors

^Footnote 1 Relational class descriptors only (see Section 22.2.1.1, "Creating Relational Class Descriptors").

^Footnote 2 EIS root descriptors only (see Section 75.2.1.1, "EIS Root Descriptors").

This configuration overrides the default cache isolation configuration defined at the project level (see Section 117.11, "Configuring Cache Isolation at the Project Level").

119.14 Configuring Unit of Work Cache Isolation at the Descriptor Level

Use this policy to determine how a unit of work uses a session cache for a specific class. Table 119-15 lists the unit of work cache isolation options.

Most of these options apply only to a unit of work in an early transaction, such as the following:

• A unit of work that was flushed (write changes).

• Issued a modify query.

• Acquired a pessimistic lock.

119.15 Configuring Cache Coordination Change Propagation at the Descriptor Level

If you plan to use a coordinated cache (see Section 102.3, "Cache Coordination"), you can configure how, and under what conditions, a coordinated cache propagates changes for a given descriptor.

Table 119-13 summarizes which descriptors support cache isolation configuration.

Table 119-16 Descriptor Support for Cache Coordination Change Propagation Configuration

Descriptor	How to Use Oracle JDeveloper	How to Configure Cache Coordination Change Propagation at the Descriptor Level Using TopLink Workbench	How to Configure Cache Coordination Change Propagation at the Descriptor Level Using Java
Relational DescriptorsFoot 1
Object-Relational Data Type Descriptors
EIS DescriptorsFoot 2
XML Descriptors

^Footnote 1 Relational class descriptors only (see Section 22.2.1.1, "Creating Relational Class Descriptors").

^Footnote 2 EIS root descriptors only (see Section 75.2.1.1, "EIS Root Descriptors").

This configuration overrides the default cache coordination change propagation configuration defined at the project level (see Section 117.12, "Configuring Cache Coordination Change Propagation at the Project Level").

To complete your coordinated cache configuration, see Chapter 103, "Configuring a Coordinated Cache".

119.16 Configuring Cache Expiration at the Descriptor Level

By default, objects remain in the cache until they are explicitly deleted (see Section 114.7, "Deleting Objects") or garbage-collected when using a weak identity map (see Section 117.11, "Configuring Cache Isolation at the Project Level"). Alternatively, you can configure an object with a CacheInvalidationPolicy that allows you to specify, either automatically or manually, that an object is invalid: when any query attempts to read an invalid object, TopLink will go to the data source for the most up-to-date version of that object and update the cache with this information.

Using cache invalidation ensures that your application does not use stale data. It provides a better performing alternative to always refreshing (see Section 119.9, "Configuring Cache Refreshing").

Table 119-17 summarizes which descriptors support a cache invalidation policy.

Table 119-17 Descriptor Support for Cache Invalidation Policy

Descriptor	How to Use Oracle JDeveloper	How to Configure Cache Expiration at the Descriptor Level Using TopLink Workbench	How to Configure Cache Expiration at the Descriptor Level Using Java
Relational DescriptorsFoot 1
Object-Relational Data Type Descriptors
EIS DescriptorsFoot 2
XML Descriptors

^Footnote 1 Relational class descriptors only (see Section 22.2.1.1, "Creating Relational Class Descriptors").

^Footnote 2 EIS root descriptors only (see Section 75.2.1.1, "EIS Root Descriptors").

You can override the project-level cache invalidation configuration (see Section 117.13, "Configuring Cache Expiration at the Project Level") by defining cache invalidation at the descriptor or query level (see Section 111.13.2, "How to Configure Cache Expiration at the Query Level").

You can customize how TopLink communicates the fact that an object has been declared invalid to improve efficiency, if you are using a coordinated cache. For more information, see Section 119.15, "Configuring Cache Coordination Change Propagation at the Descriptor Level".

For more information, see Section 102.2.5, "Cache Invalidation".

119.17 Configuring Cache Existence Checking at the Descriptor Level

When TopLink writes an object to the database, TopLink runs an existence check to determine whether to perform an insert or an update.

By default, TopLink checks against the cache. Oracle recommends that you use this default existence check option for most applications. Checking the database for existence can cause a performance bottleneck in your application.

Table 119-18 summarizes which descriptors support existence checking.

Table 119-18 Descriptor Support for Existence Checking

Descriptor	How to Use Oracle JDeveloper	How to Configure Cache Existence Checking at the Descriptor Level Using TopLink Workbench	How to Configure Cache Existence Checking at the Descriptor Level Using Java
Relational DescriptorsFoot 1
Object-Relational Data Type Descriptors
EIS DescriptorsFoot 2
XML Descriptors

^Footnote 1 Relational class descriptors only (see Section 22.2.1.1, "Creating Relational Class Descriptors").

^Footnote 2 EIS root descriptors only (see Section 75.2.1.1, "EIS Root Descriptors").

You can configure existence checking at the descriptor level to override the project level configuration (see Section 117.7, "Configuring Existence Checking at the Project Level").

For more information see the following:

• Section 102.2.1, "Cache Type and Object Identity"

• Section 108.16, "Queries and the Cache"

• Section 115.1.3, "How to Use Registration and Existence Checking"

descriptor.getQueryManager().checkCacehForDoesExist();

119.18 Configuring a Descriptor with EJB CMP and BMP Information

If your project uses EJB CMP or BMP (see Section 117.5, "Configuring Persistence Type"), you can use descriptors to describe the characteristics of entity beans with container-managed or bean-managed persistence.

Table 119-19 summarizes which descriptors support EJB information.

^Footnote 1 Relational class descriptors only (see Section 22.2.1.1, "Creating Relational Class Descriptors").

^Footnote 2 EIS root descriptors only (see Section 75.2.1.1, "EIS Root Descriptors").

When mapping enterprise beans, you create a descriptor for the bean class; you do not create a descriptor for the local interface, remote interface, home class, or primary key class.

When using TopLink Workbench, you must define the project with the correct entity bean type (such as container-managed or bean-managed persistence) and import the ejb-jar.xml file for the beans into the TopLink Workbench project.

For CMP projects, the ejb-jar.xml file defines the bean's attributes to be mapped. A descriptor for an entity bean container-managed persistence contains a CMP policy used to configure CMP-specific options.

For more information, see Section 16.2.3, "Descriptors and CMP and BMP".

descriptor.setCMPPolicy(new CMPPolicy());

119.19 Configuring Reading Subclasses on Queries

If you are mapping an inheritance hierarchy, by default, queries on root or branch classes return instances of the root class and their subclasses.

Alternatively, you can configure a root or branch class descriptor to do the following:

• not include subclasses when the root or branch class is queried;

• outer-join subclasses when the root or branch class is queried.

You can also specify a database view to optimize the reading of subclasses. The view can be used to optimize queries for root or branch classes that have subclasses spanning multiple tables. The view must apply an outer-join or union all of the subclass tables.

Do not configure this option for leaf classes.

Table 119-20 summarizes which descriptors support inherited attribute mapping configuration.

Table 119-20 Descriptor Support for Inherited Attribute Mapping Configuration

Descriptor	How to Use Oracle JDeveloper	How to Configure Reading Subclasses on Queries Using TopLink Workbench	How to Configure Reading Subclasses on Queries Using Java
Relational Descriptors
Object-Relational Data Type Descriptors
EIS Descriptors
XML Descriptors

For more information, see Section 16.2.2, "Descriptors and Inheritance".

...
public static void addToPersonDescriptor(Descriptor descriptor) {
    descriptor.getInheritancePolicy().dontReadSubclassesOnQueries();
}
...

...
public static void addToPersonDescriptor(Descriptor descriptor) {
    descriptor.getInheritancePolicy().setReadAllSubclassesViewName(myView);
}
...

...
public static void addToPersonDescriptor(Descriptor descriptor) {
    descriptor.getInheritancePolicy().setShouldOuterJoinSubclasses(true);
}
...

119.20 Configuring Inheritance for a Child (Branch or Leaf) Class Descriptor

Inheritance describes how a derived (child) class inherits the characteristics of its superclass (parent). When you designate a class as a child, you must also specify the descriptor that represents the child's parent in your inheritance hierarchy.

Table 119-39 summarizes which descriptors support child inheritance configuration.

Table 119-21 Descriptor Support for Child Inheritance Configuration

Descriptor	How to Use Oracle JDeveloper	How to Configure Inheritance for a Child (Branch or Leaf) Class Descriptor Using TopLink Workbench	How to Configure Inheritance for a Child (Branch or Leaf) Class Descriptor Using Java
Relational Descriptors
Object-Relational Data Type Descriptors
EIS Descriptors
XML Descriptors

For more information about inheritance, see Section 16.2.2, "Descriptors and Inheritance".

For more information about configuring inheritance for a parent (root) class descriptor, see Section 119.21, "Configuring Inheritance for a Parent (Root) Descriptor".

descriptor.getInheritancePolicy().setParentClass(ChildClass.class);

119.21 Configuring Inheritance for a Parent (Root) Descriptor

Inheritance describes how a derived (child) class inherits the characteristics of its superclass (parent). When you designate a class as a parent, you can configure how TopLink handles the class's inheritance hierarchy.

Table 119-24 summarizes which descriptors support parent inheritance configuration.

Table 119-22 Descriptor Support for Parent Inheritance Configuration

Descriptor	How to Use Oracle JDeveloper	How to Configure Inheritance for a Parent (Root) Descriptor Using TopLink Workbench	How to Configure Inheritance for a Parent (Root) Descriptor Using Java
Relational Descriptors
Object-Relational Data Type Descriptors
EIS Descriptors
XML Descriptors

For more information about configuring inheritance for a child (branch or leaf) class descriptor, see Section 119.20, "Configuring Inheritance for a Child (Branch or Leaf) Class Descriptor".

For more information, see Section 16.2.2, "Descriptors and Inheritance".

...
public static void addToPersonDescriptor(Descriptor descriptor) {
    descriptor.getInheritancePolicy().setClassIndicatorFieldName("CLIENT_TYPE");
    descriptor.getInheritancePolicy().addClassIndicator(Student.class, indicator);
}

public static void addToStudentDescriptor(Descriptor descriptor) {
    descriptor.getInheritancePolicy().setParentClass(Person.class);
    ...
}
...

...
public static void addToPersonDescriptor(Descriptor descriptor) {
    descriptor.getInheritancePolicy().setClassIndicatorField(
                                             new XMLField("@CLIENT_TYPE"));
    descriptor.getInheritancePolicy().addClassIndicator(Student.class, indicator);
}

public static void addToStudentDescriptor(Descriptor descriptor) {
    descriptor.getInheritancePolicy().setParentClass(Person.class);
    descriptor.getInheritancePolicy().setClassIndicatorField(
                                              new XMLField("@CLIENT_TYPE")
    );
}
...

119.22 Configuring Inheritance Expressions for a Parent (Root) Class Descriptor

If your class uses inheritance (see Section 16.3, "Descriptors and Inheritance") with a class extraction method (see Section 16.3.1.2, "Using Class Extraction Methods") you must provide TopLink with expressions to correctly filter sibling instances for all classes that share a common table.

Table 119-24 summarizes which descriptors support inheritance expression configuration.

Table 119-23 Descriptor Support for Inheritance Expression Configuration

Descriptor	How to Use Oracle JDeveloper	How to Use TopLink Workbench	How to Configure Inheritance Expressions for a Parent (Root) Class Descriptor Using Java
Relational Descriptors
Object-Relational Data Type Descriptors
EIS Descriptors
XML Descriptors

Figure 119-34 shows a typical inheritance hierarchy. In this example, instances of both Person and Student are stored in the same PERSON table, as Figure 119-35 shows: an instance of Person has a null value for STUDENT_NUMBER. Instances of Company are stored in a separate COMPANY table.

Figure 119-34 Example Inheritance Hierarchy

Description of "Figure 119-34 Example Inheritance Hierarchy"

Figure 119-35 PERSON Table

Description of "Figure 119-35 PERSON Table"

Queries on inheritance classes that share a common table, such as Person and Student, must filter out their sibling instances. TopLink performs this filtering using the Expression instances returned by the descriptor's InheritancePolicy methods getOnlyInstancesExpression and getWithAllSubclassesExpression.

Queries on a class that has its own table for its specific data, such as Company, and does not share this table with any sibling classes, do not require these expressions.

If you use a class indicator type field (see Section 16.3.1.1, "Using Class Indicator Fields"), TopLink automatically generates the required expressions.

If you use a class extraction method (see Section 16.3.1.2, "Using Class Extraction Methods"), you must provide TopLink with an expressions to correctly filter sibling instances for all classes that share a common table.

For concrete classes, you must define an only- instances expression.

For branch classes, you must define a with-all-subclasses expression.

When TopLink queries for a leaf class, it uses the only- instances expression to filter out any sibling classes.

When TopLink queries for a root or branch class whose subclasses do not define their own tables, it uses the with-all-subclasses expression. This is also the case when a subclass view is used (see Section 119.19, "Configuring Reading Subclasses on Queries").

When querying for a root or branch class that has subclasses that span multiple tables, a query is performed for each concrete class in the inheritance hierarchy using the only- instances expression to filter sibling classes.

When a class extraction method is used the only-instances expression is used to determine if a class is concrete. If a class does not require an only instances expression, do not enable reading subclasses on queries (see Section 119.19, "Configuring Reading Subclasses on Queries"), otherwise TopLink will assume that the class has no instances and it will skip that class on queries.

For more information about inheritance expressions, see Section 16.3.1.2.1, "Specifying Expressions for Only-Instances and With-All-Subclasses".

...
// Only-instances expression for Person
public static void addToPersonDescriptor(Descriptor descriptor) {
    ExpressionBuilder builder = new ExpressionBuilder();
    descriptor.getInheritancePolicy().setOnlyInstancesExpression(
                              builder.getField("STUDENT_NUMBER").isNull());
}

// Only-instances expression for Student
public static void addToStudentDescriptor(Descriptor descriptor) {
    ExpressionBuilder builder = new ExpressionBuilder();
    descriptor.getInheritancePolicy().setOnlyInstancesExpression(
                              builder.getField("STUDENT_NUMBER").notNull());
}
...

// Bicycle amemndment
public static void addToBicycleDescriptor(Descriptor descriptor) {
    ExpressionBuilder builder = new ExpressionBuilder();
    descriptor.getInheritancePolicy().setOnlyInstancesExpression(
                              builder.getField("BICYCLE_DESCR").notNull());
}

// NonFueldVehicle ammendment
public static void addToNonFueledVehicleDescriptor(Descriptor descriptor) {
    ExpressionBuilder builder = new ExpressionBuilder();
    descriptor.getInheritancePolicy().setWithAllSubclassesExpression(
                                    builder.getField("FUEL_TYPE").isNull());
}

119.23 Configuring Inherited Attribute Mapping in a Subclass

If you are defining the descriptor for a class that inherits attributes from another class, then you can create mappings for those attributes. If you remap an attribute that was already mapped in the superclass, then the new mapping applies to the subclass only. Any other siblings that inherit the attribute are unaffected.

If you leave inherited attributes unmapped, TopLink uses the mapping (if any) from the superclass if the superclass's descriptor has been designated as the parent descriptor.

Table 119-24 summarizes which descriptors support inherited attribute mapping configuration.

Table 119-24 Descriptor Support for Inherited Attribute Mapping Configuration

Descriptor	How to Use Oracle JDeveloper	How to Configure Inherited Attribute Mapping in a Subclass Using TopLink Workbench	How to Configure Inherited Attribute Mapping in a Subclass Using Java
Relational Descriptors
Object-Relational Data Type Descriptors
EIS Descriptors
XML Descriptors

For more information, see Section 16.2.2, "Descriptors and Inheritance".

119.24 Configuring a Domain Object Method as an Event Handler

You can associate a domain object method with any of the descriptor events shown in Table 119-26. You can register any domain object method that complies with the following criteria:

• Is public.

• Returns void.

• Takes a single parameter of type DescriptorEvent

Table 119-25 summarizes which descriptors support domain object method event handler configuration.

Table 119-25 Descriptor Support for Domain Object Method Event Handler Configuration

Descriptor	How to Use Oracle JDeveloper	How to Configure a Domain Object Method as an Event Handler Using TopLink Workbench	How to Configure a Domain Object Method as an Event Handler Using Java
Relational Descriptors
Object-Relational Data Type Descriptors
EIS Descriptors
XML Descriptors

For example, you can add a method handlePostDelete (that is public, returns void, and takes a single parameter of type DescriptorEvent) to your Employee object to handle PostDeleteEvent descriptor events. After you register that method with the DescriptorEventManager owned by the Employee object's descriptor as the handler for PostDeleteEvent descriptor events, whenever the Oracle TopLink runtime performs a post-delete operation on an instance of the Employee object, the runtime dispatches a PostDeleteEvent to the handlePostDelete method on the instance of the Employee object associated with that PostDeleteEvent.

The Descriptor Event ID column in Table 119-26 lists the DescriptorEventManager field name used to identify a particular event. The DescriptorEvent method getEventCode returns this value. For example:

if (descriptorEvent.getEventCode() == DescriptorEventManager.PreUpdateEvent) {
    // descriptorEvent represents a pre-update event
}

Alternatively, you can configure a descriptor event listener as an event handler (see Section 119.25, "Configuring a Descriptor Event Listener as an Event Handler").

public class Employee {
    // domain object methods
    ...
    public void handlePostDelete(DescriptorEvent event) {
        // handler implementation
    }
}

employeeDescriptor.getEventManager().setPostDeleteSelector("handlePostDelete");

119.25 Configuring a Descriptor Event Listener as an Event Handler

You can create your own DescriptorEventListner and register it with a DescriptorEventManager in a descriptor amendment method. You can also configure a DescriptorEventListner to be notified of events through the Java event model.

You can register any object that implements the DescriptorEventListener interface with the DescriptorEventManager owned by a domain object's descriptor to handle any descriptor event type (see Table 119-28). To quickly implement this interface, you can extend abstract class DescriptorEventAdapter and override only the methods for the events you are interested in.

Table 119-27 summarizes which descriptors support descriptor event listener configuration.

Table 119-27 Descriptor Support for Descriptor Event Listener Configuration

Descriptor	How to Use Oracle JDeveloper	How to Configure a Descriptor Event Listener as an Event Handler Using TopLink Workbench	How to Configure a Descriptor Event Listener as an Event Handler Using Java
Relational Descriptors
Object-Relational Data Type Descriptors
EIS Descriptors
XML Descriptors

For example, you create a DescriptorEventListener to handle PostBuildEvent descriptor events for Employee objects. After you register this DescriptorEventListener with the DescriptorEventManager owned by the Employee object's descriptor, whenever the TopLink runtime performs a post-build operation on an instance of Employee, the runtime dispatches a PostBuilEvent to the event listener's postBuild method.

Table 119-28 lists the DescriptorEventListener methods associated with each descriptor event. The Descriptor Event Listener Method column lists the DescriptorEventListener methods associated with each DescriptorEvent.

Alternatively, you can configure a domain object method as an event handler (see Section 119.24, "Configuring a Domain Object Method as an Event Handler").

public class MyDescriptorEventListener extends DescriptorEventAdapter {

    public void postBuild(DescriptorEvent event) {
        // handler implementation
    }
}

descriptor.getEventManager().addListener(new MyDescriptorEventListener());

119.26 Configuring Locking Policy

You can configure a descriptor with a locking policy that prevents one user writing over another user's work.

Table 119-29 summarizes which descriptors support locking policies.

^Footnote 1 Relational class descriptors only (see Section 22.2.1.1, "Creating Relational Class Descriptors").

^Footnote 2 EIS root descriptors only (see Section 75.2.1.1, "EIS Root Descriptors").

Oracle recommends that you use a locking policy. You should use a locking policy in any multiuser environment to prevent one user writing over another user's changes. Although locking can be particularly important if multiple servers or multiple applications access the same data, even in a single server application, the same locking issue still exists. In a multiple-server environment, locking is still relevant even if your application uses cache refreshing or cache coordination.

If you are building a three-tier application, in order to correctly lock an object, you must obtain the lock before the object is sent to client to be edited. The type of locking you choose has an influence on how you can achieve this (see Section 16.4.6, "Locking in a Three-Tier Application").

119.27 Configuring Returning Policy

Using a ReturningPolicy, you can obtain field values from the data source when inserting or updating an object. TopLink uses the values that the data source returns to update the object attributes that map to these fields. You can specify which fields to return for inserts and updates. For insert fields, you can also specify whether or not to include the field value in the insert operation.

A ReturningPolicy is useful when the data source provides default or initial field values through defaults, triggers, or stored procedures. You can also use a ReturningPolicy to allow the data source to assign a sequence or primary key value.

Any object attribute that you do not configure in a descriptor's ReturningPolicy receives the default behavior: in the context of a unit of work, if the attribute has changed, its value is written to the database. If the SQL statement invokes a trigger or stored procedure that modifies the database field, the database generated value is not reflected by the object.

Use caution when deciding on whether or not to use a ReturningPolicy, as doing so may effect insert or update performance and is not compatible with batch writing (see Section 12.11.3, "How to Use Batch Writing for Optimization").

By default, you can use a ReturningPolicy with Oracle Database, in which case, TopLink uses the Oracle RETURNING clause (see Section 119.27.1, "How to Configure Returning Policy Using TopLink Workbench").

You can use a ReturningPolicy with a non-Oracle database if you configure your descriptor's insert or update query to use a stored procedure that returns the desired returned values as output parameters (see Section 119.27.2, "How to Configure Returning Policy Using Java").

Table 119-39 summarizes which descriptors support returning policy configuration.

Table 119-30 Descriptor Support for Fetch Group Configuration

Descriptor	How to Use Oracle JDeveloper	How to Configure Returning Policy Using TopLink Workbench	How to Configure Returning Policy Using Java
Relational Descriptors
Object-Relational Data Type Descriptors
EIS DescriptorsFoot 1
XML Descriptors

^Footnote 1 EIS root descriptors only (see Section 75.2.1.1, "EIS Root Descriptors").

119.28 Configuring Instantiation Policy

The TopLink runtime instantiates new instances of a class according to the instantiation policy you configure on the class's descriptor.

Table 119-32 summarizes which descriptors support an instantiation policy.

You can specify one of the following types of instantiation policy:

• Default: TopLink creates a new instance of a class by calling the class's default constructor.

• Method: TopLink creates a new instance of a class by calling a public static method that you define on the class descriptor.

• Factory: TopLink creates a new instance of a class by calling the appropriate methods on a separate class that you implement according to the Factory design pattern.

119.29 Configuring Copy Policy

The TopLink unit of work feature must be able to produce an exact copy (clone) persistent objects. Table 119-33 summarizes which descriptors support a copy policy.

TopLink supports the following two ways of copying objects:

• Instantiation policy: By default, TopLink creates a new copy of an object by using the currently configured instantiation policy (see Section 119.28, "Configuring Instantiation Policy").

• Method: TopLink creates a new copy of an object by calling a method on the object that you specify. For example, you can specify the object's clone method (or any other appropriate method on the object). Note that the clone method should return a shallow clone of the object.

119.30 Configuring Change Policy

Use a change policy to specify how TopLink should track changes made to objects after you register them with a unit of work. Table 119-34 summarizes which descriptors support a change policy.

Table 119-34 Descriptor Support for Change Policy

Descriptor	Deferred Change Detection Policy	Object-Level Change Tracking Policy	Attribute Change Tracking Policy	How to Use Oracle JDeveloper	How to Use TopLink Workbench	How to Configure Change Policy Using Java
Relational DescriptorsFoot 1
Object-Relational Data Type Descriptors
EIS DescriptorsFoot 2
XML Descriptors

^Footnote 1 Relational class descriptors only (see Section 22.2.1.1, "Creating Relational Class Descriptors").

^Footnote 2 EIS root descriptors only (see Section 75.2.1.1, "EIS Root Descriptors").

By default, TopLink uses the deferred change detection policy.

For JPA entities or POJO classes that you configure for weaving, TopLink weaves value holder indirection for one-to-one mappings. If you want TopLink to weave change tracking and your application includes collection mappings (one-to-many or many-to-many), then you must configure all collection mappings to use transparent indirect container indirection only (you may not configure your collection mappings to use eager loading nor value holder indirection).

Mutable basic mappings affect the overhead of change tracking. TopLink can only weave an attribute change tracking policy for immutable mappings.

TopLink logs a warning message at the CONFIG log level if you try to weave a descriptor that does not support change policy.

TopLink supports alternative change policies (policies other than DeferredChangeDetectionPolicy) for attributes that use a subset of the mappings that TopLink supports.

For CMP and JPA applications deployed to OC4J TopLink automatically uses the attribute change tracking policy.

For more information, see the following:

• Section 113.2.3, "Unit of Work and Change Policy"

• Section 113.2.3.4, "Change Policy Mapping Support"

• Section 2.10, "Using Weaving"

• "Using EclipseLink JPA Weaving" section of EclipseLink Developer's Guide at http://wiki.eclipse.org/Using_EclipseLink_JPA_Extensions_%28ELUG%29#Using_EclipseLink_JPA_Weaving

• Section 2.4.1.4, "Using Method and Direct Field Access"

• Section 2.8.11, "Mutability"

119.31 Configuring a History Policy

If you want to use historical sessions (see Section 87.6, "Historical Sessions") to execute historical queries (see Section 108.11, "Historical Queries") against a historical schema of your own design, configure your descriptors with a TopLink HistoryPolicy that describes your historical schema.

If you are using Oracle Database platform for Oracle9i Database (or later), you can query the historical versions of objects automatically maintained by Oracle Database without the need for a history policy. For more information, see Section 93.1.1, "How to Configure Historical Sessions Using an Oracle Platform".

Table 119-35 summarizes which descriptors support history policy configuration.

Table 119-35 Descriptor Support for History Policy Configuration

Descriptor	How to Use Oracle JDeveloper	How to Use TopLink Workbench	How to Configure a History Policy Using Java
Relational Descriptors
Object-Relational Data Type Descriptors
EIS Descriptors
XML Descriptors

There are many ways to configure a historical database schema. TopLink supports several historical schema configurations that you can describe with a HistoryPolicy (see Section 87.6.1, "Historical Session Limitations").

Example Historical Schema

As shown in Table 119-36 and Table 119-37, a common approach is to define a special history table to store past versions of an object: one history table for each regular table that requires historical persistence. The history table typically has the same fields as the corresponding regular table plus fields (such as row start and end) used to define an interval that represents the life time of a particular version.

TopLink will include the history tables described by a HistoryPolicy when you execute a historical query.

Table 119-36 shows the schema for an EMPLOYEE table. The table currently contains one EMPLOYEE instance.

Table 119-37 shows one possible history table EMPLOYEE_HIST that stores historical versions of employees. The table contains the current EMPLOYEE (the version with a ROW_END value of NULL) and one historical version.

Because every record has a start and end interval, the history table can store multiple versions of the same object (with the same primary key). The unique identifier of a particular version is given by the existing primary key, plus the value of the start field. For example, in Table 119-37, the unique identifier of the current version is given by (EMP_ID, START) = (1, 31/08/2004).

HistoryPolicy policy = new HistoryPolicy();
policy.addStartFieldName("ROW_START");
policy.addEndFieldName("ROW_END");
policy.addHistoryTableName("EMPLOYEE", "EMPLOYEE_HIST");
// Assuming database triggers or stored procedures update history tables
policy.setShouldHandleWrites(false);

employeeDescriptor.setHistoryPolicy(policy);

HistoryPolicy policy = new HistoryPolicy();
policy.addStartFieldName("ROW_START");
policy.addEndFieldName("EMPLOYEE_HIST.ROW_END");
policy.addEndFieldName("SALARY_HIST.VALID_UNTIL");
policy.addHistoryTableName("EMPLOYEE", "EMPLOYEE_HIST");
policy.addHistoryTableName("SALARY", "SALARY_HIST");
// Assuming database triggers or stored procedures update history tables
policy.setShouldHandleWrites(false);

employeeDescriptor.setHistoryPolicy(policy);

119.32 Configuring Wrapper Policy

TopLink lets you use wrappers (or proxies) in cases where the persistent class is not the same class that is to be presented to users.

For example, in the EJB specification prior to 3.0, the entity bean class (the class that implements javax.ejb.EntityBean) is persistent, but is hidden from users who interact with a class that implements javax.ejb.EJBObject (local or remote interface class). In this example, the EJBObject acts as a proxy (or wrapper) for the EntityBean.

In cases where such a wrapper is used, TopLink continues to make the class specified in the descriptor persistent, but returns the appropriate instance of the wrapper whenever a persistent object is requested.

Table 119-38 summarizes which descriptors support a wrapper policy.

Table 119-38 Descriptor Support for Wrapper Policy

Descriptor	How to Use Oracle JDeveloper	How to Use TopLink Workbench	How to Configure Wrapper Policy Using Java
Relational Descriptors
Object-Relational Data Type Descriptors
EIS Descriptors
XML Descriptors

Use a wrapper policy to tell TopLink how to create wrappers for a particular persistent class, and how to obtain the underlying persistent object from a given wrapper instance.

If you specify a wrapper policy, TopLink uses the policy to wrap and unwrap persistent objects as required:

• Wrapper policies implement the interface oracle.toplink.descriptors.WrapperPolicy.

• A wrapper policy is specified by setting the wrapper policy for the TopLink descriptor.

• By default, no wrapper policy is used (the wrapper policy for a descriptor is null by default).

For CMP descriptors, the EJB wrapper policy is automatically configured during deployment, so does not need to be set in the descriptor (see Section 119.18, "Configuring a Descriptor with EJB CMP and BMP Information").

For BMP descriptors, you must set a BMPWrapperPolicy on the descriptor. The BMPWrapperPolicy includes the bean's information including the bean-name, primary-key-class, home-interface, and remote-interface.

Wrapper policies cannot be set using Oracle JDeveloper or TopLink Workbench and can be set only using Java code (see Section 119.32.1, "How to Configure Wrapper Policy Using Java").

public static void addToDescriptor(ClassDescriptor descriptor) {
    BMPWrapperPolicy policy = new BMPWrapperPolicy(
                                           "employee",
                                           EmployeeHome.class,
                                           EmployeePK.class,
                                           Employee.class,
                                           new Hashtable());
    descriptor.setWrapperPolicy(policy);

119.33 Configuring Fetch Groups

By default, when you execute an object-level read query for a particular object class, TopLink returns all the persistent attributes mapped in the object's descriptor. With this single query, all the object's persistent attributes are defined, and calling their get methods returns the value directly from the object.

When you are interested in only some of the attributes of an object, it may be more efficient to return only a subset of the object's attributes using a fetch group.

Using a fetch group, you can define a subset of an object's attributes and associate the fetch group with either a ReadObjectQuery or ReadAllQuery query. When you execute the query, TopLink retrieves only the attributes in the fetch group. TopLink automatically executes a query to fetch all the attributes excluded from this subset when and if you call a get method on any one of the excluded attributes.

You can define more than one fetch group for a class. You can optionally designate at most one such fetch group as the default fetch group. If you execute either a ReadObjectQuery or ReadAllQuery query without specifying a fetch group, TopLink will use the default fetch group, unless you configure the query otherwise (see Section 111.3.1, "How to Configure Default Fetch Group Behavior").

You can use fetch groups in CMP or JPA projects for EJB objects, as well as for POJO classes.

Before using fetch groups, Oracle recommends that you perform a careful analysis of system use. In many cases, the extra queries required to load attributes not in the fetch group could well offset the gain from the partial attribute loading. For more information about optimizing read performance, see Section 12.12.9, "Read Optimization Examples".

Table 119-39 summarizes which descriptors support fetch group configuration.

Table 119-39 Descriptor Support for Fetch Group Configuration

Descriptor	How to Use Oracle JDeveloper	How to Use TopLink Workbench	How to Configure Fetch Groups Using Java
Relational Descriptors
Object-Relational Data Type Descriptors
EIS Descriptors
XML Descriptors

For JPA entities or POJO classes that you configure for weaving, TopLink uses fetch groups to improve performance.

This section describes how to create a fetch group, store it in a descriptor, and optionally designate a fetch group as the default fetch group for its descriptor reference class.

For more information, see the following:

• Section 16.2.4, "Fetch Groups"

• Section 108.7.1.6, "Fetch Groups and Object-Level Read Queries"

• Section 111.3.1, "How to Configure Default Fetch Group Behavior"

• Section 2.10, "Using Weaving"

• "Using EclipseLink JPA Weaving" section of EclipseLink Developer's Guide at http://wiki.eclipse.org/Using_EclipseLink_JPA_Extensions_%28ELUG%29#Using_EclipseLink_JPA_Weaving

//Create a FetchGroupManager for the descriptor
descriptor.setFetchGroupManager(new FetchGroupManager());
// Create a FetchGroup
FetchGroup group = new FetchGroup("nameOnly");
// Add attributes to FetchGroup. Alternatively, use
// FetchGroup method addAttributes, passing in a Set of String attribute names
group.addAttribute("firstName");
group.addAttribute("lastName");
// Add the FetchGroup to the FetchGroupManager
descriptor.getFetchGroupManager().addFetchGroup(group);
//Set the default fetch group
descriptor.getFetchGroupManager().setDefaultFetchGroup(group);

119.34 Configuring a Descriptor Customizer Class

A descriptor customizer class is a Java class that implements the oracle.toplink.tools.sessionconfiguration.DescriptorCustomizer interface and provides a default (zero-argument) constructor. You can use a descriptor customizer to customize a descriptor at run time on a loaded session before login occurs, similar to how you can use an amendment method (see Section 119.35, "Configuring Amendment Methods").

Table 119-40 summarizes which sessions support customizer class configuration.

Table 119-40 Descriptor Support for Customizer Class Configuration

Descriptor	How to Use Oracle JDeveloper	How to Use TopLink Workbench	How to Configure Customizer Class Using Java
Relational Descriptors
Object-Relational Data Type Descriptors
EIS Descriptors
XML Descriptors

For more information, see Section 16.2.6, "Descriptor Customization".

import oracle.toplink.tools.sessionconfiguration.DescriptorCustomizer;
import oracle.toplink.descriptors.ClassDescriptor;

public class EmployeeDescriptorCustomizer implements DescriptorCustomizer {

    public void customize(ClassDescriptor descriptor) {
        descriptor.setReadOnly();
    }
}

119.35 Configuring Amendment Methods

Some TopLink descriptor features cannot be configured from Oracle JDeveloper or TopLink Workbench. To use these features, you must write a Java method to amend the descriptor after it is loaded as part of the project. This method must have the following characteristics:

• Be public static.

• Take a single parameter of type oracle.toplink.descriptors.ClassDescriptor.

In the implementation of this method, you can configure advanced features of the descriptor using any of the public descriptor and mapping API.

Table 119-41 summarizes which descriptors support amendment methods.

Table 119-41 Descriptor Support for Amendment Methods

Descriptor	How to Use Oracle JDeveloper	How to Configure Amendment Methods Using TopLink Workbench	How to Use Java
Relational Descriptors
Object-Relational Data Type Descriptors
EIS Descriptors
XML Descriptors

This section describes how to associate an amendment method with a descriptor.

For more information about how to implement an amendment method, see Section 16.2.7, "Amendment and After-Load Methods".

Alternatively, you can use a descriptor customizer class (see Section 119.34, "Configuring a Descriptor Customizer Class"

To customize a session, use a session customizer class (see Section 89.8, "Configuring a Session Customizer Class").