Cayenne User Documentation
Guide to 1.1 Features

Cayenne version 1.1 introduces a large number of new features and enhancements over 1.0. This chapter lists most of them, providing the links to more detailed information about each feature.

### DTD Additions.

"cayenne.xml" and "*.map.xml" file formats were updated to support new features. 1.1 DTD files are located here:

- cayenne-project-1_1.dtd
- cayenne-data-map-1_2.dtd
- cayenne-data-view-1_1.dtd
- cayenne-driver-1_1.dtd

| Upgrade Warning Saving projects with CayenneModeler v.1.1 will render them uneditable with CayenneModeler v.1.0.

### Advanced Local and Distributed Caching

Cayenne now provides a way to share its object cache between DataContexts in the same JVM and across JVMs. The following chapters in the user guide describe this feature:

- Object Caching
- Caching Query Results
- Caching Lookup Tables

### Optimistic Locking

ObjAttributes and ObjRelationships can be marked to be used for "optimistic" locking. If an corresponding columns of the underlying database row are externally modified, an attempt to save an object results in OptimisticLockingException.

### DataObjectUtils - an easy way to map objects by PK

DataObjectUtils is an often requested feature for easy retrieval of an object primary key, or locating an object for a known key. It works in a generic way for any type of DataObjects, even if a PK is not a class property.

### Entity Inheritance

Cayenne now supports entity inheritance for entities rooted in the same DB table (single table inheritance).

### Data Views and DVModeler

DataViews is a completely new addition to Cayenne. This is a framework and a Swing modeler tool to quickly build Swing applications based on Cayenne.

### Generic Multithreaded and Distributed Events Mechanism

Cayenne now includes a generic event package "org.objectstyle.cayenne.event" for registering listeners and sending events, both locally and remotely. It supports both blocking and non-blocking listeners and dispatches. Supported remote transports include JMS and JavaGroups.

### DataObjects Validation

DataContext now performs validation of DataObjects before committing them. There is a set of default validation checks being executed, based on the DataMap information. Developers can override DataObject validation methods to provide custom validation checks.

See user guide chapter on object validation.

### Expression API Enhancements

There is a new expression parser that allows creation of complex expressions from strings ("Expression.fromString(..)"). This greatly reduces the amount of code needed to build an expression.

In-memory evaluation API is improved, and now supports both boolean conditions (via "Expression.match" method) and generic expressions evaluation (via "Expression.evaluate" method), it also includes support for arithmetic operations.

- Expressions

### SQLTemplate - A Dynamic Raw SQL Query

SQLTemplate replaces SqlSelectQuery and SqlModifyQuery and is a scriptable parameterized raw SQL query. It supports DataObjects and other features declared in GenericSelectQuery interface.

- SQLTemplate Query
- Scripting SQLTemplate

### DataContext API for Running Parameterized Named Queries

DataContext now provides simple API to run SelectQuery, SQLTemplate and ProcedureQuery by name if such queries are mapped via CayenneModeler:

- DataContext Query API Overview

### Support for Shared Mapping Namespace

DataDomain now provides a shared mapping namespace. This means that all mapping objects can reference other mapping objects outside their DataMaps. For example two DbEntities can be located in different DataMaps and still have relationships to each other.

Temporary limitation of the shared mapping namespace is that Queries stored in the DataMap can't have a "root" from a different DataMap.

### SnapshotEvents

### DataContextDelegate

### Entity Restricting Qualifier

ObjEntities now can hold a qualifier expression that is automatically appended to any query qualifiers, thus creating a global data filter for a given entity. This feature is used for inheritance mapping, however it has nothing to do with inheritance as such and can be used all by itself.

### Explicit Transaction API and Container Managed Transactions

Cayenne now supports container-managed transactions. As a result it can be used inside EJBs out of the box. It also allows a high degree of transactions customization. The following user guide chapter explains Transactions design and behavior in details:

- Understanding Transactions

### Various Performance Enhancements

- Lazy Relationship Creation - when new objects are fetched, their relationships are not initialized immediately; a Fault singleton is used isntead as a placeholder. Of course in the past Cayenne also had "lazy" relationships, meaning that they didn't get resolved via a DB query until accessed. Current optimization goes further - it prevents a number of Java objects (such as empty Lists for to-many relationship, or "hollow" DataObjects for to-ones) from being created until absolutely necessary.
- To-many relationships do not have to be fully resolved on modification - if an unresolved to-many relationship is modified (i.e. an object is added or removed from it), it is not resolved until the next "read" (i.e. until a call to "size()" or "iterator()" method). This is especially helpful with bi-directional one-to-many relationships. E.g. "painting.addToArtist(artist)" used to trigger the fetch of all paintings that belong to an artist. Not anymore.

### More Databases Have Custom DbAdapters

Cayenne features new database adapters:

- OpenBase Adapter
- MS SQL Server Adapter

### Support for To-One Relationships Not Pointing to a PK.

Added support for one-to-one relationships between PK and non-PK columns of related tables. In the past this could only be modeled as one-to-many. CayenneModeler will create UNIQUE constraint for a non-PK columns during schema generation.

### Support for Queries in DataMap DTD.

Queries are made first-class mapping objects. They can be modeled in CayenneModeler and stored in DataMaps. Application code can then reuse such queries.

- Modeling Queries

### Non-refreshing Select Queries

### CayenneModeler Enhancements.

The following is an incomplete list of enhancements: new professional look and feel, preference engine, reenginnering of stored procedures, local DataSources, configurable locations of JDBC drivers, custom class generation templates, etc. A number of Modeler tasks and dialogs have been redesigned and improved to be more user-friendly and consistent.

Also CayenneModeler supports mapping of all the new 1.1 framework features, such as DataMap queries, cache synchronization configuration, etc.

.
Copyright ©2001-2006 Apache Software Foundation