Title: Upgrade

General Upgrade Recommendations

Consult UPGRADE.txt and RELEASE-NOTES.txt files in the release you just downloaded for the most up to date instructions.

(Optional) Delete CayenneModeler preferences. This is not strictly required, but recommended (especially if you used intermediate milestones and Betas). To do that delete "$HOME/.cayenne/modeler.preferences" file and "$HOME/.cayenne/prefs" directory, where $HOME is a user home directory which is OS and machine specific.

Upgrade Cayenne Mapping Projects. Open your project with the version of the Modeler that came with the latest download. If an upgrade dialog pops up, select "yes" to do an upgrade. Also it is also a good idea to make some insignificant change to the model (so that a "Save" button is activated) and do a save.

Upgrading project XML files can make them unusable with earlier versions of Cayenne.

Pay attention to CayenneModeler validation warnings.

Do a clean recomplie. Recompile all your code, to make sure that you are not using any old classes or methods. Pay attention to deprecation warnings. It is always a good idea to update your code to avoid deprecated API.

Upgrading to 3.0

If you are still using ObjectStyle.org releases of Cayenne, read "Upgrading to 2.0" for the information on how to change the package names.

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.

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

FireBird adapter is no longer distributed with Cayenne. The one we had was half-working
and we could not support it anymore.

DerivedDbEntities are removed from Cayenne.

DVModeler and DataViews are no longer shipped with Cayenne. See http://cwiki.apache.org/CAYDV/ for more details.

DataContextTransactionEventListener, DataObjectTransactionEventListener, DataContextEvent are removed.

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

2.0 is a mirror of 1.2 (third digit in release number is a patch level that matches 1.2 version, e.g. "2.0.1" has the same patch level as "1.2.1"). The main change is that all packages were renamed from "org.objectstyle.cayenne*" to "org.apache.cayenne.*". This affects user API and also mapping XML files (as they sometimes reference Cayenne classes by name).

First you need to upgrade the mapping files as described in general upgrade instructions above.

Upgrading the code: Replace "org.objectstyle.cayenne" with "org.apache.cayenne" 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.cayene" to "org.apache.cayenne".

Upgrading to 1.2

This is the list of things that are different in 1.2 and may require attention when doing an upgrade:

Cayenne tools and runtime now REQUIRE at least JDK 1.4 (or higher). They won't work on JDK 1.3. If you are still on 1.3, upgrade your JDK if you can. If you can not, consider staying on Cayenne 1.1.

1.2 no longer needs Jakarta BeanUtils.

1.2 no longer relies on ClassLoader provided by Configuration (this API is deprecated as a matter of fact). Current code uses Thread.currentThread().getContextClassLoader().

In 1.2 PostgreSQLAdapter uses DB sequences for primary key generation instead of AUTO_PK_TABLE. To port an existing application, you will need to create those sequences (e.g. using the Modeler) and assign correct current values to them (e.g. taken from the old AUTO_PK_TABLE). After that AUTO_PK_TABLE can be dropped.

In 1.2 PostgreSQLAdapter's default "BLOB" mapping is changed from "bytea" to "oid". It is still possible to use bytea, but watch for the Modeler-generated schema scripts - they will contain "oid". The easiest way to migrate your mapping (if you don't want to change the DB) is to remap all bytea columns as LONGVARBINARY DbAttributes instead of BLOB.

For extra portability encoding of entity type in the ObjectId is now based on ObjEntity name, not Java class as before. If you had ObjEntities with matching names but different class names in different DataMaps, you will need to ensure entity name uniqueness.

ObjectId methods "getObjClass" and "getObjectClass" are removed (it wasn't possible to deprecate them and still preserve meaningful functionality). Constructors that take Class as the first argument are deprecated and will only work if entity naming follows CayenneModeler default conventions of using unqualified class name as the entity name.

TempObjectId is deprecated and is no longer used by Cayenne internally. If you were referencing TempObjectId explicitly in your code (e.g. if(id instanceof TempObjectId) ... ), you will need to modify the code and use "isTemporary()" superclass method.

The meaning of SnapshotEvent "source" and "postedBy" attributes is reversed per CAY-395 for better efficiency. If you implemented custom listeners of SnapshotEvents, you may need to doublecheck their logic. From now on events use DataRowStore as source, and EventBridge or ObjectStore as postedBy, depending on whether this was a local or a remote event. I.e. the new structure is the opposite to what we used in 1.1.

Cayenne stack events are no longer sent via a shared "default" EventManager. If you were using EventManager.getDefaultManager() to communicate or receive Cayenne stack events, you'll have to switch to Configuration.getEventManager(). Otherwise default manager can be accessed as before.

Query.setLoggingLevel/getLoggingLevel methods are removed from the interface and AbstractQuery implementor. As multi-tier Cayenne doesn't use Log4J, it was no longer possible to keep these methods deprecated.

Thread-bound Transactions: QueryEngine.performQueries(Collection,OperationObserver resultConsumer,Transaction) is deprecated and no longer used internally to further decouple layers in the access stack. This DOES NOT AFFECT most users. Only if you (a) implemented custom transactions and (b) manually manage their commit/rollback, you will also have to bind and unbind such Transactions to the current thread manually, for Cayenne stack classes to pick them up.

To force refresh of cached query results, one of the two new cache policies should be used instead of "setRefreshingObjects(..)" ("setRefreshingObjects" should only be used for its original purpose - refreshing individual objects, not list contents). See Caching Query Results for details.

ObjectStore no longer stores database snapshots of object. As a result a method "retainSnapshot(DataObject object)" is removed, as its meaningful deprecation is not possible.