Understanding Interface Descriptors

An interface descriptor is a descriptor whose reference class is an interface. Each domain class specified in TopLink has a related descriptor. A descriptor is a set of mappings that describes how an object's data is represented in a relational database. It contains mappings from the class instance variable to the table's fields, as well as the transformation routines necessary for storing and retrieving attributes. The descriptor acts as the link between the Java object and its database representation.

An interface is a collection of abstract behavior that other classes can use. It is a purely Java object concept and has no representation on the relational database. Therefore, a descriptor defined for the interfaces does not map any relational entities on the database.

Note: You cannot create or edit interface descriptors in the TopLink Mapping editor.

Here are the components defined in the interface descriptor:

The Java interface it describes
The parent interface(s) it implements
A list of abstract query keys

An interface descriptor does not define any mappings, because there is no concrete data or table associated with it. A list of abstract query keys is defined so that you can issue queries on the interfaces. A read query on the interface results in reading one or more of its implementors.

The following illustration shows an interface implemented by two descriptors.

Figure 4-22 Classes Implement an Interface

This figure shows the implementation of a interface descriptor.

Following is the sample code implementation for the descriptors for Email and Phone:

Descriptor descriptor = new Descriptor();
  descriptor.setJavaInterface(Contact.class);
  descriptor.addAbstractQueryKey("id");
  return descriptor;
Descriptor descriptor = new Descriptor();
  descriptor.setJavaClass(Email.class);
  descriptor.addDirectQueryKey("id", "E_ID");
  descriptor.getInterfacePolicy().addParentInterface(Contact.class);
  descriptor.setTableName("INT_EML");
  descriptor.setPrimaryKeyFieldName("E_ID");
  descriptor.setSequenceNumberName("SEQ");
  descriptor.setSequenceNumberFieldName("E_ID");
  descriptor.addDirectMapping("emailID", "E_ID");
  descriptor.addDirectMapping("address", "ADDR");
  return descriptor;
Descriptor descriptor = new Descriptor();
  descriptor.setJavaClass(Phone.class);
  descriptor.getInterfacePolicy().addParentInterface(Contact.class);
  descriptor.addDirectQueryKey("id", "P_ID");
  descriptor.setTableName("INT_PHN");
  descriptor.setPrimaryKeyFieldName("P_ID");
  descriptor.setSequenceNumberName("SEQ");
  descriptor.setSequenceNumberFieldName("P_ID");
  descriptor.addDirectMapping("phoneID", "P_ID");
  descriptor.addDirectMapping("number", "P_NUM");
  return descriptor;

If the Contact interface extended another interface, you would call the following method to set its parent:

descriptor.getInterfacePolicy().addParentInterface(Interface.class);

Single Implementor Interfaces

Use single implementor interfaces for applications where only the domain objects' interface is visible. Each domain class has its own unique interface, and no other domain class implements it. The references to other domain objects are also through interfaces.

In such applications, defining a descriptor for each interface would be expensive and may be unnecessary. TopLink does not force you to define descriptors for such interfaces. The descriptors are defined for the domain classes, and the parent interface is set as usual.

During the initializing of a descriptor, the interface is given the descriptor of its implementor. This process allows queries on both the domain class and its interface. The only restriction is that each interface should have a unique implementor. In other words, a descriptor is not needed for an interface unless it has multiple implementors.