Cayenne New Features and Upgrade Guide

- Guide to 3.1 Features - This guide highlights the new features and changes introduced in 3.1 release. It is a - high-level overview. For more details consult RELEASE-NOTES.txt file included in each release for the full list of - changes, and UPGRADE.txt for the release-specific upgrade - instructions. -

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

+ Guide to 4.0 Features + This guide highlights the new features and changes introduced in Apache Cayenne 4.0. For a + full list of changes consult RELEASE-NOTES.txt included in + Cayenne download. For release-specific upgrade instructions check UPGRADE.txt. + +

+ Java Version + Minimal required JDK verision is 1.6 or newer. Cayenne 4.0 is fully tested with Java + 1.6, 1.7, 1.8.

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 container to configure its services. The container provides DI - services and exposes Cayenne extension points, but does 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 - Here is a simple example of starting a server-side Cayenne stack: - ServerRuntime runtime = new ServerRuntime("cayenne-UntitledDomain.xml"); - For more detailed examples check the tutorials and other documentation. -

- 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. + ServerRuntimeBuilder + Cayenne 3.1 introduced dependency injection and ServerRuntime. 4.0 provides a very + convenient utility to create a custom runtime with various extensions. This reduces + the code needed to integrate Cayenne in your environment to just a few lines and no + boilerplate. + E.g.:ServerRuntime runtime = new ServerRuntimeBuilder("myproject") + .addConfigs("cayenne-project1.xml", "cayenne-project2.xml") + .addModule(binder -> binder.bind(JdbcEventLogger.class).toInstance(myLogger)) + .dataSource(myDataSource) + .build();

Framework API - - See UPGRADE.txt for the full list of changes -

- Lifecycle Listener Annotations - Cayenne 3.1 features support for annotations on lifecycle listeners (but not yet - on entity callback methods) that simplifies registering listeners via API. Our - experience with Cayenne 3.0 shows that mapping listeners in the Modeler doesn't - scale well to complex applications, and 3.0 API for mapping the listeners is hard to - use. In 3.1 you can annotate listener methods and register multiple callback methods - with a single call. - // declare a listener with annotated methods -class MyListener { - @PostLoad(Entity1.class) - @PostPersist(Entity1.class) - void postLoad(Object object) { - .... - } -} - -// register a listener -ServerRuntime runtime = .. -MyListener listener = new MyListener(); -runtime.getChannel().getEntityResolver().getCallbackRegistry().addListener(listener); - Moreover, unlike JPA annotations, Cayenne allows to attach a listener to a set of - entities not known to the listener upfront, but that are all annotated with some - custom annotation: - class MyListener { - @PostLoad(entityAnnotations = CustomAnnotation.class) - void postLoad(Object object) { - .... - } -} + Fluent Query API + Fluent Query API is one of the most exciting new features in Cayenne 4.0. There + are many parts that make it possible (most are described below). But in essence this + is a number of new "chainable" queries that allow to write query assembly and + execution code on one line. The most useful fluent queries are ObjectSelect, + SQLSelect and SelectById: +

+ ObjectSelect + A "chainable" analog of SelectQuery. + Artist a = ObjectSelect + .query(Artist.class) + .where(Artist.ARTIST_NAME.eq("Picasso")) + .selectOne(context); +

+ SQLSelect + A "chainable" analog of SQLTemplate used specifically to run selecting raw + SQL:List<Long> ids = SQLSelect + .scalarQuery(Long.class, "SELECT ARTIST_ID FROM ARTIST ORDER BY ARTIST_ID") + .select(context); + +

+ SelectById + There's really no good analog of SelectById in Cayenne prior to 4.0. + Previously available ObjectIdQuery didn't support half of the features of + SelectById (e.g. caching consistent with other queries, prefetches, etc.) + :Artist a = SelectById + .query(Artist.class, 3) + .useLocalCache("g1") + .selectOne(context) + +

- DataChannelFilter for Intercepting DataDomain Operations - Cayenne now features a DataChannelFilter interface that allows to intercept and - alter all DataChannel traffic (i.e. selects and commits between a DataContext and - DataDomain). It provides a chain of command API very similar to servlet filters. - Filters are widely used by "cayenne-lifecyle" extensions and allow to build powerful - custom object lifecycle-aware code. To install a filter, the following API is - used: - class MyFilter implement DataChannelFilter { .. } - -MyFilter filter = new MyFilter(); -ServerRuntime runtime = .. -runtime.getDataDomain().addFilter(filter); - Very often filters mark some of their own methods with lifecycle annotations so - that certain operations can be triggered by Cayenne inside the scope of filter's - onQuery() or onSync() methods. To ensure annotated methods are invoked, filter - registration should be combined with listener registration: - MyFilter filter = new MyFilter(); -ServerRuntime runtime = .. -runtime.getDataDomain().addFilter(filter); -runtime.getDataDomain().getEntityResolver().getCallbackRegistry().addListener(filter); -// noticed that by default runtime.getDataDomain() is equivalent to runtime.getChannel() + Generics in Expressions and Queries + We finished the work of "genericizing" Cayenne APIs started in 3.1. Now all APIs + dealing with persistent objects (Expressions, Queries, ObjectContext, etc.) support + generics of Persistent object type or attribute property type. +

+ Property API + Persistent superclasses (_MyEntity) now contain a set of static Property<T> + variables generated from the model. These metadata objects make possible to create + type-safe Expressions and other query parts.

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. + Improved UI + CayenneModeler features a number of UI improvements. Attributes and relationships are + now edited in the same view (no need to switch between the tabs). Project tree allows to + easily filter elements by type and quickly collapse the tree. +

+ Dropped Support for Mapping Listeners + Managing listeners in the DataMap XML model is counterproductive and confusing, so + support for listeners was removed from both the XML and the Modeler. If you + previously had listeners mapped in the model, annotate their callback methods, and + perform listener registration in the code: + runtime.getDataDomain().addListener(myListener);Entity + callbacks on the other hand are managed in the Modeler as before.

- Lifecycle Extensions - Cayenne 3.1 includes an optional cayenne-lifecyle module that implements a few useful - extensions based on DataChannelFilters and lifecycle annotations. Those include a - concept of a String ID (which is a String URL-friendly representation of ObjectId), - support for (de)referencing objects by String ID, String ID-based relationships, - annotation-based cache groups invalidation, annotation-based audit of object changes, - etc. +

+ Build Tools +

+ cdbimport + "cdbimport" has evolved from +

+ cgen + As was mentioned above, cgen now includes Property<T> static variables for + expression building. It is also made smarter about its defaults for "destDir" and + "superPkg". +