This section describes Kodo's core additions to standard entity metadata. We present the object-relational mapping syntax to support these additions in Section 7.7, “Additional JPA Mappings”. Finally, Section 6.4, “Metadata Extensions” covers additional extensions to both JDO and JPA metadata that allow you to access auxiliary Kodo features.
JPA typically requires you to declare one or more
Id fields to act as primary keys. Kodo, 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 5.3, “Object Identity” discusses
Kodo's support for datastore identity in JPA. We
cover how to map your datastore identity primary key column in
Section 7.7.1, “Datastore Identity Mapping”
Just as Kodo can maintain your entity's identity without any
Id fields, Kodo can maintain your entity's
optimistic version without any Version fields.
Section 7.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. Kodo 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.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. Kodo expands collection support to handle
collections of simple types (primitive wrappers,
Strings, etc), custom types, and embedded
objects.
The
org.apache.openjpa.persistence.PersistentCollection
metadata annotation represents a 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.
Section 7.7.6, “Collections” contains several
examples of using PersistentCollection to
mark non-standard collection fields persistent.
JPA has limited support for maps. Kodo introduces the
org.apache.openjpa.persistence.PersistentMap
metadata annotation to represent a persistent map field.
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.
Map keys and values in Kodo can be entities, simple types
(primitive wrappers, Strings, etc),
custom types, or embedded objects.
Section 7.7.8, “Maps” contains several
examples of using PersistentMap to annotate
persistent map fields.