Title: Guide to 3.0 Features

This page highlights the new features and changes introduced in 3.0 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

Object Relational Mapping

Killed DerivedDbEntity Concept

Stopped supporting DerivedDbEntity - its functionality (aggregate queries) is achieved via EJBQL and other means.

DataMap DTD Replaced with Schema

A schema is now available here for the DataMap XML format.

Embeddables

Added a new mapping artifact - Embeddable, that allows to map composite objects to a single table.

Flattened Attributes

Just like with "flattened" relationships, now there is a way to map an ObjAttribute that spans one or more DbRelationships and is mapped to a column of a joined table. An important use of flattened attributes is vertical inheritance mapping, as described below.

Vertical Inheritance

Adding flattened attributes to subclasses in a single-table mapping gives us another powerful way to map inheritance - "vertical inheritance mapping", described in more details here.

Persisting Primitives and a Number of Other Simple Properties

DataObjects are now allowed to have primitive properties, such as int, boolean, etc. Also 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[].

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

Support for "extended" Enums Mapping

In addition to vanilla Java enums, Cayenne allows enums to provide a custom database value for each enumerated instance by implementing org.apache.cayenne.ExtendedEnumeration. This way a persistent value doesn't have to be tied to the enum Java name or position.

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.

Cayenne Persistence API

Java 5 Required

Cayenne now requires Java 5 or newer to run. This allowed us to start providing generics-based API, enums and other Java 5 features.

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 evolution of the underlying implementation, allows you to customize context behavior by using interface wrappers. There are plans to update all Cayenne API to return ObjectContext everywhere DataContext might be returned.

EJB QL Queries

Never mind the "EJB" in the name. EJBQL queries are a powerful object query mechanism similar to the one supported by the JPA specification. EJBQLQuery is a first-class citizen, just like SelectQuery.

SQLTemplate Query Improvements

SelectQuery Improvements

Entity Lifecycle Callbacks

Cayenne lifecycle callbacks are similar (but not identical) to callbacks defined in the JPA specification. This is a feature that allows to perform custom operations at certain points in the object lifecycle. For more details see this page.

General Query Improvements

DataContext Changes

Implemented DataContext.rollbackChangesLocally(). This was missing in 2.0, limiting the operation of the nested DataContexts.

Cache Management

Expression Improvements

Database Integration Changes/Improvements

Class Generation Improvements

Prefetching Improvements

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.

Nested contexts support for ROP ObjectContext

Nested contexts can now be created for ROP contexts. Creation method is added to ObjectContext interface.

CayenneModeler

Upgrade Warning
Saving projects with CayenneModeler v.3.0 will render them uneditable with earlier versions of the Modeler

The Modeler underwent significant changes with the goal to improve usability and look-and-feel.

Deployment and Runtime

Improved Performance

Improved Memory Management

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");

Optional Quoting of SQL Identifiers

Cayenne now supports optional quoting of SQL identifiers in the generated SQL. This has been a very popular request in the past. Identifier quoting can be turned on per DataMap in the Modeler (look for "Quote SQL Identifiers" checkbox). This will allow to map column names that contain spaces, non-ascii characters, reserved words, etc., i.e. the schemas that could not be mapped with Cayenne before.

Ability to Detect Missing/Partial Schema and Auto Generate Schema in Runtime

DataNode has a new attribute in the Modeler - "Schema Update Strategy". This allows to specify runtime behavior in regards to schema consistency checking. The default behavior is "do nothing" (org.apache.cayenne.access.dbsync.SkipSchemaUpdateStrategy). Alternatively Cayenne can create the schema if none is found or throw an exception if schema inconsistencies are detected.

Tools