Cayenne User Documentation
Guide to 1.2 Features

This page describes new features and other changes introduced in 1.2 release.

## Core Framework

#### Remote Object Persistence

Cayenne Remote Object Persistence is a low-overhead web services-based technology that provides lightweight generic object persistence and data query functionality to 'remote' applications. It allows to use the same object model and the same context capabilities in a system with more than one Java tier. Now persistence features can be implemented consistently across a set of collaborating applications with different responsibilities and security context.

#### ObjectContext API

ObjectContext is a new interface that is a generalization of the traditional DataContext. In fact DataContext is one of its main implementors. Another implementation is `CayenneContext` used on remote clients.

#### Query Enhancements

- Prefetching
  - Cayenne now supports prefetching of flattened relationships.
  - New "joint" prefetch semantics is introduced.
  - Semantics of prefetching now can be customized by users via `PrefetchTreeNode` API.
  - SQLTemplate and ProcedureQuery can be configured to emulate joint prefetching behavior.

- Customizing Queries: In 1.2 Queries can have behavior in addition to storing query parameters. Now queries can route themselves and also handle their own execution at the JDBC level. This opens endless possibilities for custom extensions.

- New Query Types: Customizing Queries support in the access stack made it possible to include new useful types of queries:
  - QueryChain
  - ObjectIdQuery
  - RelationshipQuery
  - NamedQuery

- More consistent cache/refresh API

#### Generated Columns

Cayenne now supports auto-increment/identity columns as an alternative mechanism for primary key generation.

#### DTD Changes

...

#### JDK 1.5 Features Support

- Mapping Properties as Enums. Numeric or character database columns can now be mapped as custom Enums. Cayenne supports this out of the box without any special configuration. Assumption is made that character columns store the name of a given Enum object, while numeric columns store a position of a given Enum object in the Enum class.

#### Generic Persistent Class

Cayenne allows CayenneDataObject (or its subclass) to be used as a generic persistent object, skipping class generation and compilation steps. Use only when appropriate!

#### WebApplicationContextFilter

A Servlet Specification 2.3 compatible way to bind DataContext to the request thread. See chapter 12.2.4 of the new User Guide shipped with 1.2 milestones for details.

#### DBCPDataSourceFactory: DBCP Pool Support

A connection pool from jakarta-commons DBCP project is now supported via the modeler - just select DBCPDataSourceFactory from the DataSource factories dropdown. The new factory loads its configuration from a specified properties file (see DBCPDataSourcefactory Javadocs for supported properties). DBCP connection pool is much more advanced than the one provided by Cayenne and supports a dozen or so runtime parameters. See Javadocs for org.objectsyle.cayenne.conf.DBCPDataSourceFactory for details.

#### Database Adapter Improvements/New Adapters

- New adapter for Cloudscape/Derby
- New adapter for FrontBase
- New adapter for Ingres
- MySQL adapter is improved to support referential integrity constraints for InnoDB tables.
- Adapter Auto Detection. Users no longer need to specify DbAdapter in the Modeler. All standard adapters are "guessed" by Cayenne in runtime using database metadata. Only custom adapters need to be set explicitly, using the new "Adapter" tab in the DataNode Editor panel. This simplifies configuration, makes deployment more transparent, and allows Cayenne to dynamically tweak adapter settings depending on the underlying database version and runtime parameters.
- Extended type mechanism now allows mapping a persistent property as an interface. This can be achieved via ExtendedTypeFactory API. A custom `ExtendedTypeFactory` is registered in a manner similar to ExtendedType with adapter's `ExtendedTypeMap`: `extendedTypeMap.addFactory(myFactory)`. Cayenne already takes advantage of this API by providing a factory that handles an arbitrary JDK 1.5 Enum via reflection.

#### DataContext Improvements

- User Properties Map. DataContext now maintains an internal map of user-defined values. This allows users to associate certain data with a given DataContext.

- DataContextFactory. DataContext allows to register an optional factory class (via the Modeler or in the API) that will be used to create DataContexts. This way users can implement DataContext subclasses that will seamlessly integrate in the existing Cayenne stack.

- DataContexts Nesting that allows to perform partial in-memory commits/rollbacks.

#### XML Serialization

A new package `org.objectstyle.cayenne.xml` provides a way to encode arbitrary Java objects to XML and decode them from XML. It allows a great degree of control over the XML structure, thus simplifying integration with third party XML message systems. M5 features the first usable release of this feature. However there may be more changes in the course of 1.2.

Need to document this better, for now see Javadocs for `org.objectstyle.cayenne.xml.XMLEncoder` and `org.objectstyle.cayenne.xml.XMLDecoder`.

#### Loading JNDI DataNodes from Local Preferences

If a DataNode is configured to use JNDIDataSourceFactory, you can setup a "Local DataSource" via Modeler preferences with the name matching the JNDI name. After that when you run your application locally without a JNDI container, Cayenne would use local preferences database.

#### WebObjects Integration

EOModel importer now correctly imports EOFetchSpecification qualifiers, prefetches and a number of other previously ignored parameters.

## Tools: CayenneModeler, Ant Tools

#### General UI Rework

CayenneModeler is significantly more user friendly compared to 1.1.

- Modeler is packaged as a native application for Windows and Mac OS X.
- Entity editors have their own "local" toolbars for working with attributes and relationships instead of trying to locate a needed button in the common top toolbar.
- There are two history navigation buttons allowing to quickly return back to the places that you've recently visited.
- There are new PK generator options at the DbEntity level.
- A class generator dialog is completely redesigned to provide a number of advanced options and better general usability.
- A number of visual bug fixes, new icons, etc.
- A number of performance enhancements.

#### Ant Task Improvements

- Antlib descriptor for Cayenne Ant Tasks
- Vastly extended and improved `cgen`. See `cgen` task documetation in the user guide shipped with release for more details. Note that cgen maybe split in two tasks to make it simpler.
- New `cdbgen` task
- New `cdataport` database data porting task. (moved from examples with improvements)

#### Code Generation Improvements

- Customizable Encoding Of Generated Files. Desired encoding for generated Java files can be specified in the Modeler in Preferences and as an "encoding" attribute of the cgen Ant task. This is helpful in cross-platform development situations.

.
Copyright ©2001-2010 Apache Software Foundation