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

## 3. Additional JPA Metadata

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 4, “ Metadata Extensions ” covers additional extensions to JPA metadata that allow you to access auxiliary OpenJPA features.

### 3.1. Datastore Identity

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 ”

### 3.2. Surrogate Version

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.

### 3.3. Persistent Field Values

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.

### 3.4. Persistent Collection Fields

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.

### 3.5. Persistent Map Fields

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.

Prev | Up | Next
2. Metadata Repository | Home | 4. Metadata Extensions