Configuring Inheritance Expressions for a Parent (Root) Class Descriptor

If your class uses inheritance (see "Understanding Descriptors and Inheritance") with a class extraction method (see "Using Class Extraction Methods") you must provide TopLink with expressions to correctly filter sibling instances for all classes that share a common table.

Table 28-23 summarizes which descriptors support inheritance expression configuration.

Table 28-22 Descriptor Support for Inheritance Expression Configuration

Descriptor	Using TopLink Workbench	Using Java
Relational Descriptors
Object-Relational Descriptors
EIS Descriptors
XML Descriptors

Figure 28-34 shows a typical inheritance hierarchy. In this example, instances of both Person and Student are stored in the same PERSON table as Figure 28-35 shows: an instance of Person has a null value for STUDENT_NUMBER. Instances of Company are stored in a separate COMPANY table.

Figure 28-34 Example Inheritance Hierarchy

Description of "Figure 28-34 Example Inheritance Hierarchy"

Figure 28-35 PERSON Table

Description of "Figure 28-35 PERSON Table"

Queries on inheritance classes that share a common table, such as Person and Student, must filter out their sibling instances. TopLink performs this filtering using the Expression instances returned by the descriptor's InheritancePolicy methods getOnlyInstancesExpression and getWithAllSubclassesExpression.

Queries on a class that has its own table for its specific data, such as Company, and does not share this table with any sibling classes, do not require these expressions.

If you use a class indicator type field (see "Using Class Indicator Fields"), TopLink automatically generates the required expressions.

If you use a class extraction method (see "Using Class Extraction Methods"), you must provide TopLink with an expressions to correctly filter sibling instances for all classes that share a common table.

For concrete classes, you must define an only- instances expression.

For branch classes, you must define a with-all-subclasses expression.

When TopLink queries for a leaf class, it uses the only- instances expression to filter out any sibling classes.

When TopLink queries for a root or branch class whose subclasses do not define their own tables, it uses the with-all-subclasses expression. This is also the case when a subclass view is used (see "Configuring Reading Subclasses on Queries").

When querying for a root or branch class that has subclasses that span multiple tables, a query is performed for each concrete class in the inheritance hierarchy using the only- instances expression to filter sibling classes.

When a class extraction method is used the only-instances expression is used to determine if a class is concrete. If a class does not require an only instances expression, do not enable reading subclasses on queries (see "Configuring Reading Subclasses on Queries"), otherwise TopLink will assume that the class has no instances and it will skip that class on queries.

For more information about inheritance expressions, see "Specifying Expressions for Only-Instances and With-All-Subclasses".

Using Java

Create a descriptor amendment method ("Configuring Amendment Methods") to customize the root class descriptor's InheritancePolicy using InheritancePolicy methods setOnlyInstancesExpression and setWithAllSubclassesExpression, as required.

Example 28-13 shows amendment methods for the Person and Student descriptors based on the class hierarchy shown in Figure 28-34 and the database table shown in Figure 28-35.

Example 28-13 Configuring Only-Instances Expressions

...
// Only-instances expression for Person
public static void addToPersonDescriptor(Descriptor descriptor) {
    ExpressionBuilder builder = new ExpressionBuilder();
    descriptor.getInheritancePolicy().setOnlyInstancesExpression(
        builder.getField("STUDENT_NUMBER").isNull()
    );
}
// Only-instances expression for Student
public static void addToStudentDescriptor(Descriptor descriptor) {
    ExpressionBuilder builder = new ExpressionBuilder();
    descriptor.getInheritancePolicy().setOnlyInstancesExpression(
        builder.getField("STUDENT_NUMBER").notNull()
    );
}
...

Example 28-14 shows amendment methods for the Bicycle and NonFueledVehicle descriptors based on the class hierarchy shown in Figure 26-2 if the vehicle hierarchy stored all of the classes in a single vehicle table, and there was not a class indicator, but a class extraction method instead.

Example 28-14 Configuring Only-Instances and With-All-Subclasses Expressions

// Bicycle amemndment
public static void addToBicycleDescriptor(Descriptor descriptor) {
    ExpressionBuilder builder = new ExpressionBuilder();
    descriptor.getInheritancePolicy().setOnlyInstancesExpression(
        builder.getField("BICYCLE_DESCR").notNull()
    );
}

// NonFueldVehicle ammendment
public static void addToNonFueledVehicleDescriptor(Descriptor descriptor) {
    ExpressionBuilder builder = new ExpressionBuilder();
    descriptor.getInheritancePolicy().setWithAllSubclassesExpression(
        builder.getField("FUEL_TYPE").isNull()
    );
}