Loading
Understanding EclipseLink, 2.4
  Go To Table Of Contents
Contents
 Search
Other Searches
 PDF
PDF
Comments
Comments

About JPA Mapping Types

To map entity classes to relational tables you must configure a mapping per persistent field. The following sections describe EclipeLink's JPA mapping types:

Basic Mappings

Simple Java types are mapped as part of the immediate state of an entity in its fields or properties. Mappings of simple Java types are called basic mappings.

By default, the EclipseLink persistence provider automatically configures a basic mapping for simple types.

Use the following annotations to fine-tune how your application implements these mappings:

  • @Basic

  • @Enumerated

  • @Temporal

  • @Lob

  • @Transient

  • @Column

  • Lazy Basics (See Using Lazy Loading)

For all mapping types there are a common set of options:

  • Read-Only: Specifies that the mapping should populate the value on read and copy. Required when multiple mappings share the same database column.

  • Converters: Allows custom data types and data conversions to be used with most mapping types

    • Annotations: @Converter, @TypeConverter, @ObjectTypeConverter, @StructConverter, @Convert

    • External Metadata: <converter>, <type-converter>, <object-type-converter>, <struct-converter>, <convert>

For more information on these annotations, see Java Persistence API (JPA) Extensions Reference for EclipseLink.

Default Conversions and Converters

EclipseLink defines the following converter annotations (in addition to JPA-defined annotations):

  • @Converter

  • @TypeConverter

  • @ObjectTypeConverter

  • @StructConverter

  • @Convert

The EclipseLink persistence provider searches the converter annotations in the following order:

  • @Convert

  • @Enumerated

  • @Lob

  • @Temporal

  • Serialized (automatic)

You can define converters at the class, field and property level. You can specify EclipseLink converters on the following types of classes:

  • @Entity

  • @MappedSuperclass

  • @Embeddable

You can use EclipseLink converters with the following mappings:

  • @Basic

  • @Id

  • @Version

  • @BasicMap

  • @BasicCollection

If you specify a converter with any other type of mapping annotation, EclipseLink will throw an exception.

For more information on these annotations, see Java Persistence API (JPA) Extensions Reference for EclipseLink.

Collection Mappings

You can access additional advanced mappings and mapping options through the EclipseLink descriptor and mapping API using a DescriptorCustomizer class.

One-to-Many Mapping

One-to-many mappings are used to represent the relationship between a single source object and a collection of target objects. They are a good example of something that is simple to implement in Java using a Collection (or other collection types) of target objects, but difficult to implement using relational databases.

In a Java Collection, the owner references its parts. In a relational database, the parts reference their owner. Relational databases use this implementation to make querying more efficient.

Figure 7-13 One-to-Many Relationships

This figure illustrates the one-to-many relationship.
Description of "Figure 7-13 One-to-Many Relationships"


NoteNote:

The phone attribute shown in the One-to-Many Relationships is of type Vector. You can use a Collection interface (or any class that implements the Collection interface) for declaring the collection attribute.


JPA Mapping

By default, JPA automatically defines a OneToMany mapping for a many-valued association with one-to-many multiplicity.

Use the @OneToMany annotation to do the following:

  • configure the fetch type to EAGER

  • configure the associated target entity, because the Collection used is not defined using generics

  • configure the operations that must be cascaded to the target of the association: for example, if the owning entity is removed, ensure that the target of the association is also removed

  • configure the details of the join table used by the persistence provider for unidirectional one-to-many relationships. For a one-to-many using a mappedBy or JoinColumn, the deletion of the related objects is cascaded on the database. For a one-to-many using a JoinTable, the deletion of the join table is cascaded on the database (target objects cannot be cascaded even if private because of constraint direction).

For more information, see Section 11.1.23 "JoinTable Annotation" in the JPA Specification.

http://jcp.org/en/jsr/detail?id=317

Many-to-Many Mapping

Many-to-many mappings represent the relationships between a collection of source objects and a collection of target objects. They require the creation of an intermediate table for managing the associations between the source and target records.

Figure 7-14 illustrates a many-to-many mapping in Java and in relational database tables.

Figure 7-14 Many-to-many Relationships

Many-to-many Relationships
Description of "Figure 7-14 Many-to-many Relationships"


NoteNote:

For the projects attribute shown in the Many-to-many Relationships you can use a Collection interface (or any class that implements the Collection interface) for declaring the collection attribute.


JPA Mapping

By default, JPA automatically defines a ManyToMany mapping for a many-valued association with many-to-many multiplicity.

Use the @ManyToMany annotation to do the following:

  • configure the Fetch Type to EAGER;

  • configure the mapping to forbid null values (for nonprimitive types) in case null values are inappropriate for your application;

  • configure the associated target entity because the Collection used is not defined using generics;

  • configure the operations that must be cascaded to the target of the association (for example, if the owning entity is removed, ensure that the target of the association is also removed).

For a list of supported attributes for the @ManyToMany annotation, see the Java Persistence specification:

http://jcp.org/en/jsr/detail?id=317

Using Optimistic Locking

Oracle recommends using optimistic locking. With optimistic locking, all users have read access to the data. When a user attempts to write a change, the application checks to ensure the data has not changed since the user read the data.

Optimistic Locking in a Stateless Environment

In a stateless environment, take care to avoid processing out-of-date (stale) data. A common strategy for avoiding stale data is to implement optimistic locking, and store the optimistic lock values in the object. This solution requires careful implementation if the stateless application serializes the objects, or sends the contents of the object to the client in an alternative format. In this case, transport the optimistic lock values to the client in the HTTP contents of an edit page. You must then use the returned values in any write transaction to ensure that the data did not change while the client was performing its work.

You can use optimistic version locking or optimistic field locking policies. We recommend using version locking policies.

Optimistic Version Locking

Use the @Version annotation to enable the JPA-managed optimistic locking by specifying the version field or property of an entity class that serves as its optimistic lock value (recommended).

When choosing a version field or property, ensure that the following is true:

  • there is only one version field or property per entity;

  • you choose a property or field persisted to the primary table;

  • your application does not modify the version property or field.

For more information, see Section 11.1.45 "Table Annotation" in the JPA Specification.

http://jcp.org/en/jsr/detail?id=317


NoteNote:

The field or property type must either be a numeric type (such as Number, long, int, BigDecimal, and so on), or a java.sql.Timestamp. EclipseLink recommends using a numeric type.


The @Version annotation does not have attributes. The @Version annotation supports the use of EclipseLink converters. See Default Conversions and Converters.

For more information, see Section 11.1.9 "Column Annotation" in the JPA Specification.

http://jcp.org/en/jsr/detail?id=317

Comments powered by Disqus