Apache Cayenne Upgrade Guide

For upgrade notes for Cayenne 4.2 and older, see UPGRADE-4.2-and-older.md.

What's New in 5.0

This is a high-level overview of 5.0 changes. Check the next section for milestone-by-milestone upgrade instructions.

New Dev Versioning Scheme

Snapshot versions are now a constant value — the dev version of 5.0 will always be 5.0-SNAPSHOT, so you can stay at the bleeding edge of development if needed:

<dependency>
    <groupId>org.apache.cayenne</groupId>
    <artifactId>cayenne</artifactId>
    <version>5.0-SNAPSHOT</version>
</dependency>

New Class Generation UI

The new Class Generation UI in CayenneModeler simplifies configuration, allows multiple cgen setups per project, and includes a template editor. Custom templates are now part of the project XML configuration and don't require separate setup in either Modeler or Maven/Gradle plugins.

Improved `(not)exists` Queries

(not)exists is now directly supported by the Expression API (including Expression, the expression parser, and the Property API) — no need to construct a subquery manually. The feature can handle any expression and spawn several sub-queries per expression if needed:

long count = ObjectSelect.query(Artist.class)
        .where(Artist.PAINTING_ARRAY.dot(Painting.PAINTING_TITLE).like("painting%").exists())
        .selectCount(context);

Improved SQL Support

ANY and ALL subqueries are now supported, as well as case-when expressions:

import static org.apache.cayenne.exp.ExpressionFactory.*;
// ...
Expression caseWhenExp = caseWhen(
        List.of(betweenExp("estimatedPrice", 0, 9),
                betweenExp("estimatedPrice", 10, 20)),
        List.of(wrapScalarValue("low"),
                wrapScalarValue("high")),
        wrapScalarValue("error"));

Upgrading to 5.0.M2

Per CAY-2947 the cayenne-commitlog artifact has been removed. Commit log support is now part of the core cayenne artifact — no extra dependency needed. Migrate as follows:
- Remove the cayenne-commitlog dependency from your build.
- Replace CommitLogModule.extend(binder).addListener(l) with:
```
CoreModule.extend(binder).addCommitLogListener(l)
```
- excludeFromTransaction() is now excludeCommitLogFromTransaction() on CoreModuleExtender.
- Replace @org.apache.cayenne.commitlog.CommitLog on entity classes with @org.apache.cayenne.annotation.CommitLog.
- The CommitLogListener, ChangeMap, ObjectChange and related model classes remain in the org.apache.cayenne.commitlog package (now part of the core artifact).
Per CAY-2935 Minimum required Java version for Apache Cayenne 5.0 is 21.
Per CAY-2937 the visual graph feature (entity layout diagrams) has been removed from CayenneModeler. Existing .graph.xml files will be automatically deleted and their references removed from cayenne-project.xml when a project is opened in the Modeler and upgraded to the newest format.
Per CAY-2859 SelectById query factory methods are redesigned with a bunch of old methods deprecated — update your calls accordingly.
Per CAY-2917 joins are generated in a different order in the Select SQL. This should not affect any logic except if your code relies on the generated SQL in any way.
Per CAY-2924 the org.apache.cayenne.map.event package (mapping events and listener interfaces) was moved from the core to the CayenneModeler module — these events are not used at runtime. As part of this:
- DbEntity, ObjEntity and DataMap no longer implement the *Listener interfaces and no longer expose the internal event-consumer methods (dbEntityChanged, objEntityChanged, dbAttributeAdded, handleAttributeUpdate, etc.).
- New public rename APIs replace the previous “set name + fire change event” pattern: DataMap.renameDbEntity(DbEntity, String), DataMap.renameObjEntity(ObjEntity, String), DbEntity.renameAttribute(DbAttribute, String) and DbEntity.renameRelationship(DbRelationship, String). Prefer these over setName(...) for renames, as they re-key the parent maps and update dependent references.
- DbAttribute.setPrimaryKey(boolean) and DbAttribute.setGenerated(boolean) no longer fire events; they update their parent DbEntity's cached collections via direct method calls, behavior-equivalent to before. If your application code subscribed to these mapping events at runtime, migrate to direct calls or to the Modeler.
Per CAY-2925 the cayenne-modeler-maven-plugin was removed. Launch CayenneModeler from the downloaded distribution instead. A CLI option also exists for all platform flavors:
```
java -jar CayenneModeler.jar path/to/cayenne-project.xml
```
or on macOS:
```
open CayenneModeler.app --args path/to/cayenne-project.xml
```
Per CAY-2955 the obsolete QueryEngine abstraction (org.apache.cayenne.access.QueryEngine) has been removed. DataNode is now used directly wherever QueryEngine was previously referenced. So you must subclass DataNode and override performQueries() if you previously implemented a custom QueryEngine.

Upgrading to 5.0.M1

Per CAY-2737 All code deprecated in Cayenne 4.1 and 4.2 was deleted — please review your code before upgrading. Most notable removals are SelectQuery and these Cayenne modules:
- cayenne-dbcp2
- cayenne-joda
- cayenne-client
- cayenne-client-jetty
- cayenne-protostuff
- cayenne-rop-server
- cayenne-web
- cayenne-jgroups
- cayenne-jms
- cayenne-xmpp
Per CAY-2742 Minimum required Java version for Apache Cayenne is 11.
Per CAY-2747 Cayenne XML schemas are updated — update your projects by opening them in the Modeler or using the cayenne-project-compatibility module.
Per CAY-2751 There is no more JNDI DataSource provided by Cayenne, nor password encoding capabilities. If you need these, provide your own custom DataSource.
Per CAY-2752 Code generation configuration has minor changes — review and update Maven, Gradle and Ant configs accordingly.
Per CAY-2772 Module extension is done differently. This may result in compile errors in some module extensions. If you encounter those, change how you configure the modules, following this general pattern (using CacheInvalidationModule as an example):
```
CayenneRuntime.builder(..)
    .addModule(b -> CacheInvalidationModule.extend(b).addHandler(MyHandler.class))
    .build();
```
Two things to note: (1) a module-specific extender is created using an extend(Binder) method of the module, and (2) an extender does not produce a Module — instead it adds services directly to the Binder. So it is usually invoked within a lambda that produces a Module, or within an app Module.

Per CAY-2822 cayenne-server module is renamed to cayenne — update your build scripts accordingly:

<dependency>
    <groupId>org.apache.cayenne</groupId>
    <artifactId>cayenne</artifactId>
    <version>{version}</version>
</dependency>

Per CAY-2823 ServerRuntime is deprecated. Use org.apache.cayenne.runtime.CayenneRuntime instead.
Per CAY-2824 CayenneServerModuleProvider was renamed to CayenneRuntimeModuleProvider and moved to the org.apache.cayenne.runtime package. If you are using the auto-loading mechanism for your custom modules, update your META-INF/services reference accordingly.
Per CAY-2825 Package org.apache.cayenne.configuration.server was renamed to org.apache.cayenne.configuration.runtime — fix your imports accordingly.

Per CAY-2826 ServerModule renamed to CoreModule. The new builder pattern combining both changes:

CayenneRuntime runtime = CayenneRuntime.builder()
        .addConfig("cayenne-project.xml")
        .module(b -> CoreModule.extend(b).setProperty("some_property", "some_value"))
        .build();

Per CAY-2828 The server prefix was removed from the names of runtime properties and named collections defined in org.apache.cayenne.configuration.Constants. Update references in code and in any scripts that use them as system properties.
Per CAY-2845 DataObject interface and BaseDataObject class were deprecated and all logic moved to the Persistent interface and PersistentObject class. Regenerate model classes via the cgen tool in CayenneModeler or Maven/Gradle plugins.