Managing JPA Entity Mappings

ORM Workbench 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.

The Entities Editor actions described in this topic include:

Opening the entities editor

Viewing entity properties

Editing property/field properties

Other property actions

Filtering the view of relationships

Creating new entities

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 Studio 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.

The property types described include:

Basic properties

One-to-many properties

Many-to-one properties

One-to-one properties

Many-to-many properties

Id properties

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.

Note: Keep in mind that when generating one-to-many and many-to-one properties, ORM Workshop creates and/or annotates multiple entity beans. For example, for the following one-to-many orders property in a Customer entity, a many-to-one customer property is generated in the Order entity. See Many-To-One Properties for an example of this property's counterpart.

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.

Note: Keep in mind that when generating one-to-many and many-to-one properties, ORM Workshop creates and/or annotates multiple entity beans. For example, for the following many-to-one customer property in an Orders entity, a one-to-many orders property is generated in the Customer entity. See One-To-Many Properties for an example of this property's counterpart.

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.

The Smart Editor displays values for the @JoinTable annotation attributes:

	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.

Generating JPA Mappings