Flattened Relationships
ObjRelationships that map to more than a single DbRelationship are called "flattened".
The most common case for using flattened relationships is modeling many-to-many relationships with a join table. E.g. ARTIST DbEntity has to-many relationship to ARTIST_EXHIBIT; ARTIST_EXHIBIT in turn has a to-one relationship to EXHIBIT DbEntity. We can create a single ObjRelationship from Artist ObjEntity to Exhibit ObjEntity that spawns two DbRelationships. This will be a to-many relationship. Lets say it is called "exhibitArray". Generated class file for Artist would contain a getExhibitArray() method returning a list of Exhibits for a given artist instance. An obvious advantage of having a flattened relationship in this case is to avoid mapping a join table as an object, meaningless in the context of the object model.
Flattened relationships work across any combination of to-one and to-many DbRelationships. If all the relationships are to-one, then the resulting flattened relationship is also to-one. If there is at least one to-many, the result is to-many as well.
 | Read-Only Note Most of flattened relationships are treated as read-only by Cayenne. Only one (the most commonly used) type is read/write. It is many-to-many (n:m) flattened relationships with a single join table. |
To map an ObjRelationship to a chain of DbRelationships, select ObjRelationship table row and click "Edit Relationship" button in the bottom right. "ObjRelationship Inspector" dialog will appear.
The dialog contains a DbRelationship table. Clicking on each row in this table will show valid choices of DbRelationships. Once you add a "chain" component, another row automatically opens below, so you can build a chain of arbitrary length.
 | Join Table Tip If you flatten across a join table and this join table was mapped to an ObjEntity (and a correspoding Java class), such ObjEntity can be deleted, as it is no longer needed. Underlying DbEntity must be preserved. |