This is an automated email from the ASF dual-hosted git repository. asf-gitbox-commits pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/cayenne.git
commit 31d08f7125dcf3af6e822d0c4930811a370d2204 Author: Andrus Adamchik <[email protected]> AuthorDate: Fri May 22 16:50:02 2026 -0400 UPGRADE notes cleanup: merging upgrade-guide "book" to the .md file --- UPGRADE.md | 67 +++++++++++- docs/asciidoc/pom.xml | 1 - docs/asciidoc/upgrade-guide/pom.xml | 121 --------------------- .../src/docs/asciidoc/_upgrade-guide/changes.adoc | 74 ------------- .../src/docs/asciidoc/_upgrade-guide/header.html | 26 ----- .../docs/asciidoc/_upgrade-guide/new-features.adoc | 67 ------------ .../src/docs/asciidoc/upgrade-guide.adoc | 41 ------- 7 files changed, 64 insertions(+), 333 deletions(-) diff --git a/UPGRADE.md b/UPGRADE.md index a1add5877..d5f0d088c 100644 --- a/UPGRADE.md +++ b/UPGRADE.md @@ -87,7 +87,7 @@ and the release you are upgrading to. extensions. If you encounter those, change how you configure the modules, following this general pattern (using `CacheInvalidationModule` as an example): ```java - ServerRuntime.builder(..) + CayenneRuntime.builder(..) .addModule(b -> CacheInvalidationModule.extend(b).addHandler(MyHandler.class)) .build(); ``` @@ -95,7 +95,14 @@ and the release you are upgrading to. 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](https://issues.apache.org/jira/browse/CAY-2822) `cayenne-server` module is renamed to `cayenne` — update your build scripts accordingly. +* Per [CAY-2822](https://issues.apache.org/jira/browse/CAY-2822) `cayenne-server` module is renamed to `cayenne` — update your build scripts accordingly: + ```xml + <dependency> + <groupId>org.apache.cayenne</groupId> + <artifactId>cayenne</artifactId> + <version>{version}</version> + </dependency> + ``` * Per [CAY-2823](https://issues.apache.org/jira/browse/CAY-2823) `ServerRuntime` is deprecated. Use `org.apache.cayenne.runtime.CayenneRuntime` instead. @@ -106,7 +113,13 @@ and the release you are upgrading to. * Per [CAY-2825](https://issues.apache.org/jira/browse/CAY-2825) Package `org.apache.cayenne.configuration.server` was renamed to `org.apache.cayenne.configuration.runtime` — fix your imports accordingly. -* Per [CAY-2826](https://issues.apache.org/jira/browse/CAY-2826) `ServerModule` renamed to `CoreModule`. +* Per [CAY-2826](https://issues.apache.org/jira/browse/CAY-2826) `ServerModule` renamed to `CoreModule`. The new builder pattern combining both changes: + ```java + CayenneRuntime runtime = CayenneRuntime.builder() + .addConfig("cayenne-project.xml") + .module(b -> CoreModule.extend(b).setProperty("some_property", "some_value")) + .build(); + ``` * Per [CAY-2828](https://issues.apache.org/jira/browse/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 @@ -115,3 +128,51 @@ and the release you are upgrading to. * Per [CAY-2845](https://issues.apache.org/jira/browse/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. + +## New Features in 5.0 + +### 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: + +```xml +<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: + +```java +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: + +```java +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")); +``` diff --git a/docs/asciidoc/pom.xml b/docs/asciidoc/pom.xml index 82651a743..5be5446a1 100644 --- a/docs/asciidoc/pom.xml +++ b/docs/asciidoc/pom.xml @@ -36,7 +36,6 @@ <module>cayenne-guide</module> <module>getting-started-guide</module> <module>getting-started-db-first</module> - <module>upgrade-guide</module> </modules> <properties> diff --git a/docs/asciidoc/upgrade-guide/pom.xml b/docs/asciidoc/upgrade-guide/pom.xml deleted file mode 100644 index 5e3d9a8ba..000000000 --- a/docs/asciidoc/upgrade-guide/pom.xml +++ /dev/null @@ -1,121 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!--~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - ~ Licensed to the Apache Software Foundation (ASF) under one - ~ or more contributor license agreements. See the NOTICE file - ~ distributed with this work for additional information - ~ regarding copyright ownership. The ASF licenses this file - ~ to you under the Apache License, Version 2.0 (the - ~ "License"); you may not use this file except in compliance - ~ with the License. You may obtain a copy of the License at - ~ - ~ https://www.apache.org/licenses/LICENSE-2.0 - ~ - ~ Unless required by applicable law or agreed to in writing, - ~ software distributed under the License is distributed on an - ~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY - ~ KIND, either express or implied. See the License for the - ~ specific language governing permissions and limitations - ~ under the License. - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~--> - -<project xmlns="http://maven.apache.org/POM/4.0.0"; xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd";> - <parent> - <artifactId>cayenne-asciidoc-parent</artifactId> - <groupId>org.apache.cayenne.docs</groupId> - <version>5.0-SNAPSHOT</version> - </parent> - - <modelVersion>4.0.0</modelVersion> - <artifactId>upgrade-guide</artifactId> - <name>${project.artifactId}: Asciidoc - Cayenne New Features and Upgrade Guide</name> - - <build> - <plugins> - <plugin> - <groupId>org.asciidoctor</groupId> - <artifactId>asciidoctor-maven-plugin</artifactId> - <dependencies> - <dependency> - <groupId>io.bootique.tools</groupId> - <artifactId>hugo-asciidoctorj-extension</artifactId> - <version>${hugo.asciidoctorj.extension.version}</version> - </dependency> - </dependencies> - - <executions> - <!-- generate "embeddable" html content with front matter and without header/footer/styles --> - <execution> - <id>asciidoctor-html-web</id> - <phase>generate-resources</phase> - <goals> - <goal>process-asciidoc</goal> - </goals> - <configuration> - <backend>html5</backend> - <standalone>false</standalone> <!-- do not generate header and footer --> - <outputDirectory>${project.build.directory}/tmp/</outputDirectory> - <extensions> - <extension> - <className>io.bootique.tools.asciidoctorj.HugoExtension</className> - </extension> - </extensions> - <attributes> - <toc>auto</toc> - </attributes> - </configuration> - </execution> - </executions> - </plugin> - </plugins> - </build> - - <profiles> - <profile> - <id>assembly</id> - <build> - <plugins> - <plugin> - <groupId>org.asciidoctor</groupId> - <artifactId>asciidoctor-maven-plugin</artifactId> - <executions> - <!-- generate standalone html help --> - <execution> - <id>asciidoctor-html-standalone</id> - <phase>${build.docs}</phase> - <goals> - <goal>process-asciidoc</goal> - </goals> - <configuration> - <backend>html5</backend> - <embedAssets>true</embedAssets> - <attributes> - <toc>left</toc> - <source-highlighter>coderay</source-highlighter> - </attributes> - </configuration> - </execution> - - <!-- generate PDF --> - <execution> - <id>generate-pdf-doc</id> - <phase>${build.docs}</phase> - <goals> - <goal>process-asciidoc</goal> - </goals> - <configuration> - <backend>pdf</backend> - <attributes> - <pagenums /> - <toc /> - <source-highlighter>coderay</source-highlighter> - </attributes> - </configuration> - </execution> - </executions> - </plugin> - </plugins> - </build> - </profile> - </profiles> - -</project> \ No newline at end of file diff --git a/docs/asciidoc/upgrade-guide/src/docs/asciidoc/_upgrade-guide/changes.adoc b/docs/asciidoc/upgrade-guide/src/docs/asciidoc/_upgrade-guide/changes.adoc deleted file mode 100644 index 854e14788..000000000 --- a/docs/asciidoc/upgrade-guide/src/docs/asciidoc/_upgrade-guide/changes.adoc +++ /dev/null @@ -1,74 +0,0 @@ -// Licensed to the Apache Software Foundation (ASF) under one or more -// contributor license agreements. See the NOTICE file distributed with -// this work for additional information regarding copyright ownership. -// The ASF licenses this file to you under the Apache License, Version -// 2.0 (the "License"); you may not use this file except in compliance -// with the License. You may obtain a copy of the License at -// -// https://www.apache.org/licenses/LICENSE-2.0 Unless required by -// applicable law or agreed to in writing, software distributed under the -// License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR -// CONDITIONS OF ANY KIND, either express or implied. See the License for -// the specific language governing permissions and limitations under the -// License. - -== Java Version - -Minimum required JDK version is 21 or newer. If your project requires Java 8 or 11, you should keep using Cayenne 4.2. -Cayenne 5.0 is fully tested with Java 21 and 25. - -== Incompatible Changes - -Apache Cayenne 5.0-M1 removes support for a multi-layered stack, so no more Cayenne ROP and all the related client parts. -Moreover, this release renames every part that contains `server` in its name, including the main library. -For all the details please consult `UPGRADE.txt`, as this document only highlights the most impactful changes. - -=== Main Library Renaming - -Main Cayenne artifact is renamed from `cayenne-server` to `cayenne`, so you need to change your dependencies accordingly - -[source,xml] ----- -<dependency> - <groupId>org.apache.cayenne</groupId> - <artifactId>cayenne</artifactId> - <version>{version}</version> -</dependency> ----- - -=== Server Runtime and Module Deprecation - -`ServerRuntime` is deprecated and replaced by `CayenneRuntime`. As well as `ServerModule` renamed to `CoreModule`. - -[source,java] ----- -CayenneRuntime runtime = CayenneRuntime.builder() - .addConfig("cayenne-project.xml") - .module(b -> CoreModule.extend(b).setProperty("some_property", "some_value")) - .build(); ----- - -=== New Modules Extenders - -Each Cayenne module now provides a module-specific extender created with an "extend(Binder)" method. -It is usually invoked within a lambda that produces a Module, or within an app Module. - -[source,java] ----- -CayenneRuntime.builder(..) - .addModule(b -> CacheInvalidationModule.extend(b).addHandler(MyHandler.class)) - .build(); ----- - -=== Removal of Deprecated Modules - -- All modules related to the ROP functionality is completely gone. -That includes `cayenne-rop-server`, `cayenne-client` and other related parts. -- `cayenne-xmpp`, `cayenne-jms` and `cayenne-jgroups` event bridges are removed. -- Finally `cayenne-joda` and `cayenne-web` modules are gone. - -=== Removal of Deprecated Code - -As always, code deprecated in earlier versions is gone. One notable class removed is `SelectQuery`, so you should use `ObjectSelect` from now on. - - diff --git a/docs/asciidoc/upgrade-guide/src/docs/asciidoc/_upgrade-guide/header.html b/docs/asciidoc/upgrade-guide/src/docs/asciidoc/_upgrade-guide/header.html deleted file mode 100644 index 44a7bf648..000000000 --- a/docs/asciidoc/upgrade-guide/src/docs/asciidoc/_upgrade-guide/header.html +++ /dev/null @@ -1,26 +0,0 @@ ---- -# Licensed to the Apache Software Foundation (ASF) under one -# or more contributor license agreements. See the NOTICE file -# distributed with this work for additional information -# regarding copyright ownership. The ASF licenses this file -# to you under the Apache License, Version 2.0 (the -# "License"); you may not use this file except in compliance -# with the License. You may obtain a copy of the License at -# -# https://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, -# software distributed under the License is distributed on an -# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY -# KIND, either express or implied. See the License for the -# specific language governing permissions and limitations -# under the License. - -title: "Guide to 5.0 Features" -description: "This guide highlights the new features and changes introduced in Apache Cayenne 5.0" -cayenneVersion: "5.0" -docsMenuTitle: "Upgrade Guide" -weight: 50 ---- - - diff --git a/docs/asciidoc/upgrade-guide/src/docs/asciidoc/_upgrade-guide/new-features.adoc b/docs/asciidoc/upgrade-guide/src/docs/asciidoc/_upgrade-guide/new-features.adoc deleted file mode 100644 index 88a45695a..000000000 --- a/docs/asciidoc/upgrade-guide/src/docs/asciidoc/_upgrade-guide/new-features.adoc +++ /dev/null @@ -1,67 +0,0 @@ -// Licensed to the Apache Software Foundation (ASF) under one or more -// contributor license agreements. See the NOTICE file distributed with -// this work for additional information regarding copyright ownership. -// The ASF licenses this file to you under the Apache License, Version -// 2.0 (the "License"); you may not use this file except in compliance -// with the License. You may obtain a copy of the License at -// -// https://www.apache.org/licenses/LICENSE-2.0 Unless required by -// applicable law or agreed to in writing, software distributed under the -// License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR -// CONDITIONS OF ANY KIND, either express or implied. See the License for -// the specific language governing permissions and limitations under the -// License. - -== New Features - -=== New Dev Versioning Scheme - -From now on a snapshot version of Cayenne is a constant value, so the dev version of 5.0 will always be 5.0-SNAPSHOT. -So you can always stay at the bleeding edge of development if needed. - -[source,xml] ----- -<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 the Cayenne Modeler 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 - -In most cases, you don’t need to deal with a subquery for `(not)exists` queries, as it is now directly supported by the Expression API. -That includes `Expression`, expression parser, and Property API. - -This feature can handle any expression and spawn several sub-queries per expression if needed. - -[source,java] ----- -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. - -[source,java] ----- -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")); ----- - diff --git a/docs/asciidoc/upgrade-guide/src/docs/asciidoc/upgrade-guide.adoc b/docs/asciidoc/upgrade-guide/src/docs/asciidoc/upgrade-guide.adoc deleted file mode 100644 index d4092d050..000000000 --- a/docs/asciidoc/upgrade-guide/src/docs/asciidoc/upgrade-guide.adoc +++ /dev/null @@ -1,41 +0,0 @@ -// Licensed to the Apache Software Foundation (ASF) under one or more -// contributor license agreements. See the NOTICE file distributed with -// this work for additional information regarding copyright ownership. -// The ASF licenses this file to you under the Apache License, Version -// 2.0 (the "License"); you may not use this file except in compliance -// with the License. You may obtain a copy of the License at -// -// https://www.apache.org/licenses/LICENSE-2.0 Unless required by -// applicable law or agreed to in writing, software distributed under the -// License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR -// CONDITIONS OF ANY KIND, either express or implied. See the License for -// the specific language governing permissions and limitations under the -// License. -= Guide to {project-major-version} Features -:revnumber: {project-major-version} ({project-version}) -// enable section numbering, limiting depth to 2 -:sectnums: -:sectnumlevels: 2 -// use custom header -:hugo-header: _upgrade-guide/header.html -// base path to java code include -:cayenne-root: {basedir}/../../.. - -[small]#Copyright © 2011-{docyear} Apache Software Foundation and individual authors# - -.License -[small]#_Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. -See the NOTICE file distributed with this work for additional information regarding copyright ownership. -The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); -you may not use this file except in compliance with the License. You may obtain -a copy of the License at https://www.apache.org/licenses/LICENSE-2.0_# - -[small]#_Unless required by applicable law or agreed to in writing, software distributed under the License -is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -See the License for the specific language governing permissions and limitations under the License._# - -This guide highlights the new features and changes introduced in Apache Cayenne 5.0. For a full list of changes consult -RELEASE-NOTES.txt included in Cayenne download. For release-specific upgrade instructions check UPGRADE.txt. - -include::_upgrade-guide/changes.adoc[] -include::_upgrade-guide/new-features.adoc[] \ No newline at end of file
