Working with Query Keys

Use a direct query key as an alias for a field name. Query keys allow OracleAS TopLink expressions to refer to a field using Java attribute names (such as firstName), rather than DBMS-specific names (such as F_NAME).

Use query keys to:

Enhance code readability when defining OracleAS TopLink expressions.
Increase portability by making code independent of the database schema. If you rename a field, the query key could be redefined without changing any code that references it.
Interface descriptors define only common query keys shared by implementors; the fields aliased could have different names in the implementor's tables.

Automatically-generating Query Keys

OracleAS TopLink automatically defines direct query keys for all direct mappings and has a special query key type for each mapping. Typically, use query keys to access fields that do not have direct mappings, such as the version field used for optimistic locking or the type field used for inheritance.

OracleAS TopLink displays automatically generated queries in the Query Keys tab of the Editor pane (see Figure 4–15). You cannot change these keys.

Automatically Generated Query KeyFor example, consider the Employee class in the OracleAS TopLink tutorial: When you define a direct-to-field mapping from the Employee class (attribute firstName) to the EMPLOYEE table (field F_NAME) you get a query key for free — it is automatically generated.The following code example illustrates using an automatically generated query key within the OracleAS TopLink expression framework.Vector employees = session.readAllObjects(Employee.class, new ExpressionBuilder().get("firstName").equal("Bob"));

Using Query Keys in Interface Descriptors

Interface descriptors are defined only with query keys that are shared among their implementors. In the descriptor for the interface, only the name of the query key is specified.

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

Doing this ensures that a single query key can be used to specify foreign key information from a descriptor that contains a mapping to the interface, even if the field names differ.

Consider an Employee that contains a contact, of type Contact. Contact is an interface with two implementors: Phone and EmailAddress. Each class has two attributes. The following figure illustrates the generated keys:

Figure 4-35 Contact interface Descriptor with Common Query Key id

Description of the illustration atgenkey.gif

Note:

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, indicate that the id query key must be defined for each of the implementors, as Figure 4-36 illustrates.

Figure 4-36

Description of the illustration conintds.gif

Note:

If either of the implementor classes did not have the id query key defined, that descriptor would be flagged 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. For example, you can now create a 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.

See "Working with Interfaces" and "Working with Relationship Mappings" on page 6-2 for more information.

Relationship Query Keys

OracleAS TopLink supports query keys for relationship mappings and automatically defines them for all relationship mappings. You can use these keys to join across a relationship. One-to-one query keys define a joining relationship and are accessed through the get() method in expressions.

One-to-many and many-to-many query keys define a distinct join across a collection relationship and are accessed through the anyOf() method in expressions. You can also define relationship query keys manually if mapping does not exist for the relationship. The relationship defined by the query key is data-level expressions.

Example 4-3 One-to-one Query Key

The following code example illustrates using a one-to-one query key within the OracleAS TopLink expression framework.

ExpressionBuilder employee = new ExpressionBuilder();
Vector employees = session.readAllObjects(Employee.class, employee.get("address").get("city").equal("Ottawa"));

Defining Relationship Query Keys by Amending a Descriptor

Relationship query keys are not supported directly in the OracleAS TopLink Mapping Workbench. To define a relationship query key, you must specify and write an amendment method. Register query keys by sending the addQueryKey() message.

Example 4-4 Defining One-to-one Query Key Example

The following code example illustrates how to define a one-to-one query key:

// 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);
}