The org.apache.openjpa.persistence.FetchGroups and org.apache.openjpa.persistence.FetchGroup annotations allow you to define fetch groups in your JPA entities. Section 7, “ Fetch Groups ” discusses OpenJPA's support for fetch groups in general; see Section 7.1, “ Custom Fetch Groups ” for how to use these annotations in particular.

Section 1, “ Data Cache ” examines caching in OpenJPA. Metadata extensions allow individual classes to override system caching defaults.

OpenJPA defines the org.apache.openjpa.persistence.DataCache annotation for caching information. This annotation has the following properties:

The OpenJPA enhancer may add a synthetic field to detachable classes to hold detached state (see Section 1.3, “ Defining the Detached Object Graph ” for details). You can instead declare your own detached state field or supress the creation of a detached state field altogether. In the latter case, your class must not use datastore identity, and should declare a version field to detect optimistic concurrency errors during detached modifications.

OpenJPA defines the org.apache.openjpa.persistence.DetachedState annotation for controlling detached state. When used to annotate a class, DetachedState recognizes the following properties:

If you declare your own detached state field, you can annotate that field with DetachedState directly, rather than placing the annotation at the class level and using the fieldName property. When placed on a field, DetachedState acts as a marker annotation; it does not recognize any properties. Your annotated field must be of type Object.

In a dependent relation, the referenced object is deleted whenever the owning object is deleted, or whenever the relation is severed by nulling or resetting the owning field. For example, if the Magazine.coverArticle field is marked dependent, then setting Magazine.coverArticle to a new Article instance will automatically delete the old Article stored in the field. Similarly, deleting a Magazine object will automatically delete its current cover Article. (This latter processing is analogous to using JPA's CascadeType.REMOVE functionality as described in Section 2.8.1, “ Cascade Type ”.) You can prevent an orphaned dependent object from being automatically deleted by assigning it to another relation in the same transaction.

OpenJPA offers a family of marker annotations to denote dependent relations in JPA entities:

The org.apache.openjpa.persistence.LoadFetchGroup annotation specifies a field's load fetch group. Section 7, “ Fetch Groups ” discusses OpenJPA's support for fetch groups in general; see Section 7.1, “ Custom Fetch Groups ” for how to use this annotation in particular.

This boolean extension, denoted by the OpenJPA org.apache.openjpa.persistence.LRS annotation, indicates that a field should use OpenJPA's special large result set collection or map proxies. A complete description of large result set proxies is available in Section 6.4.2, “ Large Result Set Proxies ”.

This extension names the inverse field in a logical bidirectional relation. To create a logical bidrectional relation in OpenJPA, use the org.apache.openjpa.persistence.InverseLogical annotation. We discuss logical bidirectional relations and this extension in detail in Section 5, “ Managed Inverses ”.

The read-only extension makes a field unwritable. The extension only applies to existing persistent objects; new object fields are always writeable.

To mark a field read-only in JPA metadata, set the org.apache.openjpa.persistence.ReadOnly annotation to an org.apache.openjpa.persistence.UpdateAction enum value. The UpdateAction enum includes:

OpenJPA has three levels of support for relations:

Clearly, when you declare a field's type to be another persistence-capable class, OpenJPA uses level 1 support. By default, OpenJPA assumes that any interface-typed fields you declare will be implemented only by other persistent classes, and assigns interfaces level 2 support. The exception to this rule is the java.io.Serializable interface. If you declare a field to be of type Serializable, OpenJPA lumps it together with java.lang.Object fields and other non-interface, unrecognized field types, which are all assigned level 3 support.

With OpenJPA's type family of metadata extensions, you can control the level of support given to your unknown/interface-typed fields. Setting the value of this extension to Entity indicates that the field value will always be some persistent object, and gives level 2 support. Setting the value of this extension to the class of a concrete persistent type is even better; it gives you level 1 support (just as if you had declared your field to be of that type in the first place). Setting this extension to Object uses level 3 support. This is useful when you have an interface relation that may not hold other persistent objects (recall that OpenJPA assumes interface fields will always hold persistent instances by default).

This extension is also used with OpenJPA's externalization feature, described in Section 6.5, “ Externalization ”.

OpenJPA defines the following type annotations for field values, collection, array, and map elements, and map keys, respectively:

The OpenJPA org.apache.openjpa.persistence.Externalizer annotation names a method to transform a field value into a value of another type. See Section 6.5, “ Externalization ” for details.

The OpenJPA org.apache.openjpa.persistence.Factory annotation names a method to re-create a field value from its externalized form. See Section 6.5, “ Externalization ” for details.

The OpenJPA org.apache.openjpa.persistence.ExternalValues annotation declares values for transformation of simple fields to different constant values in the datastore. See Section 6.5.1, “ External Values ” for details.