Jump to: navigation, search

EclipseLink/UserGuide/JPA/Basic JPA Development/Entities/Inheritance

EclipseLink JPA

@Inheritance

You can use the @Inheritance annotation or <inheritance> XML element to configure how entities with inheritance are persisted. JPA defines three inheritance strategies SINGLE_TABLE, JOINED, and TABLE_PER_CLASS. By default the SINGLE_TABLE strategy is used and all of the subclasses are persisted in a single table that contains all of the column of all of the subclasses. In addition a discriminator column named DTYPE is required in the table to store the class type.

The @Inheritance annotation has the following attributes:

  • strategy – By default, the EclipseLink persistence provider assumes that all the classes in a hierarchy are mapped to a single table differentiated by the discriminator value (see @DiscriminatorValue) in the table's discriminator column (see @DiscriminatorColumn): InheritanceType.SINGLE_TABLE.
    If this is not appropriate for your application or if you must match an existing data model, set strategy to the desired InheritanceType enumerated type:
    • SINGLE_TABLE – all the classes in a hierarchy are mapped to a single table. The table has a discriminator column (@DiscriminatorColumn) whose value (@DiscriminatorValue) identifies the specific subclass to which the instance that is represented by the row belongs.

      Elug note icon.png

      Note: This option provides the best support for both polymorphic relationships between entities and queries that range over the class hierarchy. The disadvantages of this option include the need to make nullable columns that should be NOT NULL.


    • TABLE_PER_CLASS – each class is mapped to a separate table. All properties of the class, including inherited properties, are mapped to columns of the table for the class.
    • JOINED – the root of the class hierarchy is represented by a single table and each subclass is represented by a separate table. Each subclass table contains only those fields that are specific to the subclass (not inherited from its superclass) and primary key columns that serve as foreign keys to the primary keys of the superclass table.
Elug javaspec icon.gif

For more information, see Section 2.1.9 "Inheritance" in the JPA Specification.

Elug javaspec icon.gif

For more information, see Section 9.1.29 "Inheritance Annotation" in the JPA Specification.

@DiscriminatorColumn Attributes
Attribute Description Default Required?
name The name foreign key column in the secondary table that references the id column in the primary table id column No
referencedColumnName A name of the id column in the primary table that is being referenced. This is only required for composite ids. id column No
columnDefinition Optional column description for use with DDL generation. No
Elug javaspec icon.gif

For more information, see Section 11.1.xx "DiscriminatorColumn Annotation" in the JPA Specification.

The following example shows how to use this annotation to specify the table for Employee.

Example: Using @Inheritance
@Entity
@Table(name="EMP")
@SecondaryTable(name="SALARY")
public class Employee implements Serializable {
    ...
    @Id
    public Long getId() {
        return id;
    }
    ...
}
Example: Using <inheritance>
<entity class="Employee">
    <table name="EMP"/>
    <secondary-table name="SALARY"/>
    <attributes>
        <id name="id"/>
        ...
    </attributes>
</entity>


Advanced Inheritance Configuration

JPA requires that secondary tables contain the id of the entity. EclipseLink allows for the multiple table join to be based on foreign keys, or on specific criteria.

To define a secondary table that is joined through a foreign key, the ClassDescriptor.addForeignKeyFieldNameForMultipleTable() API is used. This column name given to this API should be prefixed by its table name, this allows for foreign keys from any of the secondary tables to be used in the multiple table join. Note that all of the column values still need to be mapped at least once.

If the multiple table join is more complex, an EclipseLink Expression can be used to define the join. The Expression is set on the ClassDescriptor's query manager using the DescriptorQueryManager.setMultipleTableJoinExpression() API. It is even possible to define a join Expression that make use of an outer-join on certain databases.

In certain advanced cases multiple tables can be encapsulated using a database view. This allows for any table join to be define in SQL and for the entity to be simply mapped to the view. To map an entity to a view, just use the view name instead of the table name. If the view is not updateable, your database may support instead of triggers to allow updates.

Example: Using a DescriptorCustomizer to configure a secondary table joined through a foreign key
@Entity
@Table(name="EMP")
@SecondaryTable(name="EMP_INFO")
@Customizer(EmployeeCustomizer.class)
public class Employee implements Serializable {
    @Id
    private Long id;
    @Basic
    @Column(name="ID", table="EMP_INFO")
    private String infoId;
    ...
}
public class EmployeeCustomizer implements DescriptorCustomizer {
    public void customize(ClassDescriptor descriptor) {
        descriptor.getAdditionalTablePrimaryKeyFields().clear();
        descriptor.getMultipleTableForeignKeys()().clear();
        descriptor.addForeignKeyFieldNameForMultipleTable("EMP.INFO_ID", "EMP_INFO.ID");
    }
}
Example: Using a DescriptorCustomizer to configure a secondary table joined through an Expression
@Entity
@Table(name="EMP")
@SecondaryTable(name="EMP_INFO")
@Customizer(EmployeeCustomizer.class)
public class Employee implements Serializable {
    @Id
    private Long id;
    @Basic
    @Column(name="ID", table="EMP_INFO")
    private String infoId;
    ...
}
public class EmployeeCustomizer implements DescriptorCustomizer {
    public void customize(ClassDescriptor descriptor) {
        ExpressionBuilder emp = new ExpressionBuilder();
        Expression join = emp.getField("EMP.INFO_ID").equal(emp.getField("EMP_INFO.ID").and(emp.getField("EMP_INFO.ARCHIVE").equal(false));
        descriptor.getQueryManager().setMultipleTableJoinExpression(join);
    }
}

Eclipselink-logo.gif
Version: 2.2.0 DRAFT
Other versions...