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 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".