This section describes OpenJPA's core additions to standard entity metadata. We present the object-relational mapping syntax to support these additions in Section 7, “ Additional JPA Mappings ”. Finally, Section 3, “ Metadata Extensions ” covers additional extensions to JPA metadata that allow you to access auxiliary OpenJPA features.
JPA typically requires you to declare one or more Id fields
to act as primary keys. OpenJPA, however, can create and maintain a surrogate
primary key value when you do not declare any Id fields. This
form of persistent identity is called datastore identity.
Section 4, “
Object Identity
” discusses OpenJPA's support for
datastore identity in JPA. We cover how to map your datastore identity primary
key column in Section 7.1, “
Datastore Identity Mapping
”
Just as OpenJPA can maintain your entity's identity without any Id
fields, OpenJPA can maintain your entity's optimistic version without
any Version fields.
Section 7.2, “
Surrogate Version Mapping
” shows you how to map
surrogate version columns.
JPA defines Basic, Lob, Embedded
, ManyToOne, and OneToOne
persistence strategies for direct field values. OpenJPA supports all of these
standard strategies, but adds one of its own: Persistent.
The
org.apache.openjpa.persistence.Persistent
metadata annotation can represent any direct field value, including custom
types. It has the following properties:
FetchType fetch: Whether to load the field eagerly or
lazily. Corresponds exactly to the same-named property of standard JPA
annotations such as Basic
. Defaults to FetchType.EAGER.
CascadeType[] cascade: Array of enum values defining cascade
behavior for this field. Corresponds exactly to the same-named property of
standard JPA annotations such as
ManyToOne. Defaults to empty array.
String mappedBy: Names the field in the related entity that
maps this bidirectional relation. Corresponds to the same-named property of
standard JPA annotations such as
OneToOne.
boolean optional: Whether the value can be null. Corresponds
to the same-named property of standard JPA annotations such as
ManyToOne
, but can apply to non-entity object values as well. Defaults to
true.
boolean embedded: Set this property to true
if the field value is stored as an embedded object.
Though you can use the Persistent annotation in place of
most of the standard direct field annotations mentioned above, we recommend
primarily using it for non-standard and custom types for which no standard JPA
annotation exists. For example, Section 7.3, “
Multi-Column Mappings
”
demonstrates the use of the Persistent annotation
to denote a persistent java.awt.Point field.
JPA standardizes support for collections of entities with the
OneToMany and ManyToMany persistence strategies.
OpenJPA supports these strategies, and may be extended for other strategies as
well. For extended strategies, use the
org.apache.openjpa.persistence.PersistentCollection metadata
annotation to represents any persistent collection field. It has the following
properties:
Class elementType: The class of the collection elements.
This information is usually taken from the parameterized collection element
type. You must supply it explicitly, however, if your field isn't a
parameterized type.
FetchType fetch: Whether to load the collection eagerly or
lazily. Corresponds exactly to the same-named property of standard JPA
annotations such as
Basic. Defaults to FetchType.LAZY.
String mappedBy: Names the field in the related entity that
maps this bidirectional relation. Corresponds to the same-named property of
standard JPA annotations such as
ManyToMany.
CascadeType[] elementCascade: Array of enum values defining
cascade behavior for the collection elements. Corresponds exactly to the
cascade property of standard JPA annotations such as
ManyToMany. Defaults to empty array.
boolean elementEmbedded: Set this property to true
if the elements are stored as embedded objects.
JPA has limited support for maps. If you extend JPA's standard map support to
encompass new mappings, use the
org.apache.openjpa.persistence.PersistentMap metadata
annotation to represent your custom persistent map fields. It has the
following properties:
Class keyType: The class of the map keys. This information
is usually taken from the parameterized map key type. You must supply it
explicitly, however, if your field isn't a parameterized type.
Class elementType: The class of the map values. This
information is usually taken from the parameterized map value type. You must
supply it explicitly, however, if your field isn't a parameterized type.
FetchType fetch: Whether to load the collection eagerly or
lazily. Corresponds exactly to the same-named property of standard JPA
annotations such as
Basic. Defaults to FetchType.LAZY.
CascadeType[] keyCascade: Array of enum values defining
cascade behavior for the map keys. Corresponds exactly to the cascade
property of standard JPA annotations such as
ManyToOne. Defaults to empty array.
CascadeType[] elementCascade: Array of enum values defining
cascade behavior for the map values. Corresponds exactly to the
cascade property of standard JPA annotations such as
ManyToOne. Defaults to empty array.
boolean keyEmbedded: Set this property to true
if the map keys are stored as embedded objects.
boolean elementEmbedded: Set this property to
true if the map values are stored as embedded objects.