Working with Interfaces

An interface is a collection of method declarations and constants used by one or more classes of objects. Domain classes can implement interfaces or can reference existing interfaces. OracleAS TopLink supports interfaces in the following methods:

In a variable class relationship, a domain object references another domain object or a collection of objects that implement a specific interface.
A read query can be issued to query an interface.

Understanding Interface Descriptors

An interface descriptor is a descriptor whose reference class is an interface. Each domain class specified in OracleAS 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 OracleAS TopLink Mapping Workbench.

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-28 Classes Implement an Interface

Description of the illustration impintr.gif

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. OracleAS 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.

Implementing an Interface

One-to-one mappings that reference interfaces that have multiple implementors are known as variable one-to-one mappings. See Chapter 6, "Understanding Relationship Mappings", and Chapter 4, "Understanding Descriptors" for more information.

Use this procedure to implement an interface.

To configure an interface descriptor:

In the Navigator pane, select an interface.
On the Implementors tab in the Editor pane, click the descriptors that implement this interface and share at least one common query key.

Figure 4-29 Implementors Tab

Description of the illustration intrprop.gif

The Common Query Keys area displays all the query keys for the interface's implementors.

To specify a class descriptor as a single implementor of an interface:

In the Navigator pane, select the descriptor that will be the sole implementor of an interface.
If the Interface Alias advanced descriptor property is not visible for this descriptor, choose Set Advanced Properties > Interface Alias from the Selected menu or the pop-up menu to create the Interface Alias page.
Select the interface that will serve as an alias for this descriptor on the Interface Alias page. It is not necessary for this interface to have a descriptor in the project, and in fact, if an associated descriptor exists, it will be removed. Every instance of the interface will now be treated as an instance of this class as well.