4.3.3 Creating Entity Classes

To create an entity class, a class with an @Entity annotation, etc. set can be generated using the New JPA Entity wizard.

Point

An Entity class can also be generated from a database table.
For details, refer to "4.3.3.4 Generating Entity Classes from Tables" for details.

Opening the JPA Perspective

First open the JPA perspective.

Creating Entity Classes

Create entity classes using the [New] wizard, by selecting [JPA] > [Entity]. For the wizard settings, see below.

Project
Specify the project that generates the entity class.
Source folder
Specify the folder that stores the entity class source.
Java package
Specify the package name of the entity class.
Class name
Specify the name of the entity class.
Inheritance
Select the class that is inherited by the entity class from "Entity" or "Mapped Superclass".
XML Entity Mappings
If adding an entity to an O/R mapping file, select "Add to entity mappings in XML".
Entity Name
Specify the entity name.
Table Name
If associating with an existing table, deselect "Use default" and specify the table name.
Entity Fields
Add an entity field. Specify and add the field name and type. For the field to be made the primary key, select "Key".
Access Type
Specify the access type of the entity as "Field-based" or "Property-based".

Setting the Annotation

Activate the [JPA Structure] view and select the created Java class. In the [JPA Details] view, click the mapping type displayed in [Type]. In the [Mapping Type Selection] dialog box, when the mapping type is selected, the annotation is set in the entity class.
An Entity suited to complicated data structures can also be created using inheritance, embedding, and so on.
For details, refer to "4.3.3.1 Creating an Entity taking Data Structures into Account" for details.

Point

Java classes set as entity are not displayed in the JPA Structure view. Therefore, add the annotation definitions to the Java Source directly.

Entity Class and Database Mapping

To perform Entity class and database mapping, specify the database table name in the [Name] combo box under the [Table] group in the [JPA Details] view. The default can be used when mapping if the table has the same name as the class name.

Mapping can be performed for the Entity class fields and the database columns. Create fields in the Entity class, then select the fields in the [JPA Structure] view. Specify the database table name in the [Name] combo box under the [Column] group in the [JPA Details] view. The defaults can be used when mapping if the columns have the same names as the field names.

Point

When connected to the database that is set in the project, the [JPA Details] view combo box lists the mapping possibilities.

Database mapping can also be performed for things other than setting simple table or column associations.
For details, refer to "4.3.3.2 Mapping the Entity and Database" for details of database mapping.
In addition, relationships between Entities can be mapped by combining them with database information.
For details, refer to "4.3.3.3 Defining Relationships between Entities" for details.

Point

Database mapping can also be performed using an O/R mapping file, not just by using annotation. Use an O/R mapping file to improve application portability if you want to use it in multiple environments, for example.

4.3.3.1 Creating an Entity taking Data Structures into Account

An Entity can be created by inheriting an Entity. In addition to an Entity, common persistence items can also be managed in a superclass, and these also can be created by inheritance. To create this superclass, set the @MappedSuperclass annotation.
If an Entity has been inherited and created, the attributes of the inherited persistent items can be changed by overwriting, and the mapping method can be specified for the database tables of each of the inherited Entities. Use the @AttributeOverride annotation and the @Inheritance annotation for these purposes.

In addition, relevant persistence items can be grouped together and managed as a special class, and the special class can be embedded in the Entity by using it as the Entity field type. To create this special class, set the @Embeddable annotation and, if you want to embed this in the Entity, set either the @Embedded annotation or the @EmbeddedId annotation in the Entity field.
If embedding is performed, the attributes of the persistence items in the embedded class can be changed by overwriting.

Setting MappedSuperclass Annotation

Select the superclass in the [JPA Structure] view. In the [JPA Details] view, click the mapping type displayed in [Type]. In the [Mapping Type Selection] dialog box, when "Mapped Superclass" is selected, the @MappedSuperclass annotation is set.

If using a Java Class, open the class file in a Java editor and define the annotations directly.

Setting AttributeOverride Annotation

Select the Entity class in the [JPA Structure] view. At [Attribute Overrides] in the [JPA Details] view, select the persistence item that you want to overwrite and overwrite the attribute.

Setting Inheritance Annotation

Select the hierarchy root Entity class in the [JPA Structure] view. For [Inheritance] in the [JPA Details] view, specify the method of mapping to the Entity database table.
For details, refer to below for the settings:

Strategy
Select from the following table mapping methods:
- Single Table
  All Entities that have an inheritance relationship are mapped in a single table. For this method, the table requires a column (discriminator column) for the purpose of indicating which data of the Entity class that has an inheritance relationship is in each row of the database table.
- JOINED
  Each Entity class unit is mapped to a table. For each table, the column that corresponds to the persistence items (not including inherited persistence items) specific to that Entity class, and the join column, are defined. The purpose of the join column is to set the association with the primary key of the table (the primary table) corresponding to the hierarchy root Entity.
- Table per Class
  Each Entity class unit is mapped to a table. The column corresponding to the persistence items (including inherited persistence items) specific to that Entity class is defined.
Discriminator Column, Discriminator Type, and Discriminator Value
Specify these items if "Single Table" is selected as the method. The discriminator value sets the value used to identify the Entity classes that have an inheritance relationship.
These items are equivalent to the @DiscriminatorColumn and the @DiscriminatorValue annotations.
Primary Key Join Columns
Specify this item if "JOINED" is selected as the method. Specify the pair of columns referenced from the primary key column of the current Entity and the primary key column of the primary table.
This item is equivalent to the @PrimaryKeyJoinColumn annotation.

Setting Embeddable Annotation

Select the Java class in the [JPA Structure] view. In the [JPA Details] view, click the mapping type displayed in [Type]. In the [Mapping Type Selection] dialog box, when "Embeddable" is selected, the @Embeddable annotation is set.

If using a Java Class, open the class file in a Java editor and define the annotations directly.

Setting Embedded or EmbeddedId Annotation

In the [JPA Structure] view, select the persistence items of the class type for which Entity class @Embeddable annotation has been set. In the [JPA Details] view, click the mapping type displayed in [Attribute]. In the [Mapping Type Selection] dialog box, when "Embedded" or "Embedded Id" is selected, the @Embedded annotation or @EmbeddedId annotation is set in the persistence item.
If "Embedded" is selected, the attributes of the class for which the @Embeddable annotation was set can be changed by overwriting using [Attribute Overrides] in the [JPA Details] view.

4.3.3.2 Mapping the Entity and Database

Use the @Table annotation to perform mapping between the Entity and the database table. In addition, an Entity can be mapped to multiple databases by using the @SecondaryTable annotation.

When an Entity and a table are mapped, names are used to set the associations between the persistence items and the columns. However, database columns can also be mapped to persistence item units. The persistence item to be used as the primary key must be declared.

In addition to specifying information for mapped columns, users can also specify the data read (fetch) method, type-related options, non-persistence items, and items used for Optimistic Locking.

Setting Table Annotation

In the [JPA Structure] view, select the Entity class. Under [Table] in the [JPA Details] view, specify the table name, catalog, and schema.

Setting SecondaryTable Annotation

In the [JPA Structure] view, select the Entity class. Under [Secondary Tables] in the [JPA Details] view, add tables other than the primary table (the table specified by the @Table annotation).

For [Primary Key Join Columns], specify which column of the table added as a secondary table is associated with the primary key of the primary table.

Mapping Persistence Items and Columns

In the [JPA Structure] view, select the Entity class persistence item. At [Column] in the [JPA Details] view, specify the column name and table.
The [Insertable] and [Updatable] items specify whether the column corresponding to that persistence item is an insert target or an update target.

Setting the Primary Key

In the [JPA Structure] view, select the persistence item to be used as the primary key of the Entity class. In the [JPA Details] view, select "Id" in the mapping type displayed in [Attribute]. The @Id annotation is set in the field.

If you want the primary key value to be generated automatically rather than being explicitly set within the program, select [Primary Key Generation] in the above [JPA Details] view. For details, refer to below for the settings.

This item corresponds to the @GeneratedValue, @TableGenerator, and @SequenceGenerator annotations.

Strategy
Select one of the following primary key generation methods:
- Auto
  The execution environment selects the generation method that is appropriate for the database.
- Identity
  The database IDENTITY column is used.
- Sequence
  The database sequence is used.
- Table
  The database table is used.
Generator Name
Specify the name specified for the table generator or sequence generator.
Table Generator
The name is the name specified for the generator name. A value column is a column that stores values generated by the generator. The value of the primary key column specifies the value used to identify which generator generated the table when this table is used to generate the primary keys of multiple tables. (This value and the last generated primary key value are stored as a pair in the primary key column and the value column.)
Sequence Generator
The name is the name specified for the generator name. For the sequence, specify the database sequence name.

Specifying Fetch Method

While the persistence item is in the selected state at the [JPA Structure] view, specify [Fetch] in the [JPA Details] view to specify the fetch method.
For details, refer to below for details:

EAGER
Specify Eager if the item must be fetched when the Entity is fetched.
LAZY
Specify Lazy if it is okay for the item to be fetched the first time the persistence item is accessed.

Specifying Date and Time Options

For time-related type persistence items, users can specify whether the association is with Date, Time, or the Timestamp. Use the @Temporal to specify which is associated.

To set the @Temporal annotation, select the time-related type persistence value in the [JPA Structure] view, then select the association method in the [Temporal] combo box of the [JPA Details] view.

Specifying Enumeration-related Options

For enumeration persistence items, users can specify whether the value is handled as an Ordinal or a String. Use the @Enumerated annotation to specify how it is handled.

To set the @Enumerated annotation, select the handling method in the [Enumerated] combo box of the [JPA Details] view.

Specifying Large Object Options

If the persistence item type is the type associated with the database large object type (LOB), users can specify whether the item is handled as a large object using the @Lob annotation.

To set the @Lob annotation, select the persistence item associated with the large object type in the [JPA Structure] view, then select [Lob] in the [JPA Details] view.

Specifying Non-persistence Items

The fields and properties declared in an Entity class are handled as persistence items by default. For non-persistence items, the @Transient annotation must be set.

To set the @Transient annotation, in the [JPA Structure] view, select the items not for persistence, and in the [JPA Details] view, for the mapping type displayed in [Attribute], select "Transient".

Specifying Items that Apply Optimistic Locking

The exclusion method used to check that a value has not changed when data is read and when values are updated is known as Optimistic Locking. The @Version annotation must be set for items that apply this format.

To set the @Version annotation, in the [JPA Structure] view, select the item, and in the [JPA Details] view, for the mapping type displayed in [Attribute], select "Version".

4.3.3.3 Defining Relationships between Entities

The relationship between Entities can be either one-to-one, many-to-one, one-to-many, or many-to-many. The relationships have directionality, and can be either bidirectional enabling referencing from either direction, or unidirectional allowing referencing from only one side.
To define the relationship between Entities, the Entity type of the side that is referenced, its collection type field, and its properties are defined in the Entity, and the relationship type is set using either the @OneToOne, the @ManyToOne, the @OneToMany, or the @ManyToMany annotation.

Defining a One-to-one or a Many-to-one Relationship

To the referencing side Entity, add the Entity type field or property of the referenced side Entity. Select the items added in the [JPA Structure] view, and in the [JPA Details] view, for the mapping type displayed in [Attribute], select "One to One" or "Many to One", then define the relationship. For details, refer to below for the relationship definitions:

Target Entity
Specification is not required because the target can be discerned from the field or property type.
Fetch
Select one of the following as the timing for fetching the reference destination Entity:
- EAGER
  Specifies that fetch is essential when the Entity is fetched.
- LAZY
  Specifies that it is okay to fetch at the time of first access.
Mapped By
If the relationship is bidirectional, specify the owning side persistence item in the owned side definitions.
In a one-to-one relationship, the side that has the external key is the owning side.
In a many-to-one relationship, the multi side is the owning side, so this definition cannot be specified.
Cascade
Select the persistence processing (method) that cascades to the reference destination. When making the selection, take into account, for example, when an Entity itself is deleted, whether or not the deletion is performed as far as the reference destination.
Join Columns
For one-to-one and many-to-one relationships, an external key is used to define the relationship. Therefore, specify the external key column name and the reference destination column name that it references, or similar, as the join column.
This item is equivalent to the @JoinColumn annotation.

Defining a One-to-many or a Many-to-many Relationship

To the referencing side Entity, add the Entity collection type field or property of the referenced side Entity. Select the items added in the [JPA Structure] view, and in the [JPA Details] view, for the mapping type displayed in [Attribute], select "One to Many" or "Many to Many", then define the relationship.
For details, refer to below for the relationship definitions. (The definitions that are the same as for one-to-one or many-to-one are omitted.)

Target Entity
If the collection type is declared and a generic name is used, specification is not required because the target can be discerned from the field or property type. If a generic name is not used, specify the reference destination Entity type.
Mapped By
If the relationship is one-to-many, the many side is the owning side. Therefore, specify this definition if the directionality is bidirectional.
For a bidirectional many-to-many relationship, decide which is the owning side and specify this definition at the owned side.
Cascade
In the reference destination entity, select the persistence process (method) to be cascaded. For example, select with consideration to whether deletion is to be extended to the reference destination if the entity itself is deleted.
Order By
Specify the reference destination Entity sequence to use when fetch is performed.
This item is equivalent to the @OrderBy annotation.
Join Table
For one-to-many and many-to-many relationships, the join table is used to define the relationship. The join table must have corresponding columns at the owning side and the owned side. Specify the table columns corresponding to the Entity referenced from these column names and columns.
This item is equivalent to the @JoinTable annotation.