Repository: cayenne Updated Branches: refs/heads/master a27eda27f -> 4cca7a8b0
4.0.M2 docs Project: http://git-wip-us.apache.org/repos/asf/cayenne/repo Commit: http://git-wip-us.apache.org/repos/asf/cayenne/commit/57ea7055 Tree: http://git-wip-us.apache.org/repos/asf/cayenne/tree/57ea7055 Diff: http://git-wip-us.apache.org/repos/asf/cayenne/diff/57ea7055 Branch: refs/heads/master Commit: 57ea7055054b9f851b71280010fc4b2ec148fda5 Parents: a27eda2 Author: aadamchik <aadamc...@apache.org> Authored: Sun Nov 30 16:07:31 2014 +0300 Committer: aadamchik <aadamc...@apache.org> Committed: Sun Nov 30 17:29:53 2014 +0300 ---------------------------------------------------------------------- docs/docbook/upgrade-guide/src/docbkx/index.xml | 2 +- .../upgrade-guide/src/docbkx/new-features.xml | 215 ++++++++----------- 2 files changed, 90 insertions(+), 127 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/cayenne/blob/57ea7055/docs/docbook/upgrade-guide/src/docbkx/index.xml ---------------------------------------------------------------------- diff --git a/docs/docbook/upgrade-guide/src/docbkx/index.xml b/docs/docbook/upgrade-guide/src/docbkx/index.xml index 86d9d34..439474a 100644 --- a/docs/docbook/upgrade-guide/src/docbkx/index.xml +++ b/docs/docbook/upgrade-guide/src/docbkx/index.xml @@ -2,7 +2,7 @@ <book xmlns="http://docbook.org/ns/docbook"; xmlns:xlink="http://www.w3.org/1999/xlink"; version="5.0" xml:id="upgrade-guide" xmlns:xi="http://www.w3.org/2001/XInclude";> <info> - <title>Cayenne New Features and Upgrade Guide</title> + <title>Cayenne 4.0 New Features and Upgrade Guide</title> <copyright> <year>2011-2014</year> <holder>Apache Software Foundation and individual authors</holder> http://git-wip-us.apache.org/repos/asf/cayenne/blob/57ea7055/docs/docbook/upgrade-guide/src/docbkx/new-features.xml ---------------------------------------------------------------------- diff --git a/docs/docbook/upgrade-guide/src/docbkx/new-features.xml b/docs/docbook/upgrade-guide/src/docbkx/new-features.xml index 3251d5d..5826d51 100644 --- a/docs/docbook/upgrade-guide/src/docbkx/new-features.xml +++ b/docs/docbook/upgrade-guide/src/docbkx/new-features.xml @@ -14,149 +14,112 @@ the specific language governing permissions and limitations under the License. --> -<article xmlns="http://docbook.org/ns/docbook"; - xmlns:xlink="http://www.w3.org/1999/xlink"; version="5.0"> - <title>Guide to 3.1 Features</title> - <para>This guide highlights the new features and changes introduced in 3.1 release. It is a - high-level overview. For more details consult <emphasis role="bold" - >RELEASE-NOTES.txt</emphasis> file included in each release for the full list of - changes, and <emphasis role="bold">UPGRADE.txt</emphasis> for the release-specific upgrade - instructions.</para> - <section xml:id="ditribution-content-structure"> - <title>Distribution Contents Structure</title> - <para>Cayenne distribution is made leaner and more modular:</para> - <itemizedlist> - <listitem> - <para>"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.</para> - </listitem> - <listitem> - <para>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.</para> - </listitem> - <listitem> - <para>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.</para> - </listitem> - </itemizedlist> +<article xmlns="http://docbook.org/ns/docbook"; xmlns:xlink="http://www.w3.org/1999/xlink"; version="5.0"> + <title>Guide to 4.0 Features</title> + <para>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.</para> + + <section xml:id="java-version"> + <title>Java Version</title> + <para>Minimal required JDK verision is 1.6 or newer. Cayenne 4.0 is fully tested with Java + 1.6, 1.7, 1.8.</para> </section> <section xml:id="cayenne-configuration"> <title>Cayenne Configuration</title> - - <note><para>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.</para></note> <section> - <title>Dependency Injection Container</title> - <para>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.</para> - </section> - <section> - <title>Bootstrapping Cayenne in Various Environments</title> - <para> Here is a simple example of starting a server-side Cayenne stack:</para> - <programlisting language="java">ServerRuntime runtime = new ServerRuntime("cayenne-UntitledDomain.xml");</programlisting> - <para>For more detailed examples check the tutorials and other documentation.</para> - </section> - <section> - <title>Configuring Local DataSources, Removal of JNDI Hack</title> - <para>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:</para> - <programlisting>-Dcayenne.jdbc.driver=com.mysql.jdbc.Driver -Dcayenne.jdbc.url=jdbc:mysql://localhost/mydb \ --Dcayenne.jdbc.username=user -Dcayenne.jdbc.password=password</programlisting> - <para>For more details and configuration options see javadocs of - org.apache.cayenne.configuration.server.PropertyDataSourceFactory. </para> - <para>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. </para> + <title>ServerRuntimeBuilder</title> + <para>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.:<programlisting>ServerRuntime runtime = new ServerRuntimeBuilder("myproject") + .addConfigs("cayenne-project1.xml", "cayenne-project2.xml") + .addModule(binder -> binder.bind(JdbcEventLogger.class).toInstance(myLogger)) + .dataSource(myDataSource) + .build();</programlisting></para> </section> </section> <section xml:id="framework-api"> <title>Framework API</title> - <para> - <emphasis role="italic">See UPGRADE.txt for the full list of changes</emphasis> - </para> <section> - <title>Lifecycle Listener Annotations</title> - <para>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. </para> - <programlisting language="java">// 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);</programlisting> - <para>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:</para> - <programlisting language="java">class MyListener { - @PostLoad(entityAnnotations = CustomAnnotation.class) - void postLoad(Object object) { - .... - } -}</programlisting> + <title>Fluent Query API</title> + <para>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:</para> + <section> + <title>ObjectSelect</title> + <para>A "chainable" analog of SelectQuery. + <programlisting>Artist a = ObjectSelect + .query(Artist.class) + .where(Artist.ARTIST_NAME.eq("Picasso")) + .selectOne(context);</programlisting></para> + </section> + <section> + <title>SQLSelect</title> + <para>A "chainable" analog of SQLTemplate used specifically to run selecting raw + SQL:<programlisting>List<Long> ids = SQLSelect + .scalarQuery(Long.class, "SELECT ARTIST_ID FROM ARTIST ORDER BY ARTIST_ID") + .select(context);</programlisting></para> + + </section> + <section> + <title>SelectById</title> + <para>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.) + :<programlisting>Artist a = SelectById + .query(Artist.class, 3) + .useLocalCache("g1") + .selectOne(context)</programlisting></para> + + </section> </section> + <section> - <title>DataChannelFilter for Intercepting DataDomain Operations</title> - <para>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:</para> - <programlisting language="java">class MyFilter implement DataChannelFilter { .. } - -MyFilter filter = new MyFilter(); -ServerRuntime runtime = .. -runtime.getDataDomain().addFilter(filter);</programlisting> - <para>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:</para> - <programlisting language="java">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()</programlisting> + <title>Generics in Expressions and Queries</title> + <para>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.</para> + </section> + <section> + <title>Property API</title> + <para>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.</para> </section> </section> <section xml:id="cayenne-modeler"> <title>CayenneModeler</title> <section> - <title>Java Preferences API</title> - <para>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.</para> + <title>Improved UI</title> + <para>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.</para> + </section> + <section> + <title>Dropped Support for Mapping Listeners</title> + <para>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: + <programlisting>runtime.getDataDomain().addListener(myListener);</programlisting>Entity + callbacks on the other hand are managed in the Modeler as before.</para> </section> </section> - <section xml:id="lifecycle-extensions"> - <title>Lifecycle Extensions</title> - <para>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.</para> + <section xml:id="build-tools"> + <title>Build Tools</title> + <section> + <title>cdbimport</title> + <para>"cdbimport" has evolved from </para> + </section> + <section> + <title>cgen</title> + <para>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".</para> + </section> </section> </article>
