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