Cayenne runtime framework is an intermediary between a Java application and a relational database. The picture below shows the main components of the framework:

Vertical Structure - Cayenne Persistence Stack

Vertically this structure reflects the runtime organization of the Cayenne persistence stack. Cayenne instantiates and configures the stack (shown in yellow above) using the XML descriptors provided by the user (usually these are the XML files created by CayenneModeler). Alternatively persistence stack can be assembled via the API and/or using Spring or any similar approach. Moreover Cayenne stack is fully dynamic and can be altered at runtime, since currently (as of version 1.2) Cayenne does not rely on bytecode enhancement.

Horizontal Structure - Cayenne Layers

The top Cayenne layer (ObjectContext, Query API, Expression API) is what the application needs to work with persistent objects. This layer implements Cayenne part of the persistence contract between the application and the framework, while underlying layers deal with details of the object-to-relational translation and data source interaction. Access to the mapping metadata and the stack objects residing in the lower layers is possible via the API.

Runtime Components

Many individual components of the framework are discussed in the following chapters: