Java Persistence/Embeddables

=Embeddables=

In an application object model some objects are considered independent, and others are considered dependent parts of other objects. In UML a relationship to a dependent object is considered an aggregate or composite association. In a relational database this kind of relationship could be modeled in two ways, the dependent object could have its own table, or its data could be embedded in the independent object's table. Which is another word to say the dependent data is included in the independent object's table.

In JPA a relationship where the target object's data is embedded in the source object's table is considered an embedded relationship, and the target object is considered an Embeddable object. Embeddable objects have different requirements and restrictions than Entity objects and are defined by the  annotation or   element.

An embeddable object cannot be directly persisted, or queried, it can only be persisted or queried in the context of the source object in which it is embedded. An embeddable object does not have an id or table. The JPA spec does not support embeddable objects having inheritance, although some JPA providers may allow this. Relationships from embeddable objects are supported in JPA 2.0.

Relationships to embeddable objects are defined through the  annotation or   element. The JPA 2.0 spec also supports collection relationships to embeddable objects.

Example of an embedded relationship XML
=Advanced=

Embedding more than one Instance of the same embeddable Type
Instances of an embeddable object can be embedded in the same parent entity more than once. However, without additional measures this creates a naming conflict, because it would require to have two or more columns with the same name in a table, which is not possible. The columns of all (except one of) the embedded instances of the same type need to be renamed to ensure unique column names. This renaming is done through the @AttributeOverride annotation, the  element, the @AssociationOverride annotation, or the   element.


 * @AttributeOverride is used to rename a basic mapping.
 * @AssociationOverride is used to rename the mapping for an entity relationship.
 * For example, @AssociationOverride is needed for an attribute in the embeddable class which is a @ManyToOne relation or a @OneToOne relation. I.e. when the embeddable class holds a foreign key.

@AttributeOverride and @AssociationOverride annotations are grouped together with @AttributeOverride s and @AssociationOverride s annotations respectively (note the plurals).

Sharing
An embeddable object can be shared between multiple classes. Consider a  object, that both an   and a   contain. Both  and a   have their own tables, with different column names that they desire to store their name in. Embeddables support this through allowing each embedded mapping to override the columns used in the embeddable. This is done through the @AttributeOverride annotation or  element.

Note that an embeddable cannot be shared between multiple instances. If you desire to share an embeddable object instance, then you must make it an independent object with its own table.

Embedded Ids
An  is an embeddable object that contains the   for an entity.

See: Embedded Id

Nulls
An embeddable object's data is contained in several columns in its parent's table. Since there is no single field value, there is no way to know if a parent's reference to the embeddable is. One could assume that if every field value of the embeddable is, then the reference should be  , but then there is no way to represent an embeddable with all   values. JPA does not allow embeddables to be, but some JPA providers may support this.


 * TopLink / EclipseLink : Support an embedded reference being .  This is set through using a   and the     API.


 * Hibernate : When loading an entity, embedded references are set to  if all of the columns in the embeddable are null.

Nesting
A nested embeddable is a relationship to an embeddable object from another embeddable. The JPA 1.0 spec only allows  relationships in an embeddable object, so nested embeddables are not supported, however some JPA products may support them. Technically there is nothing preventing the  annotation being used in an embeddable object, so this may just work depending on your JPA provider (cross your fingers).

JPA 2.0 supports nested embeddable objects.


 * TopLink / EclipseLink : Support embedded mappings from embeddables. The existing   annotation or   element can be used.

A workaround to having a nested embeddable, and for embeddables in general is to use property access, and add get/set methods for all of the attributes of the nested embeddable object.

Inheritance
Embeddable inheritance is when one embeddable class subclasses another embeddable class. The JPA spec does not allow inheritance in embeddable objects, however some JPA products may support this. Technically there is nothing preventing the  annotation being used in an embeddable object, so this may just work depending on your JPA provider (cross your fingers). Inheritance in embeddables is always single table as an embeddable must live within its' parent's table. Generally attempting to mix inheritance between embeddables and entities is not a good idea, but may work in some cases.


 * TopLink / EclipseLink : Support inheritance with embeddables. This is set through using a   and the.

Relationships
A relationship is when an embeddable has a  or other such mapping to an entity. The JPA 1.0 spec only allows  mappings in an embeddable object, so relationships from embeddables are not supported, however some JPA products may support them. Technically there is nothing preventing the  annotation or other relationships from being used in an embeddable object, so this may just work depending on your JPA provider (cross your fingers).

JPA 2.0 supports all relationship types from an embeddable object.


 * TopLink / EclipseLink : Support relationship mappings from embeddables. The existing relationship annotations or XML elements can be used.

Relationships to embeddable objects from entities other than the embeddable's parent are typically not a good idea, as an embeddable is a private dependent part of its parent. Generally relationships should be to the embeddable's parent, not the embeddable. Otherwise, it would normally be a good idea to make the embeddable an independent entity with its own table. If an embeddable has a bi-directional relationship, such as a  that requires an inverse   the inverse relationship should be to the embeddable's parent.

A workaround to having a relationship from an embeddable is to define the relationship in the embeddable's parent, and define property get/set methods for the relationship that set the relationship into the embeddable.

Example of setting a relationship in an embeddable from its parent
One special relationship that is sometimes desired in an embeddable is a relationship to its parent. JPA does not support this, but some JPA providers may.


 * Hibernate : Supports a  annotation in embeddables to define a relationship to its parent.

A workaround to having a parent relationship from an embeddable is to set the parent in the property set method.

Collections
A collection of embeddable objects is similar to a  except the target objects are embeddables and have no. This allows for a  to be defined without a inverse , as the parent is responsible for storing the foreign key in the target object's table. JPA 1.0 did not support collections of embeddable objects, but some JPA providers support this.

JPA 2.0 does support collections of embeddable objects through the  mapping. See, ElementCollection.


 * EclipseLink (as of 1.2) : Supports the JPA 2.0  mapping.


 * TopLink / EclipseLink : Support collections of embeddables. This is set through using a   and the.


 * Hibernate : Supports collections of embeddables through the  annotation and JPA 2.0   mapping.


 * DataNucleus : Supports the JPA 2.0  mapping.

Typically the primary key of the target table will be composed of the parent's primary key, and some unique field in the embeddable object. The embeddable should have a unique field within its parent's collection, but does not need to be unique for the entire class. It could still have a unique id and still use sequencing, or if it has no unique fields, its id could be composed of all of its fields. The embeddable collection object will be different than a typical embeddable object as it will not be stored in the parent's table, but in its own table. Embeddables are strictly privately owned objects, deletion of the parent will cause deletion of the embeddables, and removal from the embeddable collection should cause the embeddable to be deleted. Embeddables cannot be queried directly, and are not independent objects as they have no.

Querying
Embeddable objects cannot be queried directly, but they can be queried in the context of their parent. Typically it is best to select the parent, and access the embeddable from the parent. This will ensure the embeddable is registered with the persistence context. If the embeddable is selected in a query, the resulting objects will be detached, and changes will not be tracked.

Example of querying an embeddable
/Mapping