Cayenne User Documentation
Guide to 3.1 Features

This page highlights the new features and changes introduced in 3.1 release. It is a high-level overview and as such is by no means complete. Consult RELEASE-NOTES.txt file included in each release for the full list of changes, and UPGRADE.txt for the upgrade instructions.

- Distribution Contents Structure
- Cayenne Configuration
- Framework API
- CayenneModeler

## Distribution Contents Structure

Cayenne distribution is made leaner and more modular:

- `"cayenne-modeler.jar"` is no longer included in the "lib" folder, as it is no longer used for loading local JNDI overrides. Of course "CayenneModeler-the-app" is still included.
- Ashwood library used for commit operation sorting is no longer a third-party dependency. Instead a small subset of the relevant Ashwood classes got included in Cayenne core.
- The following helper modules are split away from Cayenne core: `"cayenne-project"` and `"cayenne-wocompat"`. They are bundled in CayenneModeler, and are available from the source distribution. They are not included as standalone jars in the binary distribution.

## Cayenne Configuration

| The new DI-based bootstrap and configuration approach is not API-compatible with earlier versions of Cayenne. Make sure you read the UPGRADE.txt file for instructions how to upgrade the existing projects.

### Dependency Injection Container

Cayenne 3.1 runtime stack is built around the ideas of Dependency Injection (DI), making it extremely flexible and easy to extend. It bundles a small, flexible annotations-based DI to configure its services. The idea behind Cayenne DI is to provide DI services and extension points to Cayenne, but do not interfere with other DI containers that may be present in the application. I.e. it is invisible to the users who do not care about advanced Cayenne customization.

### Bootstrapping Cayenne in Various Environments

TODO... For now read the UPGRADE.txt file and check the tutorials source code for bootstrap examples. Here is a simple example of starting a server-side Cayenne stack:

    ServerRuntime runtime = new ServerRuntime("cayenne-UntitledDomain.xml");

### Configuring Local DataSources, Removal of JNDI Hack

Cayenne 3.1 provides a property-based mechanism to override Modeler DataSource definitions, regardless of whether they are driver configurations, JNDI, DBCP, etc. A quick configuration example is shown below:

    -Dcayenne.jdbc.driver=com.mysql.jdbc.Driver -Dcayenne.jdbc.url=jdbc:mysql://localhost/mydb \
    -Dcayenne.jdbc.username=user -Dcayenne.jdbc.password=password

For more details and configuration options see javadocs of `org.apache.cayenne.configuration.server.PropertyDataSourceFactory`.

This feature supersedes what was formerly known as "JNDI hack", i.e. JNDI DataSource failover load strategy based on CayenneModeler preferences database. The problem with JNDI hack was unstable and frequently corrupted preferences database, and the need to include hsqldb and cayenne-modeler jars in the runtime.

## Framework API

TODO... See UPGRADE.txt for the list of changes

## CayenneModeler

### Java Preferences API

We got rid of HSQLDB-based preferences storage, and are using standard Java Preferences API for the Modeler preferences. This solved a long-standing stability issue with Modeler preferences. So no more lost user preferences.

.
Copyright ©2001-2010 Apache Software Foundation