Defining Entity Mappings

Chapter 9 Generating Persistent Objects for Java and JSF Pages

Defining Entity Mappings

Set the stereotype of persistent classes to make them EJB 3 Entity classes. See the O/R Mapping Modeling chapter for information about defining entity class mappings.

The Entity annotation is generated to specify that the class is an entity.

@Entity
@Table(name="EMPLOYEE")
public class Employee { ... }

EJB 3 Entity Mapping Options

The following EJB3-specific mapping options can be set on the EJB 3 Persistence tab of the class property sheet.

Option	Description
Entity Name	Specifies that the class alias that can be used in EJB QL.
Access strategy	Specifies the default access type (FIELD or PROPERTY)
Schema name	Specifies the name of the database schema.
Catalog name	Specifies the name of the database catalog.
Mapping definition type	Specifies what will be generated for mapping meta data, the mapping file, annotations or both.
Discriminator value	Specifies the discriminator value to distinguish instances of the class

Mapping to Multiple Tables

In EJB 3, Entity classes can be mapped to multiple tables. See the O/R Mapping Modeling chapter for information on how to map one Entity class to multiple tables.

There is a check to guarantee that secondary tables have reference keys referring to primary tables.

The SecondaryTable annotation is generated to specify a secondary table for the annotated Entity class. The SecondaryTables annotation is used when there are multiple secondary tables for an Entity.

Defining Primary Identifier Mapping

Three kinds of primary identifier mapping are supported in EJB 3.0:

Simple identifier mapping - This kind of primary key can be generated automatically in EJB 3. You can define the generator class and parameters. There are four generator class types, Identity, Sequence, Table and Auto. Table generator and sequence generators require certain parameters. See the EJB 3.0 persistence specification for details.

You can define the generator class and parameters in the EJB 3 persistence tab of primary identifiers' property sheet. The parameters take the form of param1=value1; param2=value2.

The Id annotation generated specifies the primary key property or field of an entity. The GeneratedValue annotation provides for the specification of generation strategies for the values of primary keys:

@Id
@GeneratedValue(strategy=GenerationType.TABLE, generator="customer_generator")
@TableGenerator(
      name=" customer_generator",
      table="Generator_Table", 
      pkColumnName="id", 
      valueColumnName="curr_value",
      initialValue=4
)
@Column(name="cid", nullable=false)

Composite identifier mapping - The IdClass annotation will be generated for an entity class or a mapped superclass to specify a composite primary key class that is mapped to multiple fields or properties of the entity:

@IdClass(com.acme.EmployeePK.class)
@Entity
public class Employee {
  @Id String empName;
  @Id Date birthDay;
   ...
}

Embedded primary identifier mapping - corresponds to component primary identifier mapping. The EmbeddedId annotation is generated for a persistent field or property of an entity class or mapped superclass to denote a composite primary key that is an embeddable class:

@EmbeddedId
protected EmployeePK empPK;

Defining Attribute Mappings

Each persistent attribute with basic types can be mapped to one column. Follow instructions to define attribute mappings for this kind of persistent attributes.

The following EJB3-specific attribute mapping options are available on the EJB 3 Persistence tab of each attribute's property sheet:

Option	Description
Version attribute	Specifies if attribute is mapped as version attribute
Insertable	Specifies that the mapped columns should be included in any SQL INSERT statements.
Updatable	Specifies that the mapped columns should be included in any SQL UPDATE statements.
Fetch	Specify if attribute should be fetched lazily.
Generate finder	Generates a finder function for the attribute.

The Basic annotation is generated to specify fetch mode for the attribute or property and whether the attribute or property is mandatory. The Column annotation is generated to specify a mapped column for a persistent property or field.

@Basic
@Column(name="DESC", nullable=false, length=512)
public String getDescription() { return description; }

Other Annotations can also be generated to specify the persistence type of an attribute or property. A Temporal annotation specifies that a persistent property or attribute should be persisted as a temporal type. There is also the enumerated annotation for enumerated types and Lob for large object types.

Defining Versioning Mapping

EJB 3.0 uses managed versioning to perform optimistic locking. If you want to use this kind of feature, you need to set one mapped persistent attribute as the Version attribute, by selecting the Version attribute option on the EJB 3 Persistence tab. The following types are supported for Version attribute: int, Integer, short, Short, long, Long, Timestamp.

The Version attribute should be mapped to the primary table for the entity class. Applications that map the Version property to a table other than the primary table will not be portable. Only one Version attribute should be defined for each Entity class.

The Version annotation is generated to specify the version attribute or property of an entity class that serves as its optimistic lock value.

@Version
@Column(name="OPTLOCK")
protected int getVersionNum() { return versionNum; }