6.3. Additional JPA Metadata

6.3.1. Datastore Identity
6.3.2. Surrogate Version
6.3.3. Persistent Field Values
6.3.4. Persistent Collection Fields
6.3.5. Persistent Map Fields

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.

6.3.1. Datastore Identity

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”

6.3.2. Surrogate Version

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.

6.3.3. Persistent Field Values

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.

6.3.4. Persistent Collection Fields

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.

6.3.5. Persistent Map Fields

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.

 

Skip navigation bar   Back to Top