Jump to: navigation, search

Difference between revisions of "EclipseLink/Examples/JPA/AttributeGroup"

(AttributeGroup Types and Operations)
Line 20: Line 20:
==== Full FetchGroup ====
==== Full FetchGroup ====
A FetchGroup when first created is assumed to be empty. The user must add the attributes to the FetchGroup. If a FetchGroup is required with all of the attributes then the [http://www.eclipse.org/eclipselink/api/2.1/org/eclipse/persistence/descriptors/FetchGroupManager.html#createFullFetchGroup%28%29 FetchGroupManager.createFullFetchGroup()] must be used.
==== Load/LoadAll with FetchGroup ====
==== Load/LoadAll with FetchGroup ====

Revision as of 08:41, 14 June 2010

Starting in the EclipseLink 2.1.0 release, EclipseLink has introduced the concept of an AttributeGroup that can be used configure the use of partial entities in fetch, load, copy, and merge operations. This example illustrates how this functionality can be used.

Fetch: Control which attributes and their associated columns are retrieved from the database
Load: Control which relationships in the entities returned from a query are populated
Copy: Control which attributes are copied into a new entity instance
Merge: Merge only those attributes fetched, loaded, or copied into an entity

AttributeGroup Types and Operations


The FetchGroup which has existed in EclipseLInk for a number of releases defines which attributes should be fetched (selected from the database) when the entity is retrieved as the result of a query execution. The inclusion of relationship attributes in a FetchGroup only determines if the attribute's required columns should be fetched and populated. In the case of a lazy fetch type the inclusion of the attribute simply means that its proxy will be created to enable lazy loading when accessed. To force a relationship mapping to be populated when using a FetchGroup on a query the attribute must be included in the group and must either be FetchType.EAGER or it must be included in an associated LoadGroup on the query.

Default FetchGroup

FetchGroup also has the notion of named and default FetchGroup which are managed by the FetchGroupManager. A default FetchGroup is defined during metadata processing if one or more basic mappings are configured to be lazy and the entity class implements FetchGroupTracker (typically introduced through weaving). The default FetchGroup is used on all queries for this entity type where no explicit FetchGroup or named FetchGroup is configured.

Named FetchGroup

A Named FetchGroup can be defined for an entity using [TODO @FetchGroup] or within the [[EclipseLink/Examples/JPA/EclipseLink-ORM.XML|eclipselink-orm.xml]

Full FetchGroup

A FetchGroup when first created is assumed to be empty. The user must add the attributes to the FetchGroup. If a FetchGroup is required with all of the attributes then the FetchGroupManager.createFullFetchGroup() must be used.

Load/LoadAll with FetchGroup

A FetchGroup can also be configured to perform a load operation of relationship mappings and nested relationship mappings.


A LoadGroup is used to force a specified set of relationship attributes to be populated in a query result.


The CopyGroup replaces the deprecated ObjectCopyPolicy being used to define how a entity is copied. In addition to specifying the attributes defining what should be copied from the source entity graph into the target copy the CopyGroup also allows definition of:

  • shouldResetPrimaryKey: Reset the identifier attributes to their default value. This is used when the copy operation is intended to clone the entity in order to make a new entity with similar state to the source. Default is false.
  • shouldRestVersion: Reset the optimistic version locking attribute to its default value in the copies. Default is false.
  • depth: defines cascade mode for handling relationships. By default CASCADE_PRIVATE_PARTS is used but it can also be configure to NO_CASCADE, CASCADE_ALL_PARTS, and CASCADE_TREE (which should be used if the attribute group's specified items are all that is to be copied).


When a partial entity is merged into a persistence context that has an AttributeGroup associated with it defining which attributes are available only those attributes are merged. The relationship mappings within the entity are still merged according to their cascade merge settings.

Usage Examples

FetchGroup Examples

Named FetchGroup

Configuring using @FetchGroup

@FetchGroup(name="names", attributes={

Configuring within eclipsleink-orm.xml

<entity class="model.Employee">
	<secondary-table name="SALARY" />
	<fetch-group name="names">
		<attribute name="firstName" />
		<attribute name="lastName" />

Copy Examples

Here an Employee entity is copied with it basic names, address and phoneNumbers.

CopyGroup group = new CopyGroup();
group.cascadeTree(); // Only copy the specified attribute group items
Employee empCopy = (Employee) em.unwrap(JpaEntityManager.class).copy(emp, group);

Clone Entity using Copy and Persist

In this example an employee entity is cloned using a CopyGroup to copy all attributes with the exception of relationships (1:1, 1:M, M:M) that are not configured as private-owned. The resulting copy of the entity is then persisted to have new identity but the same state as its source.

CopyGroup group = new CopyGroup();
group.cascadePrivateParts(); // Copy all attributes and only private-owned relationships
Employee empCopy = (Employee) em.unwrap(JpaEntityManager.class).copy(emp, group);
System.out.println(">>> Employee copied");
// Persist the employee copy