6.3. Additional JPA Metadata
Prev | Chapter 6. Metadata | Next

## 6.3. Additional JPA Metadata

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 `kodo.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, `String`s, etc), custom types, and embedded objects.

The `kodo.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 `kodo.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, `String`s, etc), custom types, or embedded objects. Section 7.7.8, “Maps” contains several examples of using `PersistentMap` to annotate persistent map fields.

Prev | Up | Next
6.2. Metadata Factory | Home | 6.4. Metadata Extensions