Using and upgrading Apache Cayenne 3.1M2 from trunk

Recently I decided to use the trunk version of Apache Cayenne as dependency to my own project in Eclipse. At the same time I had to upgrade from Cayenne 3.0 to the 3.1 version. With the a little help from the great Cayenne community this was straightforward.

Having Cayenne as a trunk project will give you the chance to debug it better and - if necessary - create a patch against the trunk very easily. Additionally you can use all updates at the time they are coming in. Of course it is not recommended to use a trunk version in production, except you know very well what you are doing. In my case, production deployment is in far future and I want to get into Cayenne.

First I checked out the whole Cayenne trunk from the SVN repos (GIT repo is available too):

svn checkout http://svn.apache.org/repos/asf/cayenne/main/trunk/ cayenne-trunk

Then open eclipse choose your working set and hit “Import existing projects into Workspace” from eclipse. You’ll not need all projects in Eclipse, only:

• cayenne-client
• cayenne-di-unpublished
• cayenne-jdk1.5-unpublished
• cayenne-server

The Apache Cayenne team commits the required Eclipse files to SVN. This is not true for the documentation modules. But you’ll not need it as a Eclipse project so thats OK for now.

If you would like to create mvn eclipse:eclipse - this will fail if you are not doing a mvn install before. And then it will fail at the documentation project at the moment. This is a trivial thing, but I want to let you know. Avoid mvn eclipse:eclipse if possible.

Here we go - you should have everything you’ll need to work with the trunk. I had a few compiler errors. But I think it was because I runned eclipse:eclipse before. It seems Cayenne has a bit of a non-maven-standard build and I damaged something :-) If you have Compiler errors as I have, please look at the pom.xml which dependencies are missing and add them manually to the corresponding project. For example, I had to add JEdit classes for the modeler. Nothing which should happen to you, except you want to build the modeler yourself, like me.

As I have used the 3.0 version before there was some other work to upgrade. The Cayenne developers have changed a bit of code. But you can clean the problems out very easily. Open your project files with your new modeler (be careful: if you don’t build the yourself, you’ll need to download one - and the downloaded could not be compatible with the trunk. At the time of writing, it is). The modeller asks you to upgrade. Choose yes.

You’ll find your old cayenne.xml renamed to cayenne-DomainName.xml. This is one of the bigger changes. The datasource definition has moved (in case of XML definition) to the domain file. A driver file is not longer necessary. Support for JNDI and Apache DBCP is built int. The Schema-Update Strategies have changed their naming. In the modeler you have now an ER diagram which shows your relations. This is a fantastic improvement on modeler side. For sure, Apache Cayenne 3.1M2 looks very promising.

But back to the upgrade. If you are upgrading a web project from 3.0, you probably have a problem: your cayenne.xml is not longer found: a curious file is expected (CayenneFilter.xml probably?). CayenneFilter.xml is the name from the webapp docs of Cayenne. There is a good chance you copied the name to your own filter configuration. But the new Cayenne uses the filter name to look up your configuration file. For example in old world you had:

CayenneFilter
org.apache.cayenne.conf.WebApplicationContextFilter

This will cause the filter to search for CayenneFilter.xml. In new Cayenne you should rename the filter to:

cayenne-YourDomain
org.apache.cayenne.conf.WebApplicationContextFilter

Which will start your webapp with cayenne-YourDomain.xml.

Now you should be able use Cayenne again.