Managing JPA Entity Mappings

Workshop provides graphical interfaces for editing EJB3 entities and for editing the persistence.xml file that describes the persistence context.

As described here, the Entities Editor is a graphical view of your entities. Using the Entities Editor, you can view relationships between entities, edit their relationship with the database, get easy access to the entity bean source code, and create additional mappings.

You can edit the persistence.xml file using a graphical interface that provides easy access to the file's structure and value. See Configuring JPA Properties for a description of the editing features.

Opening the Entities Editor

You can use the Entities Editor to edit properties of both entity beans and their fields. Open the Entities Editor by double-clicking Entities Editor in AppXplorer.

Viewing Entity Properties

You can click an entity's name (here, "Customer") to select the entity in the editor. When you select an entity its properties are displayed in the Smart Editor. Here you can change entity properties, such as which database table the entity interacts with. By right-clicking the entity, you can view its source code or delete the entity. You can open entity or field source code also by double-clicking the entity or field in the Entities Editor.

Editing Property/Field Properties

You can click a property or field's name to select the field in the Entities Editor. Note that the property or field's properties are displayed in the Smart Editor. These properties will differ depending on the type of property you've selected.

When you create entity mappings, you define each property as having one of six property types: basic, id, many-to-one, one-to-one, one-to-many, and many-to-many. When you generate entities from a database, Workshop annotates the generated source code with EJB 3.0 annotations that designate which type a given property is. What's displayed in the Smart Editor is a view on the annotations specified in entity beans code.

The following briefly describes how the annotations are translated into what the Smart Editor displays. Note that where the Smart Editor displays an underlined label, you can click the label to view the corresponding Java source code or item in the DbXplorer.

Basic Properties

A basic property handles a standard value that is persisted as-is to the database. As a result, its properties are pretty straightforward. In addition to specifying the property's name and type, the Smart Editor displays the following for the @Column annotation that accompanies the @Basic annotation:

Value Name	Description
Column Name	The name of the column to which the property is bound.
Unique	true to specify that the column is UNIQUE in the SQL sense (can have only unique values).
Nullable	`true` to specify that the column can store null values.
Length	The column length.
Insertable	`false` to omit the column from SQL INSERT statements.
Updatable	`false` to omit the column from SQL UPDATE statements.

Note that values that haven't been explicitly set are left at their defaults. Default values needn't appear in source code; in the Smart Editor, defaults are grey. When you set the value explicitly, the value is written as an attribute value to the annotation in source code.

Java Source Example

Entities Editor and Smart Editor Example

One-to-Many Properties

A one-to-many property designates a relationship in which one A entity references multiple B entities, and no two A entities reference the same B entity. In the example below, a Customer entity references multiple Order entities, but an Order entity can have only one Customer entity reference. In addition to specifying the property's name and type, the Smart Editor displays the following corresponding to attributes of the @OneToMany annotation:

Value Name	Description
Cascade	An array of enum values specifying cascade behavior for entities represented by this property.
Fetch Type	A enum specifying whether to load the field's persisted data before the entity object is returned by the persistence provider (`FetchType.EAGER`) or later, when the property is accessed (`FetchType.LAZY`).
Mapped By	Names the many-to-one field in the related entity that maps this bidirectional relation.
Target Entity	The class of the related entity type.

The Smart Editor's Order By property exposes an @OrderBy annotation that designates the column value by which entities are sorted.

Java Source Example

Entities Editor and Smart Editor Example

Many-to-One Properties

A many-to-one property designates a relationship in which an entity A references a single entity B, and other As might also reference the same B; there is a many-to-one relation from A to B. In addition to specifying the property's name and type, the Smart Editor displays the following corresponding to attributes of the @ManyToOne annotation:

Value Name	Description
Cascade	An array of enum values specifying cascade behavior for entities represented by this property.
Fetch Type	A enum specifying whether to load the field's persisted data before the entity object is returned by the persistence provider (`FetchType.EAGER`) or later, when the property is accessed (`FetchType.LAZY`).

The following properties in the Smart Editor correspond to attributes of the @JoinColumn annotation:

Value Name	Description
Column Name	The name of the column to which the property is bound.
Unique	`true` to specify that the column is UNIQUE in the SQL sense (can have only unique values).
Nullable	`true` to specify that the column can store null values.
Insertable	`false` to omit the column from SQL INSERT statements.
Updatable	`false` to omit the column from SQL UPDATE statements
Referenced Column	The name of the primary key column being joined to.

Java Source Example

Entities Editor and Smart Editor Example

One-to-One Properties

A one-to-one property designates a relationship in which an entity A references a single entity B, and no other As can reference the same B; this is a one-to-one relation between A and B.

Note that most of the properties available in the Smart Editor are the same as those for the Many-to-One type. You'll find the Mapped By property described for the One-to-Many type.

Java Source Example

Entities Editor and Smart Editor Example

Many-to-Many Properties

A many-to-many property designates a relationship in which an entity A references multiple B entities, and other As might reference some of the same B entities; there is a many-to-many relation between A and B. In addition to specifying the property's name and type, the Smart Editor displays the following corresponding to attributes of the @ManyToMany annotation:

Value Name	Description
Cascade	An array of enum values specifying cascade behavior for entities represented by this property.
Fetch Type	A enum specifying whether to load the field's persisted data before the entity object is returned by the persistence provider (`FetchType.EAGER`) or later, when the property is accessed (`FetchType.LAZY`).
Target Entity	The class of the related entity type.
Mapped By	Names the many to many field in the related entity that maps this bidirectional relation.

The Smart Editor's Order By property exposes an @OrderBy annotation that designates the column value by which entities are sorted.

Value Name	Description
Join Table	The database table for the entity.
Join	An array of joined columns (representing the `@JoinColumns` annotation) showing how to associate join table records with the owning row in the primary table.
Join (for inverse join)	An array of joined columns (representing the `@JoinColumns` annotation) showing how to associate join table records with the records that form the elements of the collection.

Java Source Example

Entities Editor and Smart Editor Example

Id Properties

An Id property designates an identifier, such as a primary key. All entity beans must declare one or more fields which together form the persistent identity of an instance. In addition to specifying the property's name and type, the Smart Editor displays the following corresponding to attributes of the @Id annotation:

Value Name

Description

Generate

An enum value specifying how to auto-generate the identity field value. Auto-generated values are only available for numeric fields. The values for this property are defined by the GeneratorType enum, which has the following constants:

NONE: Do not generate an automatic value for the field. This is the default.
AUTO: Assign the field a generated value, leaving the details to the EJB persistence vendor.
IDENTITY: The database will assign an identity value on insert.
SEQUENCE: Use a datastore sequence to generate a field value.
TABLE: Use a sequence table to generate a field value.

The Smart Editor also displays the following corresponding to attributes of the @Column annotation.

Value Name	Description
Column Name	The name of the column to which the property is bound.
Nullable	`true` to specify that the column can store null values.
Length	The column length.

Java Source Example

Entities Editor and Smart Editor Example

Other Property Actions

In addition to editing property values, you can also click Property Name to view the entity source code, Property Type to view information about that type, and Column Name to view a database diagram of the database column. By right-clicking the field, you can open its source code, unmap it, or delete the entity itself.

Filtering the View of Relationships

You can select a filter from the Filters dropdown to reduce the number of the relationship lines displayed in the Entities Editor. This can be useful when you have a complex set of relationships between many entities.

Creating New Entities

By clicking the icons at the upper right of the Entities Editor, you can create new entity mappings. Clicking these icons will launch the wizards that generate entity mappings. For more information on using these wizards, see Creating JPA Mappings from a Schema and Annotating Existing Java Classes.