Cayenne User Documentation
Guide to 3.0 Features

This page summarizes the new features and changes introduced in 3.0 release, roughly corresponding to the latest released milestone. Consult RELEASE-NOTES.txt file bundled with each release for the full list of changes, fixes and improvements.

## Distribution Contents Structure

- There are a few changes in the contents of the distribution "lib" folder. For details see this page. Main Cayenne JAR is now called `"cayenne-server-x.x.x.jar"`. We no longer ship the "fat" jar with dependencies. Instead dependencies are included in the separate jars in `"lib/third-party"` distribution folder.
- CayenneModeler is located in the "bin" folder. Never mind the `"lib/cayenne-modeler-x.x.x.jar"` - this is just an underlying Modeler library, used in "local JNDI" configuration for instance, not the runnable application.

## Cayenne JPA Provider

(status: preview)

Cayenne 3.0 includes an in-progress partial implementation of a Java Persistence API specification compliant persistence provider, with support for POJO and JPA annotations. Provider can be used in a standalone mode, as well as a part of a J2EE container.

Currently implemented features:

- Provider, EntityManagerFactory, EntityManager API bridge to the current Cayenne stack
- Loading mapping from annotations
- Loading mapping from XML
- Class enhancement
- EJBQL
- Entity callbacks
- All types of relationships and simple properties

## Cayenne Persistence API

Many of the improvements below were done to support the JPA provider, still Cayenne applications can take advantage from all of these things without using JPA.

### ObjectContext

While you can still use DataContext directly, we encourage you to avoid direct dependency on DataContext throughout your code, and instead use `org.apache.cayenne.ObjectContext` interface. E.g.:

    ObjectContext context = DataContext.createDataContext();

This protects your code from the actual implementation evolution, allows you to customize context behavior by using interface wrappers, and would also allow you to use lifecycle callbacks feature (although we may enable callbacks directly on the DataContext at some point). There are plans to update all Cayenne API to return ObjectContext everywhere DataContext might be returned.

### EJB QL Queries

(status: in progress, only selecting queries are supported)

Never mind the "EJB" in the name. EJBQL queries are a powerful object query mechanism borrowed from the JPA specification and added to Cayenne API. EJBQLQuery is a first-class citizen, just like SelectQuery.

### Entity Lifecycle Callbacks

Just like EJBQL, lifecycle callbacks is a JPA-inspired feature that allows to perform custom operations at certain points in the object lifecycle. For more details see this page.

### Cache Management

- pluggable query cache
- a notion of Query cache groups
- automated cache key management for standard queries
- RefreshQuery

### Expression Improvements

- Added missing DB expressions to ExpressionFactory.
- Added support for matching against TRUE and FALSE.

### Database Integration Changes/Improvements

- Added stored procedure support on MySQL.
- Changed default table type on MySQL to InnoDB, added MySQL FK constraints support in the Modeler.
- Turned on update query batching on SQL Server and Derby.

### POJO Persistence

(status: preview)

- Implemented class enhancer to enhance POJO's into org.apache.cayenne.Persistent

### DbAttribute Scale and Precision

Changed DbAttribute "precision" property to "scale" (as it meant scale all along) and added a separate "precision" attribute to track precision.

### Support for Persisting a Number of Extra Simple Property Types

Cayenne can now persist the following extra simple property types: java.util.Calendar, java.math.BigInteger, java.io.Serializable, char[], java.lang.Character, java.lang.Character[], java.lang.Byte[]. (Note that until CAY-826 is fixed, these types do not show up in the Modeler, still users can enter them directly).

### Support for To-Many Relationship Maps and Collections.

In addition to mapping a to-many relationship as a List, Cayenne now supports to-many Maps (keyed by target object pk, or an arbitrary unique property), Sets and generic Collections. Note that relationship maps is the only conceptually new type of relationships. Collection and Set are not that different from the earlier List behavior (that was a Collection, and just like Set ensured uniqueness of its objects).

## Remote Object Persistence

### Validation callbacks support for ROP ObjectContext.

Now object validation works the same way on the ROP client as it did on the server.

## CayenneModeler

- Added ability to specify password encryption mechanism
- Added ability to drag and drop cayenne.xml from the filesystem to the Modeler window to open the project.
- Added support for to-many relationship collections mapping.

## Deployment and Runtime

### Improved Performance

- Paginated query algorithm is changed, resulting in very significant performance improvements on large data sets (this also improves ROP paginated query performance).
- ROP new context creation speed is improved, as EntityResolver is cached on the client after first retrieval.
- Reduced the scope of lock on a shared cache during commit, that should result in improved concurrency.

### Improved Memory Management

- Leak free ObjectContext
- Query lists are cached in an LRU map, so there's no indefinite memory growth when using query caching.

### Logging Switched to commons-logging from Log4J

Cayenne no longer has a Log4J dependency. Instead it uses Jakarta commons-logging, as described here. Note that 2.0 Log4J configurations should continue to work, although now it is a user responsibility to bootstrap Log4J - Cayenne will no longer do it for you. E.g. you can do this on startup:

    org.apache.log4j.PropertyConfigurator.configure("cayenne-log.properties");

.
Copyright ©2001-2007 Apache Software Foundation