7 Using EJB 3.0 Persistence API

Configuring an EJB 3.0 Entity Primary Key

Every EJB 3.0 entity must have a primary key field (see "Configuring an EJB 3.0 Entity Primary Key Field").

You can specify a primary key as a single primitive or JDK object type.

You can either assign primary key values yourself, or, more typically, you can associate a primary key field with a primary key value generator (see "Configuring EJB 3.0 Entity Automatic Primary Key Generation").

@Id(generate=TABLE, generator="ADDRESS_TABLE_GENERATOR")
@TableGenerator(
    name="ADDRESS_TABLE_GENERATOR", 
    tableName="EMPLOYEE_GENERATOR_TABLE", 
    pkColumnValue="ADDRESS_SEQ"
)
@Column(name="ADDRESS_ID")
public Integer getId()
{
    return id;
}

@Entity
@Table(name="EJB_EMPLOYEE")
@GeneratedIdTable(
    name="EMPLOYEE_GENERATOR_TABLE", 
    table=@Table(name="EJB_EMPLOYEE_SEQ"), 
    pkColumnName="SEQ_NAME", valueColumnName="SEQ_COUNT"
)
public class Employee implements Serializable
{
...
    @Id(generate=TABLE, generator="EMPLOYEE_GENERATOR_TABLE")
    @Column(name="EMPLOYEE_ID", primaryKey=true)
    public Integer getId()
    {
        return id;
    }
...
}

@Entity
@Table(name="EJB_ADDRESS")
public class Address implements Serializable
{
...
    @Id(generate=TABLE, generator="ADDRESS_TABLE_GENERATOR")
    @TableGenerator(
        name="ADDRESS_TABLE_GENERATOR", 
        tableName="EMPLOYEE_GENERATOR_TABLE", 
        pkColumnValue="ADDRESS_SEQ"
    )
    @Column(name="ADDRESS_ID")
    public Integer getId()
    {
        return id;
    }
...
}

@Entity
@Table(name="EJB_ADDRESS")
public class Address implements Serializable
{
...
    @Id(generate=SEQUENCE, generator="ADDRESS_TABLE_GENERATOR")
    @SequenceGenerator(
        name="ADDRESS_TABLE_GENERATOR",
        sequenceName="ADDRESS_SEQ"
    )
    @Column(name="ADDRESS_ID")
    public Integer getId()
    {
        return id;
    }
...
}

Configuring Table and Column Information

You can define the characteristics of the database table into which the TopLink persistence manager persists your entity, including:

• Configuring the Primary Table

• Configuring a Secondary Table

• Configuring a Column

• Configuring a Join Column

This is particularly important if you have an existing database schema.

If you do not have an existing database schema, you can delegate table and column definition to OC4J by omitting this configuration: at deployment time, OC4J will create default table and column names based on class and data member names.

@Entity
@Table(name="EJB_EMPLOYEE")
public class Employee implements Serializable
{
...
}

@Entity
@Table(name="EJB_EMPLOYEE")
@SecondaryTable(name="EJB_SALARY")
public class Employee implements Serializable
{
...
}

@Column(name="F_NAME")
public String getFirstName()
{
    return firstName;
}

@Column(name="SALARY", secondaryTable="EMP_SALARY")
public String getSalary()
{
    return salary;
}

@Entity
@Table(name="EJB_EMPLOYEE")
@SecondaryTable(name="EJB_SALARY")
@JoinColumn(name="EMP_ID", referencedColumnName="EMP_ID")
public class Employee implements Serializable
{
...
}

@OneToOne(cascade=ALL, fetch=LAZY)
@JoinColumn(name="ADDR_ID")
public Address getAddress()
{
    return address;
}

@ManyToOne(cascade=PERSIST, fetch=LAZY)
@JoinColumn(name="MANAGER_ID", referencedColumnName="EMP_ID")
public Employee getManager()
{
    return manager;
}

@OneToMany(cascade=PERSIST)
@JoinColumn(name="MANAGER_ID", referencedColumnName="EMP_ID")
public Collection getManagedEmployees()
{
    return managedEmployees;
}

Configuring an EJB 3.0 Entity Container-Managed Relationship Field

In an EJB 3.0 entity, you define container-managed relationship (CMR) fields (see "What are Container-Managed Relationship Fields?") as follows:

• "Configuring a Basic Mapping"

• "Configuring a Large Object Mapping"

• "Configuring a Serialized Object Mapping"

• "Configuring a One-to-One Mapping"

• "Configuring a Many-to-One Mapping"

• "Configuring a One-to-Many Mapping"

• "Configuring a Many-to-Many Mapping"

Configuring a Basic Mapping

Use a basic mapping to map an field that contains a primitive or JDK object value. For example, use a basic mapping to store a String attribute in a VARCHAR column.

You define a basic mapping at one of the property (getter or setter method) or field level of your entity.

For more information, see "Understanding Direct-to-Field Mapping" in the Oracle TopLink Developer's Guide.

@Basic(fetch=EAGER)
@Column(name="F_NAME")
public String getFirstName()
{
    return firstName;
}

Configuring a Large Object Mapping

Use a large object (LOB) mapping to specify that a persistent property or field should be persisted as a LOB to a database-supported LOB type. A LOB may be either a binary (BLOB) or character (CLOB) type.

You define a large object mapping at one of the property (getter or setter method) or field level of your entity.

For more information, see:

• "Understanding Direct-to-Field Mapping" in the Oracle TopLink Developer's Guide

• "Using a Converter Mapping" in the Oracle TopLink Developer's Guide

• "Type Conversion Converter" in the Oracle TopLink Developer's Guide

@Lob(fetch=EAGER, type=BLOB)
@Column(name="IMAGE")
public Byte[] getImage() 
{
    return image;
}

Configuring a Serialized Object Mapping

Use a serialized object mapping to specify that a persistent property should be persisted as a serialized stream of bytes.

You define a serialized object at one of the property (getter or setter method) or field level of your entity.

For more information, see:

• "Understanding Direct-to-Field Mapping" in the Oracle TopLink Developer's Guide

• "Using a Converter Mapping" in the Oracle TopLink Developer's Guide

• "Serialized Object Converter" in the Oracle TopLink Developer's Guide

@Serialized(fetch=EAGER)
@Column(name="PICTURE")
public Byte[] getPicture() 
{
    return picture;
}

Configuring a One-to-One Mapping

Use a one-to-one mapping to represent simple pointer references between two Java objects. In Java, a single pointer stored in an attribute represents the mapping between the source and target objects. Relational database tables implement these mappings using foreign keys.

You define a one-to-one mapping at one of the property (getter or setter method) or field level of your entity.

For more information, see "Understanding One-to-One Mapping" in the Oracle TopLink Developer's Guide.

@OneToOne(cascade=ALL, fetch=LAZY)
@JoinColumn(name="ADDR_ID")
public Address getAddress()
{
    return address;
}

Configuring a Many-to-One Mapping

Use a many-to-one mapping to represent simple pointer references between two Java objects. In Java, a single pointer stored in an attribute represents the mapping between the source and target objects. Relational database tables implement these mappings using foreign keys.

You define a many-to-one mapping at one of the property (getter or setter method) or field level of your entity.

For more information, see "Understanding One-to-One Mapping" in the Oracle TopLink Developer's Guide.

@ManyToOne(cascade=PERSIST, fetch=LAZY)
@JoinColumn(name="MANAGER_ID", referencedColumnName="EMP_ID")
public Employee getManager()
{
    return manager;
}

Configuring a One-to-Many Mapping

Use a one-to-many mapping to represent the relationship between a single source object and a collection of target objects. This relationship is a good example of something that is simple to implement in Java using a Vector (or other collection types) of target objects, but difficult to implement using relational databases.

You define a one-to-many mapping at one of the property (getter or setter method) or field level of your entity.

For more information, see "Understanding One-to-Many Mapping" in the Oracle TopLink Developer's Guide.

@OneToMany(cascade=PERSIST)
@JoinColumn(name="MANAGER_ID", referencedColumnName="EMP_ID")
public Collection getManagedEmployees()
{
    return managedEmployees;
}

Configuring a Many-to-Many Mapping

Use a many-to-many mapping to represent the relationships between a collection of source objects and a collection of target objects. This mapping requires the creation of an intermediate table (the association table) for managing the associations between the source and target records.

You define a many-to-many mapping at one of the property (getter or setter method) or field level of your entity.

For more information, see "Understanding Many-to-Many Mapping" in the Oracle TopLink Developer's Guide.

@ManyToMany(cascade=PERSIST)
@AssociationTable(
    table=@Table(name="EJB_PROJ_EMP"),
    joinColumns=@JoinColumn(name="EMP_ID", referencedColumnName="EMP_ID"),
    inverseJoinColumns=@JoinColumn(name="PROJ_ID", referencedColumnName="PROJ_ID")
)
public Collection getProjects()
{
    return projects;
}

Configuring an Aggregate Mapping

Two entities–an owning (parent or source) entity and an owned (child or target) entity–are related by aggregation if there is a strict one-to-one relationship between them and all the attributes of the owned entity can be retrieved from the same table(s) as the owning entity. This means that if the owning entity exists, then the owned entity must also exist and if the owning entity is destroyed, then the owned entity is also destroyed.

An aggregate mapping allows you to associate data members in the owned entity with fields in the owning entity's underlying database tables.

In the owning entity, you designate the owned field or setter as embedded.In owned entity, you designate the class as embeddable and associate it with the owning entity's table name.

In the owning entity, you can override any column specifications (see "Configuring a Column") made in the owned entity.

For more information, see "Understanding Aggregate Mapping" in the Oracle TopLink Developer's Guide.

@Entity
@Table(name="EJB_EMPLOYEE")
public class Employee implements Serializable
{
...
    @Embedded
    public EmploymentPeriod getPeriod()
    {
        return period;
    }
...
}

@Embeddable
@Table(name="EJB_EMPLOYEE")
public class EmploymentPeriod implements Serializable
{
    private Date startDate;
    private Date endDate;
...
}

@Entity
@Table(name="EJB_EMPLOYEE")
public class Employee implements Serializable
{
...
    @Embedded(
        {
            @AttributeOverride(name="startDate", column=@Column("EMP_START")),
            @AttributeOverride(name="endDate", column=@Column("EMP_END"))
        }
    )
    public EmploymentPeriod getPeriod()
    {
        return period;
    }
...
}

@Embeddable
@Table(name="EJB_EMPLOYEE")
public class EmploymentPeriod implements Serializable
{
    @Column("START_DATE")
    private Date startDate;

    @Column("END_DATE")
    private Date endDate;
...
}

Configuring Optimistic Lock Version Field

You can specify an entity field to function as a version field for use in a TopLink optimistic version locking policy. OC4J uses this version field to ensure integrity when reattaching (see "Detaching and Merging an Entity Bean Instance") and for overall optimistic concurrency control.

You define the optimistic lock version field at one of the property (getter or setter method) or field level of your entity.

For more information, see "Optimistic Version Locking Policies" in the Oracle TopLink Developer's Guide.

@Version
@Column(name="VERSION")
public int getVersion()
{
    return version;
}

Configuring Lazy Loading on Finder Methods

Lazy loading is an Oracle-specific option that you configure using the EJB 2.1 orion-ejb-jar.xml file.

For more information, see "Configuring Lazy Loading on Finder Methods".

Configuring a Lifecycle Callback Method for an EJB 3.0 Entity

You can specify an EJB 3.0 entity class method as a callback method for any of the following lifecycle events:

• Pre-persist: a method called on an object when that object has the create operation applied to it.

• Post-persist: a method called on an object that has just been inserted into the database. You can use this method to notify any of the object's dependents or to update information not accessible until the object has been inserted.

• Pre-remove: a method called on an object when that object has the remove operation applied to it.

• Post-remove: a method called on an object that has just been deleted from the database. You can use this method to notify or remove any of the object's dependents.

• Pre-update: a method called when an object's row is about to be updated.

  The TopLink persistence manager calls this method only if it determines that an actual update is required (only if it is prepared to send SQL to the database). Contrast this with a post-update callback which is called whether or not an actual change was required.

  You can use this method to modify the row before insert.

• Post-update: a method called on an object that has just been updated into the database.

  Use this callback to update any dependent objects.

  The TopLink persistence manager calls this method even if it determines that no actual update is required (even if it determines that no SQL needs to be sent to the database). Use the pre-update callback if you want to be notified only when the object has actually been changed.

• Post-load: a method called on an object that has just been built from the database. This event can be used to correctly initialize an object's non-persistent attributes or to perform complex optimizations or mappings. This event is called whenever an object is built.

The entity class method must have the following signature:

public int <MethodName>()

For more information, see:

• "Callback Methods"

• "Descriptor Event Manager" in the Oracle TopLink Developer's Guide

• "Configuring a Domain Object Method as an Event Handler" in the Oracle TopLink Developer's Guide

@PrePersist
public int initialize()
{
  ...
}

Configuring Inheritance for an EJB 3.0 Entity

OC4J supports the following inheritance strategies for mapping a class or class hierarchy to a relational database schema:

• Joined Subclass

• Single Table for each Class Hierarchy

You can configure either approach using annotations (see "Using Annotations").

@Entity
@Table(name="EJB_PROJECT")
@Inheritance(strategy=JOINED, discriminatorValue="P")
@DiscriminatorColumn(name="PROJ_TYPE")
public class Project implements Serializable
{
...
    @Id()
    @Column(name="PROJECT_ID", primaryKey=true)
    public Integer getId()
    {
        return id;
    }
...
}

@Entity
@Table(name="EJB_LPROJECT")
@Inheritance(discriminatorValue="L")
@InheritanceJoinColumn(name="LARGE_PROJECT_ID")
public class LargeProject extends Project
{
...
    @Id()
    @Column(name="LARGE_PROJECT_ID", primaryKey=true)
    public Integer getProjectId()
    {
        return projectId;
    }
...
}

@Entity
@Table(name="EJB_PROJECT")
@Inheritance(discriminatorValue="S")
public class SmallProject extends Project
{
...
}

@Entity
@Table(name="EJB_PROJECT")
@Inheritance(strategy=SINGLE_TABLE, discriminatorValue="P")
@DiscriminatorColumn(name="PROJ_TYPE")
public class Project implements Serializable
{
...
}

@Entity
@Inheritance(discriminatorValue="L")
public class LargeProject extends Project
{
...
}

@Entity
@Inheritance(discriminatorValue="S")
public class SmallProject extends Project
{
...
}