An Embeddable is a persistent Java class that does not have its own persistent "identity" ("identity" is an ORM concept similar to "primary key") and is managed by Cayenne as a part of its owning object. Embeddables are mapped in Cayenne similar to ObjEntities, except that they are not linked to any DbEntity. An Embeddable becomes linked to one when it is "embedded" in an owning ObjEntity. "Embedding" means mapping ObjEntity's ObjAttribute to an embeddable type. A single embeddable can be included ("embedded") in more than one ObjEntity.
Embeddable classes are generated by Cayenne (via the Modeler, Ant or Maven), just like other persistent classes. There's no common embeddable superclass, so each embeddable inherits from Object. Still Cayenne generates a familiar pair of _Xyz superclass and Xyz subclass for each Embeddable.
Mapping an Embeddable
A new Embeddable is created by clicking on the "Create Embeddable" button on the toolbar (or selecting an appropriate item from the menu). The only required field is a fully qualified class name:
An embeddable can have one or more attributes. Each attribute requires at least the name and the java type specified. Quite often you would also specify the DbAttribute name. Although Embeddable is not connected to a DbEntity just yet, this will save some typing during embedding it to ObjEntities (provided the DB column names for the Embeddable are the same across ObjEntities):
Embedding an Embeddable
The process of embedding an Embeddable is rather simple. Add a new attribute to your Java class (under the ObjEntity Attributes tab) and then inspect the entry. (Note: It is important that you inspect the entry instead of entering the embeddable's type directly in the Java Type column under the Attributes tab due to a limitation in Cayenne Modeler.) Select the embeddable type in the Type pulldown list. CayenneModeler will automatically include all Embeddable classes it knows about in the Java types dropdown. If the underlying DbEntity has the same column names as the original Embeddable, that's all you need to do. If not, you can override the default column names by clicking on the attribute inspector button ("I") and changing DbAttribute mappings for this particular embedding:
