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 <[email protected]>
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".
