You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@cayenne.apache.org by aa...@apache.org on 2026/05/22 20:52:28 UTC
(cayenne) branch master updated: UPGRADE notes cleanup:
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
The following commit(s) were added to refs/heads/master by this push:
new b51630b6e UPGRADE notes cleanup:
b51630b6e is described below
commit b51630b6e04e5692a6372966c7c1b0485a4a3bf1
Author: Andrus Adamchik <an...@objectstyle.com>
AuthorDate: Fri May 22 16:50:02 2026 -0400
UPGRADE notes cleanup:
1. (really) converting to markdown
2. splitting older notes into a separate file
---
UPGRADE-4.2-and-older.md | 611 ++++++++++++++++++++++++++++++++++++++++
UPGRADE.md | 121 ++++++++
UPGRADE.txt | 719 -----------------------------------------------
3 files changed, 732 insertions(+), 719 deletions(-)
diff --git a/UPGRADE-4.2-and-older.md b/UPGRADE-4.2-and-older.md
new file mode 100644
index 000000000..652c801ce
--- /dev/null
+++ b/UPGRADE-4.2-and-older.md
@@ -0,0 +1,611 @@
+# Apache Cayenne Upgrade Guide — 4.2 and Older
+
+> These notes cover Cayenne releases up to and including 4.2.
+> For 5.0 and newer, see [UPGRADE.md](UPGRADE.md).
+
+---
+
+## Upgrading to 4.2.M2
+
+* Per CAY-2659 All batch translators (`InsertBatchTranslator`, `UpdateBatchTranslator`, etc.) are updated
+ to the new SQLBuilder utility. If you are using customized versions of these classes you should either
+ update them accordingly, or keep using the old versions which are moved to the
+ `org.apache.cayenne.access.translator.batch.legacy` package.
+
+---
+
+## Upgrading to 4.2.M1
+
+* Per CAY-2520 `ObjectId` can't be instantiated directly — use `ObjectId.of(..)` methods instead:
+ ```java
+ ObjectId.of("Artist", 1) // instead of new ObjectId("Artist", 1)
+ ```
+
+* Per CAY-2523 `SelectQuery` was deprecated. Use `ObjectSelect` instead.
+
+* Per CAY-2525 OpenBase adapter was deprecated.
+
+* Per CAY-2467 `Property` class is replaced with a type-aware `Property` API — mostly backwards
+ compatible. To take advantage of the new API, regenerate code via Modeler
+ ("Tools" → "Generate Classes") or cgen tools.
+
+* Per CAY-2563 The following methods were deprecated:
+ ```java
+ SQLSelect.scalarQuery(Class<T>, String)
+ SQLSelect.scalarQuery(Class<T>, String, String)
+ ```
+
+* Per CAY-2585 The following methods were deprecated:
+ ```java
+ SQLSelect.scalarQuery(String sql)
+ SQLSelect.scalarQuery(String sql, String dataMapName)
+ SQLSelect.scalarQuery(String sql, Class<?> firstType, Class<?>... types)
+ SQLSelect.scalarQuery(String sql, String dataMapName, Class<?> firstType, Class<?>... types)
+ SQLSelect.params(String name, Object value)
+ ```
+
+---
+
+## Upgrading to 4.1.M3
+
+* Per CAY-2514 `SERVER_CONTEXTS_SYNC_PROPERTY` default value was set to `false`.
+
+---
+
+## Upgrading to 4.1.M2
+
+* Per CAY-2438 `DataChannelFilter` was deprecated and two new independent filters are introduced:
+ `DataChannelSyncFilter` and `DataChannelQueryFilter`.
+
+* Per CAY-2400 `cayenne-dbcp2` integration was deprecated.
+
+* Per CAY-2377 All code deprecated in Cayenne 4.0 was removed — please review your code before upgrading.
+
+* Per CAY-2372 Three new modules were extracted from Cayenne core. No changes to packages or API were
+ made, so only include the additional modules in your project if you use them:
+ - `cayenne-web` — contains all logic related to bootstrapping Cayenne inside a servlet container.
+ `WebModule` is autoloaded, so you shouldn't add it to the runtime explicitly any more.
+ - `cayenne-osgi` — contains OSGi related functionality.
+ - `cayenne-rop-server` — ROP server part.
+
+---
+
+## Upgrading to 4.1.M1
+
+* Per CAY-2351 Minimum supported Java version is now Java 8. There is no option to use Cayenne 4.1 with
+ earlier versions — use 4.0 if Java 7 is required.
+
+* Per CAY-2345 Velocity was replaced with Cayenne's own template engine by default in `cayenne-server`.
+ This should be transparent in almost all cases; however if you relied on advanced Velocity features in
+ `SQLTemplate` you can include the auto-loaded `cayenne-velocity` module to keep using Velocity — no
+ other action required.
+
+* Per CAY-2335 `ServerRuntime` by default will fail to load projects in case of version mismatch.
+ You have two options:
+ - Update project files by opening them in CayenneModeler.
+ - Use the `cayenne-project-compatibility` module — add it as a dependency. Note: it only supports
+ versions created by Cayenne 3.1 or later.
+
+* Per CAY-2330 Field-based data objects are introduced and enabled by default. Your existing code will
+ continue to work, but to get the benefits you should regenerate code via Modeler
+ ("Tools" → "Generate Classes") or cgen tools in Maven/Ant/Gradle plugins. Also note that the
+ serialization format of old data objects has changed — do not use serialized form to store objects.
+
+---
+
+## Upgrading to 4.0.B1
+
+* Per CAY-2302 `postcommit` module and all its internals renamed to `commitlog`. The most important
+ change is the new `@CommitLog` annotation which should be used instead of `@Auditable`. This change
+ is backward incompatible and most likely to be missed, as the IDE won't give you a hint. Note that
+ the new `@CommitLog` annotation is used only by the `commitlog` module — deprecated functionality
+ in the `lifecycle` module still depends on `@Auditable`.
+
+ Steps to update:
+ 1. Include `cayenne-commitlog` in your project (add a dependency to your `pom.xml`).
+ 2. Remove `cayenne-lifecycle` (and `cayenne-postcommit` if present) from your project.
+ 3. Switch usages of `@Auditable` to `@CommitLog`.
+ 4. Change usages of renamed classes:
+ ```
+ PostCommitListener -> CommitLogListener
+ PostCommitModuleBuilder -> CommitLogModuleExtender
+ ```
+ 5. Fix all imports for renamed packages:
+ ```
+ org.apache.cayenne.lifecycle.postcommit -> org.apache.cayenne.commitlog
+ org.apache.cayenne.lifecycle.changemap -> org.apache.cayenne.commitlog.model
+ ```
+ 6. Change `CommitLogModuleExtender` methods:
+ ```
+ auditableEntitiesOnly() -> commitLogAnnotationEntitiesOnly()
+ build() -> module()
+ ```
+
+* Per CAY-2280 Cayenne migrated from commons-logging to SLF4J. Options:
+ 1. Migrate your logging to SLF4J. See https://www.slf4j.org for documentation.
+ 2. Use commons-logging over SLF4J to keep logging compatible with previous Cayenne versions:
+ - Remove the `commons-logging` dependency if you have it.
+ - Add `slf4j-jcl` as a dependency.
+
+ As part of this change `CommonsJdbcEventLogger` and `FormattedCommonsJdbcEventLogger` were renamed to
+ `Slf4jJdbcEventLogger` and `FormattedSlf4jJdbcEventLogger` respectively. They now use
+ `org.apache.cayenne.log.JdbcEventLogger` as the logger name.
+
+* Per CAY-2278 Packages `org.apache.cayenne.lifecycle.audit` and `org.apache.cayenne.lifecycle.changeset`
+ were deprecated. Use the `cayenne-commitlog` module and its new `@CommitLog` annotation instead.
+
+ Weighted graph sorter moved to `cayenne-server` into `org.apache.cayenne.ashwood` package.
+
+ Packages `org.apache.cayenne.lifecycle.changemap` and `org.apache.cayenne.lifecycle.postcommit` were
+ moved to the new `cayenne-commitlog` module. Update your code accordingly (see also notes for CAY-2302
+ above).
+
+* Per CAY-2277 `ClientRuntime` is now created with `ClientRuntimeBuilder` — direct instantiation of
+ `ClientRuntime` is deprecated. Also the whole `ClientLocalRuntime` class is deprecated; use
+ `ClientRuntimeBuilder.local()` instead.
+
+* Per CAY-2262 Client modules are now auto-loaded by default. To turn off auto-loading use
+ `ClientRuntimeBuilder.disableModulesAutoLoading()`.
+
+ Client modules:
+ - `cayenne-client`
+ - `cayenne-client-jetty`
+ - `cayenne-protostuff` (also supports auto-loading by `ServerRuntimeBuilder`)
+
+ New modules extracted from existing ones — add to your `pom.xml` if you use this functionality:
+ - `cayenne-cache-invalidation` (was part of `cayenne-lifecycle`)
+ - `cayenne-commitlog` (was part of `cayenne-lifecycle`)
+
+* Per CAY-2259 Cache invalidation module refactored. Changes:
+ - Package `org.apache.cayenne.lifecycle.cache` renamed to `org.apache.cayenne.cache.invalidation`.
+ - `CacheInvalidationModuleBuilder` renamed to `CacheInvalidationModuleExtender`; its `build()` method
+ renamed to `module()`.
+ - `InvalidationFunction` now returns `CacheGroupDescriptor` instead of a plain `String` with the cache
+ group name — update your custom functions accordingly.
+
+* Per CAY-2268 DI methods for binding ordered lists (introduced in 4.0.M3) were changed:
+ - `after()` replaced by `addAfter()`, `addAllAfter()`
+ - `before()` replaced by `insertBefore()`, `insertAllBefore()`
+
+* Per CAY-2258 Injection of `List` and `Map` is now type-safe, introducing small incompatibilities.
+ Change:
+ ```java
+ bindMap(String bindingName)
+ bindList(String bindingName)
+ ```
+ to the type-safe versions:
+ ```java
+ bindMap(Class<T> valueType, String bindingName)
+ bindList(Class<T> valueType, String bindingName)
+ ```
+ Also change DI keys like `Key.get(Map.class, "bindingName")` or `Key.get(List.class, "bindingName")`
+ to the new factory methods `Key.mapOf(MapValues.class, "bindingName")` and
+ `Key.listOf(ListValues.class, "bindingName")`.
+
+ The new API also allows binding `List`s and `Map`s without names:
+ ```java
+ binder.bindList(SomeUniqueType.class).add(...);
+ @Inject List<SomeUniqueType> list;
+ ```
+
+* Per CAY-1873 and CAY-2266 Cache and remote notification configuration was moved from Modeler into
+ runtime DI settings. To set a custom cache size, use a custom module:
+ ```java
+ Module module = binder -> {
+ ServerModule.setSnapshotCacheSize(binder, 20000);
+ };
+ ```
+ Or via command line: `-Dcayenne.DataRowStore.snapshot.size=20000`
+
+ If you use remote notifications, include one of these modules:
+ - `cayenne-jgroups`
+ - `cayenne-jms`
+ - `cayenne-xmpp`
+
+ For Maven, add a dependency, e.g.:
+ ```xml
+ <dependency>
+ <groupId>org.apache.cayenne</groupId>
+ <artifactId>cayenne-jgroups</artifactId>
+ <version>4.0.M6</version>
+ </dependency>
+ ```
+
+ The module will be autoloaded and remote notifications enabled — you only need to provide configuration
+ via a custom DI module. For JGroups:
+ ```java
+ Module module = binder -> {
+ JGroupsModule.contributeMulticastAddress(binder, MCAST_ADDRESS);
+ JGroupsModule.contributeMulticastPort(binder, MCAST_PORT));
+ };
+ ```
+
+* Per CAY-2256 Fix for CAY-2146 was reverted — it is not possible to reliably deduce whether a
+ relationship is optional or not. For mandatory relationships in vertical inheritance, perform manual
+ validation before insert using a `prePersist` callback (create it in CayenneModeler) or by overriding
+ `validateForSave()`.
+
+---
+
+## Upgrading to 4.0.M5
+
+* Per CAY-2186 `DerbyPkGenerator` switched from `AUTO_PK_TABLE` to a sequence-based PK generator.
+ If you relied on `AUTO_PK_TABLE` usage in Derby, update your code.
+
+* Per CAY-2228 Support for multiple cache groups has been removed from caching and query API, as none of
+ the modern providers supports it. If you relied on this feature you should implement it yourself or
+ change the caching provider.
+
+* Per CAY-1980 `maven-cayenne-modeler-plugin` renamed to `cayenne-modeler-maven-plugin`.
+
+* Per CAY-2225 `CacheInvalidationFilter` has been changed to support custom invalidation rules in addition
+ to the rule based on `@CacheGroups`. If you have used it previously, change its binding in your custom
+ module to use `CacheInvalidationModuleBuilder` instead of a direct binding.
+
+* Per CAY-2212 `cdbimport` tool revisited — Maven plugin configuration should be updated:
+ - `maven-cayenne-plugin` is deprecated; switch to `cayenne-maven-plugin`.
+ - `<reverseEngineering>` tag replaced with `<dbimport>`.
+ - New `<dataSource>` tag introduced that should enclose all connection properties:
+ 1. `<driver>`
+ 2. `<url>`
+ 3. `<user>`
+ 4. `<password>`
+ - Top-level properties moved into `<dbimport>`:
+ 1. `<defaultPackage>`
+ 2. `<forceDataMapCatalog>`
+ 3. `<forceDataMapSchema>`
+ 4. `<meaningfulPkTables>`
+ 5. `<namingStrategy>`
+ 6. `<stripFromTableNames>`
+ 7. `<usePrimitives>`
+ - Java 8 `java.time.*` types are now used by default in cdbimport (and in the "Reengineer Database
+ Schema" tool in Modeler). Control this with `<useJava7Types>` in `<dbimport>` (or a checkbox in
+ Modeler).
+ - For Ant users: `cayenne-tools.jar` split into two parts:
+ 1. `cayenne-ant.jar` for Ant tasks
+ 2. `cayenne-cgen.jar` for class generation (required only for the cgen task)
+
+* Per CAY-2166 Cayenne supports auto-loading of DI modules. Notable changes:
+ - **Service override policy:** Custom modules now override "builder" modules (implicit modules wrapping
+ builder method call customizations), since the builder is invoked explicitly during stack assembly
+ while modules may be written without knowledge of the final stack.
+ - **Module renaming:** If you see compile errors for `CayenneJodaModule` or `CayenneJava8Module`, just
+ remove explicit loading — they will be auto-loaded if on the classpath. If auto-loading is disabled,
+ use the new names: `JodaModule` and `Java8Module`.
+
+* Per CAY-2164 Creating a `ServerRuntimeBuilder` is now done via `ServerRuntime.builder()` (static
+ method). The previous style `ServerRuntimeBuilder.builder()` is deprecated.
+
+---
+
+## Upgrading to 4.0.M4
+
+* Per CAY-2133 `LegacyObjectNameGenerator` is no longer provided, as it wasn't possible to maintain it
+ in a fully backwards-compatible manner. Embrace the new naming scheme, or provide your own
+ `ObjectNameGenerator` if you absolutely need the old names.
+
+* Per CAY-2125 `SchemaUpdateStrategy` is no longer injected directly — `SchemaUpgradeStrategyFactory` is
+ injected instead. If you have custom modules with `SchemaUpdateStrategy` injection they will be ignored.
+ Update your DI code to use `SchemaUpgradeStrategyFactory` (or a subclass).
+
+* Per CAY-2060 4.0.M4 changes how queries are stored in mapping files — all existing `*.map.xml` files
+ should be upgraded. Open each project in the new CayenneModeler and agree to upgrade when prompted.
+
+ `EntityResolver.getQuery(String)` was removed. Consider switching to `MappedSelect` or `MappedExec`,
+ or use `EntityResolver.getQueryDescriptor(String).buildQuery()` if you need to retrieve a specific query.
+
+* Per CAY-2065 `ROPHessianServlet` was replaced by `ROPServlet`. Update your `web.xml`:
+ ```
+ org.apache.cayenne.configuration.rop.server.ROPHessianServlet -> org.apache.cayenne.rop.ROPServlet
+ ```
+
+* Per CAY-2118 Several deprecated keys in cdbimport configuration were removed, along with the ability
+ to set `reverseEngineering` config properties at the top level. In Maven you must always wrap them
+ inside `<reverseEngineering>`. Removed top-level keys:
+ 1. `catalog`
+ 2. `schema` (also `schemaName`)
+ 3. `excludeTables`
+ 4. `includeTables`
+ 5. `procedurePattern`
+ 6. `tablePattern`
+ 7. `importProcedures`
+ 8. `meaningfulPk`
+ 9. `overwrite`
+
+---
+
+## Upgrading to 4.0.M3
+
+* Per CAY-2026 Minimal Java version is now 1.7. Use Cayenne 3.1 or 4.0.M2 if your application requires
+ Java 1.6.
+
+* `@Deprecated` annotation is no longer added to generated String property names in entity superclasses.
+ String property name inclusion became optional, controlled by the `createPropertyNames` flag in cgen
+ (`false` by default). A similar option was added to the "Advanced" cgen dialog in CayenneModeler.
+ If you have references to `@Deprecated` String properties and run cgen without `createPropertyNames`,
+ there will be compile errors. See CAY-1991.
+
+* Per CAY-2008, CAY-2009 `org.apache.cayenne.conn.PoolManager` and its associated classes were removed.
+ A replacement pooling DataSource is available under `org.apache.cayenne.datasource` (`PoolingDataSource`,
+ `ManagedPoolingDataSource`), best assembled using `org.apache.cayenne.datasource.DataSourceBuilder`.
+
+* Per CAY-2012 API for `ObjectSelect` and `SelectById` was changed to remove "reset" functionality.
+ Methods like `where`, `prefetch`, `orderBy` that previously reset the corresponding option state now
+ work as "append". Methods that previously appended were removed as redundant. Revisit your code if you
+ relied on reset behavior.
+
+* If you are using `DBCPDataSourceFactory`, take the following steps:
+ - Per CAY-2025 and CAY-2026, `DBCPDataSourceFactory` is now based on DBCP2 (required under Java 1.7+).
+ - Check your DBCP properties file — property names must be supported by DBCP2. Remove any
+ `cayenne.dbcp.` prefix if still present.
+ - `DBCPDataSourceFactory` must now be explicitly included as a Cayenne module. For Maven:
+ ```xml
+ <parent>
+ <groupId>org.apache.cayenne</groupId>
+ <artifactId>cayenne-dbcp2</artifactId>
+ <version>4.0.M3</version>
+ </parent>
+ ```
+
+---
+
+## Upgrading to 4.0.M2
+
+* Note that the 3.2 line of development was renamed to 4.0 — 4.0.M2 is a direct descendant of 3.2M1.
+
+* `org.apache.cayenne.map.naming.SmartNamingStrategy` was replaced with
+ `org.apache.cayenne.map.naming.DefaultNameGenerator`. If you mentioned `SmartNamingStrategy`
+ explicitly in Maven or Ant configs, rename it. Since this was the default, chances are you didn't.
+
+* Minimal required JDK version is now 1.6.
+
+* Managing listeners in the Modeler was removed per CAY-1842. If you have listeners in the model, delete
+ them from XML and use annotations, registering them in runtime:
+ ```java
+ runtime.getDataDomain().addListener(myListener);
+ ```
+
+* `Cayenne.objectForSelect(Select)` (present in 3.2M1) was replaced with `ObjectContext.selectOne(Select)`.
+
+* In-memory expression evaluation (`Expression.match`/`Expression.evaluate`) will now return `true` when
+ matching a `Persistent` with an `ObjectId`, `Number`, or `String` (if those correspond to the object's
+ `ObjectId`). Also, two objects in different `ObjectContexts` will match even if they have differing
+ local changes — only their `ObjectId`s are compared. See CAY-1860 for details.
+
+* `ResultIterator` was moved to `org.apache.cayenne` to make it available on both server and client. When
+ upgrading related iterator code, review `ResultIterator` improvements: it implements `Iterable`, is no
+ longer limited to `DataRows`, and no longer requires catching checked exceptions. Also see
+ `ObjectContext.iterate(..)`.
+
+* Transaction management was refactored significantly:
+ - External transactions are no longer configured in the Modeler — they are provided as a DI property
+ defined in `Constants.SERVER_EXTERNAL_TX_PROPERTY`.
+ - `TransactionDelegate` is no longer present. Equivalent functionality can be achieved by writing a
+ decorator for the `Transaction` interface and using a custom `TransactionFactory`.
+ - If your code relied on `Transaction.externalTransaction()` or `Transaction.internalTransaction()`
+ for manual transaction management, use constructors of `ExternalTransaction` and `CayenneTransaction`
+ instead.
+
+* When switching to `ServerRuntimeBuilder`, users of multi-config projects may assume it has the same
+ behavior as 3.1 `ServerRuntime` for assigning the domain name (using the name of the last config).
+ `ServerRuntimeBuilder` will only use the config name if there's a single config and no override —
+ otherwise it uses the override, or `"cayenne"` as the default. See CAY-1972.
+
+---
+
+## Upgrading to 3.1.B1
+
+* Per CAY-1665 all properties and DI collection keys were placed in a single `Constants` interface, with
+ values following a single naming convention. Refer to
+ https://issues.apache.org/jira/browse/CAY-1665 for the mapping between old and new names.
+
+ If you are upgrading from an earlier 3.1 release, update your code and runtime parameters accordingly.
+
+---
+
+## Upgrading to 3.1.M3
+
+* DataMap listeners are no longer supported. Use global listeners registered through the annotations API
+ instead:
+ ```java
+ public class SomeListener {
+ @PrePersist
+ public void onPrePersist(Object object) {
+ // callback method
+ }
+ }
+ ```
+ To register a listener:
+ ```java
+ runtime.getChannel().getEntityResolver().getCallbackRegistry().addListener(listenerInstance);
+ ```
+ Note that DataMap listener entries from old `*.map.xml` files will be ignored.
+
+---
+
+## Upgrading to 3.1.M1
+
+The most essential change in Cayenne 3.1 is a new Dependency-Injection (DI) based bootstrap and
+configuration mechanism, which is not backwards compatible with 3.0. Read on for specific areas
+requiring attention.
+
+* **Upgrading 3.0.x mapping files:** Open each project in the new CayenneModeler and agree to upgrade.
+ Note that Cayenne 3.1 supports only one DataDomain per project — if multiple domains existed, you'll
+ end up with multiple project files after the upgrade, each requiring a separate `ServerRuntime`.
+
+* **Upgrading 2.0.x and earlier mapping files:** CayenneModeler 3.1 cannot upgrade projects created
+ with a Modeler older than 3.0. Upgrade in two steps: download Cayenne 3.0 and upgrade there first,
+ then upgrade from 3.0 to 3.1.
+
+* **Cayenne runtime bootstrap:** All classes under `org.apache.cayenne.conf` were removed, superseded
+ by DI-based configuration under `org.apache.cayenne.configuration` and its subpackages. To instantiate
+ the Cayenne stack:
+ ```java
+ ServerRuntime cayenneRuntime = new ServerRuntime("cayenne-UntitledDomain.xml");
+ ```
+ To obtain a new `ObjectContext`:
+ ```java
+ ObjectContext context = cayenneRuntime.getContext();
+ ```
+
+* **No static configuration singleton:** The `Configuration.sharedConfiguration` singleton was removed.
+ Users must decide where to store their `ServerRuntime` instance — e.g., as a `ServletContext` attribute
+ (see `org.apache.cayenne.configuration.web.CayenneFilter` and `WebUtil`), inside a DI container like
+ Spring, or in a static singleton variable.
+
+* **No static DataContext creation methods:** Methods like `DataContext.createDataContext()` relied on
+ the removed static singleton. Use `ServerRuntime` instance methods to create contexts.
+
+* **Webapp configuration changes:** `org.apache.cayenne.conf.WebApplicationContextFilter` was replaced
+ by `org.apache.cayenne.configuration.web.CayenneFilter`. See its javadocs for init parameters.
+
+* **ROP Server configuration changes:** `org.apache.cayenne.remote.hessian.service.HessianServlet` was
+ replaced by `org.apache.cayenne.configuration.rop.server.ROPHessianServlet`. See its javadocs for
+ init parameters.
+
+* **ROP Client configuration changes:** There is now a DI "runtime" object —
+ `org.apache.cayenne.configuration.rop.client.ClientRuntime` — so client connection and channel can
+ be managed via DI with connection parameters specified as properties:
+ ```java
+ Map<String, String> properties = new HashMap<String, String>();
+ properties.put(ClientModule.ROP_SERVICE_URL, "http://localhost:8080/tutorial/cayenne-service");
+ properties.put(ClientModule.ROP_SERVICE_USER_NAME, "cayenne-user");
+ properties.put(ClientModule.ROP_SERVICE_PASSWORD, "secret");
+
+ ClientRuntime runtime = new ClientRuntime(properties);
+ ObjectContext context = runtime.getContext();
+ ```
+
+* **Deprecated API removal:** All API deprecated as of 3.0 is removed. If custom class generation
+ templates are used, check that they do not reference removed `EntityUtil` methods — these were replaced
+ by variables placed directly into the Velocity context.
+
+* **Custom DbAdapter / DbAdapterFactory:** The auto-detection interface changed from
+ `org.apache.cayenne.dba.DbAdapterFactory` to `org.apache.cayenne.configuration.DbAdapterDetector`.
+ Custom implementations can now rely on Cayenne DI for dependencies via `@Inject`. To register:
+ ```java
+ public void configure(Binder binder) {
+ binder.bindList(DbAdapterFactory.class).add(new MyDbAdapterDetector());
+ }
+ ```
+
+* **Custom DataSourceFactory:** The interface changed from `org.apache.cayenne.conf.DataSourceFactory`
+ to `org.apache.cayenne.configuration.DataSourceFactory`. Custom implementations can use `@Inject`
+ for Cayenne dependencies.
+
+* **JNDI preferences hack replaced with runtime properties:** The "JNDI hack" (reading JNDI connection
+ info from Modeler preferences) is no longer available. Instead, any `DataSourceFactory` (including
+ JNDI) can be overridden via runtime properties. See
+ `org.apache.cayenne.configuration.server.PropertyDataSourceFactory` javadocs. Examples:
+ ```
+ -Dcayenne.jdbc.url=jdbc://urloverride
+ -Dcayenne.jdbc.driver=com.example.MyDriver
+ -Dcayenne.jdbc.username=foo
+ -Dcayenne.jdbc.password=bar
+ ```
+
+---
+
+## Upgrading to 3.0.B1
+
+* Per CAY-1281 the `pre-persist` callback was renamed to `post-add` (while `pre-persist` now has a
+ different meaning). Open the project in the Modeler and agree to the automated upgrade.
+
+---
+
+## Upgrading to 3.0.M6
+
+* Per CAY-1154 `org.apache.cayenne.access.reveng` was renamed to `org.apache.cayenne.map.naming`. If
+ you use custom naming strategies, update accordingly.
+
+* Per CAY-1161 The custom columns feature in `SelectQuery` was deprecated. Consider switching to EJBQL.
+ Custom column support will likely go away completely after 3.0.M6.
+
+* Per CAY-1175 The `columnNameCapitalization` property of `SQLTemplate` now takes an enum, not a
+ `String` — fix the calling code.
+
+---
+
+## Upgrading to 3.0.M5
+
+* Per CAY-1127 Query "name" is no longer used as an internal cache key. This change is transparent to
+ most users, but if your code explicitly depends on the cache key value, update it:
+ ```java
+ String cacheKey = query.getQueryMetadata(entityResolver).getCacheKey();
+ ```
+
+---
+
+## Upgrading to 3.0.M4
+
+* Per CAY-1049 API of internal classes that participate in `SelectQuery` translation has changed in a
+ backwards-incompatible way. This should not affect regular users, but if you implemented a custom
+ `DbAdapter`, check classes that directly or indirectly inherit from `QueryAssembler` and
+ `QueryAssemblerHelper`.
+
+---
+
+## Upgrading to 3.0.M3
+
+* Java 5 is now required as a minimum for CayenneModeler and the Cayenne libraries.
+
+* After the move to Java 5, generics have been implemented in many Cayenne APIs. If you don't use
+ generics this should not affect you, but if you do you will need to review any new compiler errors
+ or warnings. Generics only affect compile time — the runtime behaviour is unchanged.
+
+---
+
+## Upgrading to 3.0.M2
+
+* Per CAY-843 Lifecycle callback functionality is now built into `DataContext` and `DataDomain` — all
+ custom setup code is no longer needed. As a result of this change `org.apache.cayenne.intercept`
+ package was removed. See http://cayenne.apache.org/doc/lifecycle-callbacks.html for details.
+
+---
+
+## Upgrading to 3.0.M1
+
+* **Jar files:**
+ - All jar files now include version numbers in their names.
+ - `cayenne-nodeps.jar` is renamed to `cayenne-server-x.x.x.jar`.
+ - The "fat" `cayenne.jar` (which included all dependencies) is no longer distributed. Use the new
+ `cayenne-server-x.x.x.jar` plus the separate dependency jars under `cayenne-x.x.x/lib/third-party/`.
+ - A new `cayenne-agent-x.x.x.jar` is included for class enhancement with POJOs and JPA. Classic
+ Cayenne users can ignore it.
+
+* Ant class generator now uses what was called "version 1.2" by default. If you were using custom
+ Velocity templates in 1.1 mode, either change the templates or specify `version="1.1"` in the
+ buildfile.
+
+* Cross-platform Modeler startup is now done without a batch file or shell script. Run the included
+ `CayenneModeler.jar` directly:
+ - Double-click (on platforms that support it), or
+ - `java -jar CayenneModeler.jar`
+
+* FireBird adapter is no longer distributed with Cayenne.
+
+* `DataContextTransactionEventListener`, `DataObjectTransactionEventListener` and `DataContextEvent`
+ were deprecated in favor of callbacks. **This API will be removed in following 3.0 milestones.**
+
+* Long PK: Cayenne now supports `long` primary key generation (previously only `int`). You may
+ optionally change the PK lookup table to accommodate large IDs. On MySQL:
+ ```sql
+ ALTER TABLE AUTO_PK_SUPPORT CHANGE COLUMN NEXT_ID NEXT_ID BIGINT NOT NULL;
+ ```
+
+---
+
+## Upgrading to 2.0.x
+
+Since 2.0, Cayenne is an Apache project and all `org.objectstyle.*` packages were renamed to
+`org.apache.*` analogues. Since the 1.2.x and 2.0.x release lines are fully compatible (differing
+only in package names), upgrading to 2.0.x can be a first step in a safe upgrade to the latest version.
+
+* **Upgrading mapping files:** Open them in the new Modeler — you will see an upgrade dialog. Confirm
+ the upgrade.
+
+* **Upgrading the code:** Replace `org.objectstyle.` with `org.apache.` everywhere in imports and do
+ a clean recompile.
+
+* **Upgrading logging configuration:** If you are using a custom logging configuration file, change all
+ Cayenne loggers from `org.objectstyle` to `org.apache`.
diff --git a/UPGRADE.md b/UPGRADE.md
new file mode 100644
index 000000000..5134e4bcc
--- /dev/null
+++ b/UPGRADE.md
@@ -0,0 +1,121 @@
+# Apache Cayenne Upgrade Guide
+
+> For upgrade notes for Cayenne 4.2 and older, see [UPGRADE-4.2-and-older.md](UPGRADE-4.2-and-older.md).
+
+**IMPORTANT:** Be sure to read all notes for the intermediate releases between your current release
+and the release you are upgrading to.
+
+---
+
+## 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:
+ ```java
+ 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
+ ```
+
+---
+
+## 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):
+ ```java
+ ServerRuntime.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.
+
+* 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`.
+
+* 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.
diff --git a/UPGRADE.txt b/UPGRADE.txt
deleted file mode 100644
index 9630b62fe..000000000
--- a/UPGRADE.txt
+++ /dev/null
@@ -1,719 +0,0 @@
-Apache Cayenne Upgrade Information
-==================================
-
-IMPORTANT: be sure to read all notes for the intermediate releases between your
- current release and the release you are upgrading to.
--------------------------------------------------------------------------------
-
-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,
-so you should 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, e.g.
-`java -jar CayenneModeler.jar path/to/cayenne-project.xml`, or on macOS
-`open CayenneModeler.app --args path/to/cayenne-project.xml`.
-
-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, so you need to update you projects (just open them in the Modeler
-or use cayenne-project-compatibility module)
-
-* Per CAY-2751 there's no more JNDI DataSource provided by Cayenne, nor there's a password encoding capabilities.
-If you need these you should provide you own custom DataSource.
-
-* Per CAY-2752 code generation configuration has minor changes. You need to 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) :
- ServerRuntime.builder(..)
- .addModule(b -> CacheInvalidationModule.extend(b).addHandler(MyHandler.class))
- .build();
-Two things to note here: (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`, so you need to change
-that accordingly in your build scripts
-
-* Per CAY-2823 `ServerRuntime` is deprecated. You should change your code to use `org.apache.cayenne.runtime.CayenneRuntime` instead.
-
-* Per CAY-2824 `CayenneServerModuleProvider` renamed to `CayenneRuntimeModuleProvider` and moved to `org.apache.cayenne.runtime` package.
-If you are using auto-loading mechanism for your custom modules you need to change `META-INF.services` reference accordingly.
-
-* Per CAY-2825 package `org.apache.cayenne.configuration.server` renamed to `org.apache.cayenne.configuration.runtime`,
-fix your imports accordingly.
-
-* Per CAY-2826 `ServerModule` renamed to `CoreModule`
-
-* Per CAY-2828 `server` prefix removed from the names of runtime properties and named collections defined in `org.apache.cayenne.configuration.Constants`.
-You should change references in code, and in any scripts that could 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 . You should regenerate model classes via cgen tool in Cayenne Modeler or Maven/Gradle plugins.
-
-UPGRADING TO 4.2.M2
-
-* Per CAY-2659 All batch translators (`InsertBatchTranslator`, `UpdateBatchTranslator`, etc.) are updated to the new SQLBuilder utility.
-If you are using customized versions of these classes you should either update them accordingly, or you could keep using
-old versions witch are moved to the `org.apache.cayenne.access.translator.batch.legacy` package.
-
-UPGRADING TO 4.2.M1
-
-* Per CAY-2520 ObjectId can't be instantiated directly, ObjectId.of(..) methods should be used.
- E.g. ObjectId.of("Artist", 1) instead of new ObjectId("Artist", 1).
-
-* Per CAY-2523 SelectQuery was deprecated. Use ObjectSelect instead.
-
-* Per CAY-2525 OpenBase adapter was deprecated.
-
-* Per CAY-2467 Property class is replaced with a type-aware Property API, it's mostly backwards compatible.
- To take advantage of this new API you should regenerate code via Modeler ("Tools" -> "Generate Classes") or cgen tools.
-
-* Per CAY-2563 SQLSelect.scalarQuery(Class<T>, String) and SQLSelect.scalarQuery(Class<T>, String, String) methods
- were deprecated.
-
-* Per CAY-2585 SQLSelect.scalarQuery(String sql), SQLSelect.scalarQuery(String sql, String dataMapName),
- SQLSelect.scalarQuery(String sql, Class<?> firstType, Class<?>... types),
- SQLSelect.scalarQuery(String sql, String dataMapName, Class<?> firstType, Class<?>... types) and
- SQLSelect.params(String name, Object value) were deprecated.
-
-UPGRADING TO 4.1.M3
-
-* Per CAY-2514 SERVER_CONTEXTS_SYNC_PROPERTY default value was set to false.
-
-UPGRADING TO 4.1.M2
-
-* Per CAY-2438 DataChannelFilter filter was deprecated and two new independent filters are introduced:
- DataChannelSyncFilter and DataChannelQueryFilter.
-
-* Per CAY-2400 Cayenne-DBCP2 integration was deprecated
-
-* Per CAY-2377 All code deprecated in Cayenne 4.0 was removed, please review your code before upgrading.
-
-* Per CAY-2372 three new modules extracted from Cayenne core. No changes to the packages or api have been made,
- so only include additional modules to your project if you use them.
-
- - cayenne-web module contains all logic related to bootstrapping Cayenne inside a servlet container.
- WebModule is autoloaded, so you shouldn't add it to runtime explicitly any more.
- - cayenne-osgi module contains OSGi related functionality.
- - cayenne-rop-server ROP server part.
-
-UPGRADING TO 4.1.M1
-
-* Per CAY-2351 Minimum supported Java version is now Java 8. There is no options to use Cayenne 4.1 with earlier
- versions, you should use 4.0 version if Java 7 is required by your project.
-
-* Per CAY-2345 Velocity replaced with Cayenne own template engine by default in cayenne-server,
- this should be transparent in almost all cases, however if you relied on advanced Velocity
- features in SQLTemplate you can include auto-loaded cayenne-velocity module and keep using Velocity,
- no other actions required.
-
-* Per CAY-2335 ServerRuntime by default will fail to load projects in case of version mismatch.
- You have two options:
- - update project files via opening them in Cayenne Modeler
- - if you are unable to do so you can use new cayenne-project-compatibility module,
- to enable it simply add it as a dependency in Maven (or any other build system you use), however
- this module can support only versions created by Cayenne 3.1 or later.
-
-* Per CAY-2330 Field-based data objects are introduced and enabled by default.
- Your existing code will continue to work, but in order to get benefits from this feature you should
- regenerate code via Modeler ("Tools" -> "Generate Classes") or cgen tools in Maven/Ant/Gradle plugins.
- Also note that serialization format of old data objects have changed, make sure you don't use serialization
- form to store your objects.
-
-UPGRADING TO 4.0.B1
-
-* Per CAY-2302 postcommit module and all it's internals renamed to commitlog.
- Most important change is the new @CommitLog annotation which should be used instead of @Auditable,
- this change is backward incompatible and most likely for you to miss as IDE won't give you a hint.
- Please keep in mind that new @CommitLog annotation is used only by commitlog module.
- Deprecated functionality in lifecycle module still depends on @Auditable annotation.
-
- Here is list of steps you should do in order to update your code:
- - include cayenne-commitlog module into your project (i.e. add dependency to your pom.xml)
- - remove cayenne-lifecycle (and cayenne-postcommit if you have it) module from your project
- - switch usages of @Auditable to @CommitLog
- - change usages of renamed classes, here is two classes most likely used by your code:
- PostCommitListener -> CommitLogListener
- PostCommitModuleBuilder -> CommitLogModuleExtender
- - fix all imports for renamed packages:
- org.apache.cayenne.lifecycle.postcommit -> org.apache.cayenne.commitlog
- org.apache.cayenne.lifecycle.changemap -> org.apache.cayenne.commitlog.model
- - change CommitLogModuleExtender methods:
- auditableEntitiesOnly() -> commitLogAnnotationEntitiesOnly()
- build() -> module()
-
-* Per CAY-2280 Cayenne migrated from commons-logging to SLF4J.
- Here is options you have to upgrade your project accordingly:
- 1) Migrate your logging to SLF4J. Please see https://www.slf4j.org for documentation about
- inclusion into your project logging backend of you choice.
-
- 2) Other option is to use commons-logging over SLF4J and keep all logging compatible with previous Cayenne versions.
- In order to do so you need:
- - remove commons-logging dependency if you have it
- - add to your project slf4j-jcl dependency
-
- As a part of this change classes CommonsJdbcEventLogger and FormattedCommonsJdbcEventLogger
- were renamed to Slf4jJdbcEventLogger and FormattedSlf4jJdbcEventLogger respectively.
- Internally they are using now org.apache.cayenne.log.JdbcEventLogger interface as a logger name.
-
-* Per CAY-2278 Packages org.apache.cayenne.lifecycle.audit and org.apache.cayenne.lifecycle.changeset where deprecated.
- Please use instead cayenne-commitlog module and its new @CommitLog annotation.
-
- Weighted graph sorter moved to cayenne-server into org.apache.cayenne.ashwood package.
-
- Packages org.apache.cayenne.lifecycle.changemap and org.apache.cayenne.lifecycle.postcommit
- where moved to the new cayenne-commitlog module.
-
- Please change your code accordingly (see also notes above for CAY-2302).
-
-* Per CAY-2277 ClientRuntime created with ClientRuntimeBuilder, direct instantiation of
- ClientRuntime is deprecated. Also whole ClientLocalRuntime class is deprecated, use instead
- ClientRuntimeBuilder.local() method.
-
-* Per CAY-2262 Client modules are now auto-loaded by default to turn off auto-loading use
- ClientRuntimeBuilder.disableModulesAutoLoading() method.
-
- List of client modules:
- - cayenne-client
- - cayenne-client-jetty
- - cayenne-protostuff (it also supports auto-loading by ServerRuntimeBuilder)
-
- Also new modules are extracted from the existing one and should be added to your pom.xml if the corresponding
- functionality is used by your project:
- - cayenne-cache-invalidation (was part of cayenne-lifecycle)
- - cayenne-commitlog (was part of cayenne-lifecycle)
-
-* Per CAY-2259 Cache invalidation module refactored to provide new functionality and better align with
- new module autoloading functionality. Here is list of changes:
- - Package org.apache.cayenne.lifecycle.cache renamed to org.apache.cayenne.cache.invalidation.
- - CacheInvalidationModuleBuilder renamed to CacheInvalidationModuleExtender and its method build()
- renamed to module().
- - InvalidationFunction returns CacheGroupDescriptor instead of simple String with cache group name,
- so you need to change your custom functions accordingly.
-
-* Per CAY-2268 DI methods for binding ordered lists, introduced in 4.0.M3 where changed:
- - method after() replaced by explicit addAfter(), addAllAfter()
- - method before() replaced by insertBefore(), insertAllBefore()
-
-* Per CAY-2258 Injection of List and Map are made type-safe, as a result small incompatibilities are introduced.
- If you are using following methods:
- - bindMap(String bindingName)
- - bindList(String bindingName)
- you should change them to corresponding type-safe versions:
- - bindMap(Class<T> valueType, String bindingName)
- - bindList(Class<T> valueType, String bindingName)
- Also if you are using DI Keys like Key.get(Map.class, "bindingName") or Key.get(List.class, "bindingName")
- you should use new corresponding factory methods Key.mapOf(MapValues.class, "bindingName")
- and Key.listOf(ListValues.class, "bindingName").
- Additionally new API allows you to bind Lists and Maps without using names:
- - binder.bindList(SomeUniqueType.class).add(...);
- - @Inject List<SomeUniqueType> list;
-
-* Per CAY-1873 and CAY-2266 Cache and remote notification configuration was moved from Modeler into
- runtime DI settings. To set custom cache size, you should use custom module like this:
- Module module = binder -> {
- ServerModule.setSnapshotCacheSize(binder, 20000);
- };
- Or you can use cmd line arg: -Dcayenne.DataRowStore.snapshot.size=20000
-
- If you have used remote notifications, you should include one of the following modules into your project:
- - cayenne-jgroups
- - cayenne-jms
- - cayenne-xmpp
- For maven users this can be easily done by adding dependency to pom.xml:
- <dependency>
- <groupId>org.apache.cayenne</groupId>
- <artifactId>cayenne-jgroups</artifactId>
- <version>4.0.M6</version>
- </dependency>
-
- Module will be autoloaded and remote notifications enabled, so only thing you need is to provide configuration.
- Custom DI module should be used for that, e.g. for JGroups:
- Module module = binder -> {
- JGroupsModule.contributeMulticastAddress(binder, MCAST_ADDRESS);
- JGroupsModule.contributeMulticastPort(binder, MCAST_PORT));
- };
-
-
-* Per CAY-2256 Fix for CAY-2146 was reverted, as it appears that we can't reliably deduce whether
- relationship is optional or not. So in case of mandatory relationships in vertical inheritance
- you should perform manual validation before insert by using "prePersist" callback in your
- object (you can create it in the Cayenne Modeler) or by overriding "validateForSave" method.
-
-
-UPGRADING TO 4.0.M5
-
-* Per CAY-2186 DerbyPkGenerator switched from AUTO_PK_TABLE to sequence-based PK generator
- If you relied in anyway on AUTO_PK_TABLE usage in derby, you should change your code.
-
-* Per CAY-2228 Support for multiple cache groups has been removed from caching and query API
- as none of the modern providers supports it. If you relied on this feature you should
- implement it by yourself or change caching provider
-
-* Per CAY-1980 "maven-cayenne-modeler-plugin" renamed to "cayenne-modeler-maven-plugin"
-
-* Per CAY-2225 CacheInvalidationFilter has been changed to support custom invalidation rules,
- in addition to the rule based on @CacheGroups annotation.
- If you have used it previously, you should change its binding to runtime from direct binding in
- a custom module to a module built by CacheInvalidationModuleBuilder.
-
-* Per CAY-2212 cdbimport tool revisited once again, so configuration of Maven plugin should be changed.
- - "maven-cayenne-plugin" is deprecated, please switch to "cayenne-maven-plugin"
- - <reverseEngineering> tag replaced with <dbimport> tag
- - new <dataSource> tag introduced that should enclose all connection properties:
- 1. <driver>
- 2. <url>
- 3. <user>
- 4. <password>
-
- - top level properties moved to <dbimport>:
- 1. <defaultPackage>
- 2. <forceDataMapCatalog>
- 3. <forceDataMapSchema>
- 4. <meaningfulPkTables>
- 5. <namingStrategy>
- 6. <stripFromTableNames>
- 7. <usePrimitives>
-
- - Java 8 java.time.* types are now used by default in cdbimport (and in "Reengineer Database Schema" tool in Modeler)
- This can be controlled by <useJava7Types> property in <dbimport> (or checkbox in Modeler).
-
- - For Ant users: cayenne-tools.jar split into two parts:
- 1. cayenne-ant.jar for Ant tasks
- 2. cayenne-cgen.jar for class generation functionality (required only for cgen task)
-
-
-* Per CAY-2166, Cayenne supports auto-loading of DI modules. There are a few changes worth mentioning:
- - Service override policies. In the previous 4.0 milestones custom modules would override "builder" modules
- (i.e. implicit modules that wrap around various customizations made in response to the builder method calls). It
- seemed logical to reverse this order, and let builder modules override custom modules. As the builder is
- invoked explicitly when the stack assembly is performed, while modules can be written without any knowledge of the
- final stack.
- - Module Renaming and Explicit Loading of Modules. If you see compile errors (class not found for CayenneJodaModule,
- CayenneJava8Module), just remove explicit loading of those modules. They will be auto-loaded if they are on classpath.
- If you explicitly turn off auto-loading, use the new names for these modules: JodaModule and Java8Module.
-
-* Per CAY-2164, creating a ServerRuntimeBuilder is done via a static method on ServerRuntime ("ServerRuntime.builder()").
- The previous style (ServerRuntimeBuilder.builder()) is deprecated and will soon be removed, so you should replace it
- with the new API.
-
-UPGRADING TO 4.0.M4
-
-* Per CAY-2133, LegacyObjectNameGenerator is no longer provided, as it wasn't possible to maintain it in a fully backwards-
- compatible manner. Embrace the new naming scheme, or provide your own ObjectNameGenerator if you absolutely need the
- old names.
-
-* Per CAY-2125 we no longer inject SchemaUpdateStrategy directly. Instead SchemaUpgradeStrategyFactory is injected.
- If you have your own modules with SchemaUpdateStrategy injection, it will be ignored. So please review your
- DI code and update it to use SchemaUpgradeStrategyFactory (or likely its subclass).
-
-* Per CAY-2060 4.0.M4 changes the way queries are stored in the mapping files, so all existing *.map.xml files should be upgraded.
- To do that open each of your existing projects in the new CayenneModeler. Agree to perform an upgrade when asked.
-
- Also EntityResolver.getQuery(String) method is removed. If you relied on it, consider switching to MappedSelect or MappedExec query, or if you absolutely need to get a hold of specific query, use EntityResolver.getQueryDescriptor(String).buildQuery().
-
-* Per CAY-2065 ROPHessianServlet has been discarded in favor of new implementation called ROPServlet,
- so if you were using org.apache.cayenne.configuration.rop.server.ROPHessianServlet in your web.xml configuration,
- you must change it to org.apache.cayenne.rop.ROPServlet
-
-* Per CAY-2118 we stopped a bunch of deprecated keys in cdbimport configuration, and also removed the ability to set
- properties of "reverseEngineering" config object at the top level of configuration. So you will always need
- <reverseEngineering></reverseEngineering> tag in Maven (but not Ant) to setup any DB filtering. Removed top-level
- configuration keys:
-
- 1. catalog
- 2. schema (also schemaName)
- 3. excludeTables
- 4. includeTables
- 5. procedurePattern
- 6. tablePattern
- 7. importProcedures
- 8. meaningfulPk
- 9. overwrite
-
-UPGRADING TO 4.0.M3
-
-* Per CAY-2026 minimal Java version is now 1.7. If you are still need Java 1.6, you can use Cayenne 3.1 or 4.0.M2 until your
- application is able to upgrade.
-
-* We no longer add @Deprecated annotation to generated String property names in entity superclasses.
- Instead String property names inclusion
- became optional, controlled with "createPropertyNames" flag in cgen ("false" by default). Also a similar option
- was added to Advanced Type of CayenneModeler class generation dialog.
- Note if you have references to @Deprecated String properties and you run cgen without "createPropertyNames" flag,
- there will be errors. Reference Jira: CAY-1991
-
-* Per CAY-2008, CAY-2009 we got rid of org.apache.cayenne.conn.PoolManager and associated classes that made up a
- pooling DataSource. A replacement is non-blocking DataSource under org.apache.cayenne.datasource (PoolingDataSource, ManagedPoolingDataSource),
- best assembled using org.apache.cayenne.datasource.DataSourceBuilder.
-
-* Per CAY-2012 API for ObjectSelect and SelectById queries were changed to remove "reset" functionality. Methods like 'where', 'prefetch',
- 'orderBy' that would previously reset the corresponding option state now work as "append". Methods that would previously append to the
- option state were removed as redundant. Please revisit your code if you previously relied on the reset behavior.
-
-* If you are using DBCPDataSourceFactory, you will need to take a few steps to upgrade:
-
- - Per CAY-2025 and CAY-2026, DBCPDataSourceFactory is now based on DBCP2 (which is required under Java 1.7 and newer).
- - Check your DBCP properties file to ensure it uses property names supported by DBCP.
- (In the past Cayenne would require prefixing those properties with 'cayenne.dbcp.'. If you still have that prefix, remove it).
- - To use DBCPDataSourceFactory, you will now have to explicitly include an extra Cayenne module, as it is no longer in cayenne-server.
- E.g. if you are using Maven:
-
- <parent>
- <groupId>org.apache.cayenne</groupId>
- <artifactId>cayenne-dbcp2</artifactId>
- <version>4.0.M3</version>
- </parent>
-
-
-UPGRADING TO 4.0.M2
-
-* Note that 3.2 line of development was renamed to 4.0. So 4.0.M2 is a straight descendant of
- 3.2M1.
-
-* org.apache.cayenne.map.naming.SmartNamingStrategy was replaced with org.apache.cayenne.map.naming.DefaultNameGenerator. If you
- mentioned SmartNamingStrategy explicitly in your Maven or Ant configs, make sure you rename it. Since this was/is the default,
- chances are that you didn't.
-
-* Minimal required JDK version is now 1.6 (both for modeler and runtime). This is a pretty conservative
- requirement, considering that Java 1.6 has been EOL'd by Oracle on Feb 2013.
-
-* Managing listeners in the Modeler is counterproductive and confusing,
- so support for them was removed from the Modeler per CAY-1842. If you have
- any listeners in the model, delete them from XML, and start using annotations,
- and register them in runtime:
-
- runtime.getDataDomain().addListener(myListener);
-
-* Cayenne.objectForSelect(Select) that was present in 3.2M1 was replaced with ObjectContext.selectOne(Select).
-
-* In-memory expression eval (Expression.match/Expression.evaluate) will now return true when matching Persistent
- with ObjectId or Number or String (if those correspond to a given object's ObjectId). Also 2 objects in 2 different
- ObjectContexts will match even if they have differing local changes. Only their ObjectIds are compared.
- See CAY-1860 for details.
-
-* ResultIterator was moved to org.apache.cayenne to make it available on both server and client. When you upgrade
- related iterator code, make sure to check ResultIterator improvements (e.g. it implements Iterable, it is no
- longer limited to DataRows and can fetch objects just as easy, it no longer requires catching checked exceptions).
- Also check ObjectContext.iterate(..) method.
-
-* Transaction management was refactored significantly:
-
- * External transactions are no longer configured in the Modeler. Instead they are provided as a DI property
- defined in Constants.SERVER_EXTERNAL_TX_PROPERTY.
-
- * TransactionDelegate is no longer present. Similar functionality can be achieved by writing a decorator for
- Transaction interface and using a custom TransactionFactory to decorate standard transactions.
-
- * If your code relied on static methods Transaction.externalTransaction() or Transaction.internalTransaction() for
- manual tx management, use constructors of ExternalTransaction and CayenneTransaction classes instead.
-
-* When switching to ServerRuntimeBuilder, users of multi-config projects may erroneously assume it has the same
- behavior as 3.1 ServerRuntime in assigning domain name to the resulting merged project. Which is to use the
- name of the last project config. We are trying to move away from this behavior, so ServerRuntimeBuilder
- will only use config name if there's only one config and no override. Otherwise it will use the override,
- or if not set - "cayenne" as the default name. Reference Jira: CAY-1972
-
-
-
-UPGRADING TO 3.1B1
-
-* In an attempt to better organize DI configuration and ultimately make it easier to understand,
- all properties and DI collection keys were placed in a single Constants interface. The property and key String
- values were changed to follow a single convention. Please refer to https://issues.apache.org/jira/browse/CAY-1665
- for mapping between the old and the new names.
-
- If you are upgrading from the earlier 3.1 releases, please change your code and runtime parameters accordingly.
- 3.0 users may still review the new property names as some of them existed prior to DI.
-
-UPGRADING TO 3.1M3
-
-* DataMap listeners are no longer supported. Global listeners registered through
- annotations API can be used instead. E.g.:
-
- public class SomeListener {
- @PrePersist
- public void onPrePersist(Object object) {
- // callback method
- }
- }
-
- To register listener class use following API:
-
- runtime.getChannel().getEntityResolver().getCallbackRegistry().addListener(listenerInstance);
-
- Note that DataMap listeners entries from old *.map.xml files will be ignored.
-
-
-UPGRADING TO 3.1M1
-
-The most essential change in Cayenne 3.1 is a new Dependency-Injection (DI) based
-bootstrap and configuration mechanism, which is not backwards compatible with 3.0.
-Read on to learn about specific areas that require attention when upgrading your
-application.
-
-* Upgrading 3.0.x mapping files: Open each of your existing projects in the new
- CayenneModeler. Agree to perform an upgrade when asked. Note that Cayenne
- 3.1 only supports one DataDomain per project, so if multiple domains existed in
- the project, you'll end up with multiple project files after the upgrade. Each
- will require instantiation of a separate ServerRuntime in the code.
-
-* Upgrading 2.0.x and earlier mappings files: Note that CayenneModeler
- 3.1 won't be able to upgrade projects created with a Modeler older than 3.0. To
- upgrade older projects do it in two steps - download Cayenne 3.0, and perform an
- upgrade with 3.0 CayenneModeler. After that perform a second upgrade from 3.0 to
- 3.1.
-
-* Cayenne runtime bootstrap: In 3.1 all classes under "org.apache.cayenne.conf"
- package were removed, superseded by dependency injection (DI) based configuration,
- with main classes located under "org.apache.cayenne.configuration" and its
- subpackages. E.g. to instantiate the Cayenne stack in 3.1 you would do
- something like that:
-
- ServerRuntime cayenneRuntime = new ServerRuntime("cayenne-UntitledDomain.xml");
-
- To obtain a new ObjectContext, the following API is used:
-
- ObjectContext context = cayenneRuntime.getContext();
-
-* No static configuration singleton: Cayenne 3.1 completely gets rid of a (previously
- optional, but widely used) "Configuration.sharedConfiguration" singleton. This
- change was done to acknowledge the fact that single configuration per application
- is just a special case, and generally user can instantiate as many configurations
- (or ServerRuntime's in 3.1 terms) as appropriate. This however means that the
- users must now decide themselves where in their application it is appropriate to
- store ServerRuntime instance (or instances). E.g. it can be stored as an attribute
- of ServletContext (check out "org.apache.cayenne.configuration.web.CayenneFilter" and
- "org.apache.cayenne.configuration.web.WebUtil"), reside in a user's favorite dependency
- injection container (e.g. Spring), or even be saved in a user's own static singleton
- variable.
-
-* No static DataContext creation methods: Methods like DataContext.createDataContext()
- were relying on static configuration singleton, which was removed (see above). Use
- ServerRuntime instance methods to create context instances.
-
-* Webapp configuration changes: "org.apache.cayenne.conf.WebApplicationContextFilter"
- was replaced by "org.apache.cayenne.configuration.web.CayenneFilter". See CayenneFilter
- javadocs for details on of the init parameters.
-
-* ROP Server configuration changes: "org.apache.cayenne.remote.hessian.service.HessianServlet"
- was replaced by "org.apache.cayenne.configuration.rop.server.ROPHessianServlet". See
- ROPHessianServlet javadocs for details on its init parameters.
-
-* ROP Client configuration changes: There is now a special DI "runtime" object -
- "org.apache.cayenne.configuration.rop.client.ClientRuntime", so client connection
- and channel can be (optionally) managed via DI, with connection parameters
- specified as properties. E.g.:
-
- Map<String, String> properties = new HashMap<String, String>();
- properties.put(ClientModule.ROP_SERVICE_URL, "http://localhost:8080/tutorial/cayenne-service");
- properties.put(ClientModule.ROP_SERVICE_USER_NAME, "cayenne-user");
- properties.put(ClientModule.ROP_SERVICE_PASSWORD, "secret");
-
- ClientRuntime runtime = new ClientRuntime(properties);
- ObjectContext context = runtime.getContext();
-
- The advantage of this approach in that all the client stack objects are managed
- by the DI container and a user can customize/override various pieces.
-
-* Deprecated API removal: All API deprecated as of 3.0 is removed. This may require
- some code cleanup. Since 3.0 javadocs for suggested replacements. Also if custom
- class generation templates are used, doublecheck that they do not reference removed
- EntityUtil methods, which were replaced by variables placed directly into Velocity context.
-
-* Custom DbAdapter / DbAdapterFactory: The interface used by Cayenne to allow custom
- DbAdapters to be auto-detected with AutoAdapter has changed from
- org.apache.cayenne.dba.DbAdapterFactory to org.apache.cayenne.configuration.DbAdapterDetector.
- Note that now a custom implementation can rely on Cayenne DI to obtain Cayenne
- dependencies via @Inject annotation. To register a custom implementation with
- Cayenne DI container, one might do this in the custom DI module:
-
- ...
- public void configure(Binder binder) {
- ...
- binder.bindList(DbAdapterFactory.class).add(new MyDbAdapterDetector());
- }
-
-* Custom DataSourceFactory: The interface used by Cayenne to load custom DataSource
- factories has changed from "org.apache.cayenne.conf.DataSourceFactory" to
- "org.apache.cayenne.configuration.DataSourceFactory". This new interface must be
- implemented by the custom factories. Note that now a custom implementation can
- rely on Cayenne DI to obtain Cayenne dependencies via @Inject annotation.
-
-* Replaced JNDI preferences hack with runtime properties: "JNDI hack", as it was
- known prior to 3.1, allowed to define a named database connection using CayenneModeler,
- and then Cayenne would read this connection information from Modeler preferences
- and use it as a failover for JNDI DataNodes. The problem with this is that it
- required CayenneModeler and HSQLDB jars on the application classpath, and also that the
- preferences database was prone to data corruption. In 3.1, preferences hack is no
- longer available. Instead JNDI (or really any other type of DataSourceFactory)
- can be overridden via runtime properties (or by redefining DataSourceFactoryLoader
- via DI). See org.apache.cayenne.configuration.server.PropertyDataSourceFactory javadocs for
- details. Here are some simple examples:
-
- -Dcayenne.jdbc.url=jdbc://urloverride
- -Dcayenne.jdbc.driver=com.example.MyDriver
- -Dcayenne.jdbc.username=foo
- -Dcayenne.jdbc.password=bar
-
-
-UPGRADING TO 3.0B1
-
-* Per CAY-1281 pre-persist callback was renamed to post-add (while pre-persist now has a different meaning).
- To upgrade your project, open it in the Modeler and agree to perform an automated upgrade.
-
-UPGRADING TO 3.0M6
-
-* Per CAY-1154, org.apache.cayenne.access.reveng package was renamed to org.apache.cayenne.map.naming. So, if you
- use your own naming strategies, you should update as well.
-
-* Per CAY-1161, custom columns feature in SelectQuery was deprecated. Consider switching to EJBQL as an alternative.
- Custom columns support will likely go away completely after 3.0M6.
-
-* Per CAY-1175, 'columnNameCapitalization' property of SQLTemplate now takes an enum, not a String.
- Calling code should be fixed.
-
-UPGRADING TO 3.0M5
-
-* Per CAY-1127, query "name" property is no longer used as an internal cache key. This change should be transparent
- to most users, as Cayenne generates a correct cache key internally when needed, however if a user code explicitly
- depended on the value of the cache key, it should be updated to use something like this:
-
- String cacheKey = query.getQueryMetadata(entityResolver).getCacheKey();
-
-UPGRADING TO 3.0M4
-
-* Per CAY-1049 API of the internal classes that participate in SelectQuery translation has changed in a way that
- is not backwards compatible. This should not affect regular users, however if you implemented a custom DbAdapter,
- check for classes that directly or indirectly inherit from QueryAssembler and QueryAssemblerHelper and fix them
- if needed.
-
-UPGRADING TO 3.0M3
-
-* Java 5 is now required as a minimum for Cayenne Modeler and the Cayenne libraries.
-
-* After the move to Java 5, generics have been implemented in many of the Cayenne APIs. If you don't use generics
-in your project this should not affect you, but if you do you will need to review any new compiler errors or warnings.
-The effect of generics is at compile time only, so their introduction will not change the runtime behaviour of
-your application once compiled.
-
-UPGRADING TO 3.0M2
-
-* Lifecycle Callbacks require no setup:
- Per CAY-843, lifecycle callback functionality is now built into DataContext and DataDomain,
- so all the custom code to set them up is no longer needed. Also as a result of this change
- 'org.apache.cayenne.intercept' package is removed from Cayenne.
- Further information can be found here: http://cayenne.apache.org/doc/lifecycle-callbacks.html
-
-UPGRADING TO 3.0M1
-
-* Jar files:
- - all jar files now include version numbers in their names.
- - "cayenne-nodeps.jar" is renamed to "cayenne-server-x.x.x.jar"
- - "fat" cayenne.jar file that included dependencies is no longer distributed.
- All dependencies that it contained are included as separate jars under
- "cayenne-x.x.x/lib/third-party/". The new "cayenne-server-x.x.x.jar" plus
- dependencies should be used in place of cayenne.jar.
- - A new "cayenne-agent-x.x.x.jar" is included. It is used for class enhancement
- with POJO's and JPA. "Classic" Cayenne users can ignore this file.
-
-* Ant class generator is using what was called "version 1.2" by default. This means that if you were
- using custom Velocity templates in 1.1 mode, you should either change the templates or specify 'version="1.1"'
- in the buildfile explicitly.
-
-* Cross-platform Modeler Startup is now done without a batch file or a shell script.
- A "fat" CayenneModeler.jar is included in the "cayenne-x.x.x/bin" directory
- and can be run either by double-clicking the jar (on platforms that support that)
- or by running "java -jar CayenneModeler.jar".
-
-* Note that FireBird adapter is no longer distributed with Cayenne. The one we had was half-working
- and we could not support it anymore.
-
-* DataContextTransactionEventListener, DataObjectTransactionEventListener, DataContextEvent all were deprecated
- favor of callbacks. NOTE THAT THIS API WILL BE REMOVED IN THE FOLLOWING 3.0 MILESTONES.
-
-* Long PK: Cayenne now supports "long" primary key generation (previously it only supported "int"). You may
- have to change the existing PK lookup tables on some databases to take advantage of that (this is optional,
- and is needed if you expect your PK to exceed maximum value of an "int" allowed in your database). E.g. on
- MySQL you may run the following SQL:
-
- ALTER TABLE AUTO_PK_SUPPORT CHANGE COLUMN NEXT_ID NEXT_ID BIGINT NOT NULL;
-
-
-UPGRADING TO 2.0.x
-
-Since 2.0, Cayenne is an Apache project, so all "org.objectstyle.*" java packages
-were renamed to "org.apache.*" analogues. Since 1.2.x and 2.0.x release lines maintain
-full compatibility with each other, differing only in package names, upgrading to 2.0.x
-can be a first step in a safe upgrade to the latest version of Cayenne.
-
-* Upgrading mapping files:
-
-To upgrade the mapping files, open them in the new Modeler. You should see an upgrade
-dialog. Once you confirm the upgrade
-
-* Upgrading the code:
-
-Replace "org.objectstyle." with "org.apache." everywhere in imports and do a clean
-recompile.
-
-* Upgrading logging configuration
-
-If you are using custom logging configuration file, make sure that all the
-Cayenne loggers are changed from "org.objectstyle" to "org.apache".