Skip Headers

Oracle TopLink Developer's Guide 10g Release 3 (10.1.3) B13593-01 |
| Home | Solution Area | Contents | Index

Previous | Next |

# Configuring Interface Query Keys

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

Interface descriptors (see "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 28-11 summarizes which descriptors support interface query keys.

Table 28-12 Descriptor Support for Interface Query Keys

Descriptor | Using TopLink Workbench | Using Java
--- | --- | ---
Relational Descriptors |  |
Object-Relational 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 28-23 illustrates the generated keys:

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

Description of "Figure 28-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, TopLink Workbench flags 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 "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.

## Using TopLink Workbench

To choose the implementors of an interface that share at least one common automatically generated query key, use this procedure.

1. Select an interface descriptor in the Navigator. Its properties appear in the Editor.

   Figure 28-24 Interface Descriptor Editor Window

   Description of "Figure 28-24 Interface Descriptor Editor Window"

To choose an implementor of the selected interface that shares at least one common query key, click Add.

To remove an implementor of the selected interface, select the implementor and click Remove.

## Using Java

Example 28-7 shows how to define the `Contact` interface and `Email` and `Phone` implementors in Java.

Example 28-7 Defining Interface Query Keys

    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");