cayenne-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject [1/2] cayenne git commit: 4.0.M2 docs
Date Sun, 30 Nov 2014 14:30:29 GMT
Repository: cayenne
Updated Branches:
  refs/heads/master a27eda27f -> 4cca7a8b0

4.0.M2 docs


Branch: refs/heads/master
Commit: 57ea7055054b9f851b71280010fc4b2ec148fda5
Parents: a27eda2
Author: aadamchik <>
Authored: Sun Nov 30 16:07:31 2014 +0300
Committer: aadamchik <>
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(-)
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="" xmlns:xlink=""
     xml:id="upgrade-guide" xmlns:xi="">
-        <title>Cayenne New Features and Upgrade Guide</title>
+        <title>Cayenne 4.0 New Features and Upgrade Guide</title>
             <holder>Apache Software Foundation and individual authors</holder>
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
-<article xmlns=""
-    xmlns: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
-        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
-                    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
-                    standalone jars in the binary distribution.</para>
-            </listitem>
-        </itemizedlist>
+<article xmlns="" xmlns:xlink=""
+    <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 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>
-            <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
-                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
-                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.
-                DataSource failover load strategy based on CayenneModeler preferences database.
-                problem with JNDI hack was unstable and frequently corrupted preferences
-                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
+                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 xml:id="framework-api">
         <title>Framework API</title>
-        <para>
-            <emphasis role="italic">See UPGRADE.txt for the full list of changes</emphasis>
-        </para>
-            <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.
-                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
-                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();
-            <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
-                custom annotation:</para>
-            <programlisting language="java">class MyListener {
-    @PostLoad(entityAnnotations = CustomAnnotation.class)
-    void postLoad(Object object) {
-        ....
-    }
+            <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
+                is a number of new "chainable" queries that allow to write query assembly
+                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&lt;Long> ids = SQLSelect
+     .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
+                    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>
-            <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
-                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
-                custom object lifecycle-aware code. To install a filter, the following API
-                used:</para>
-            <programlisting language="java">class MyFilter implement DataChannelFilter
{ .. }
-MyFilter filter = new MyFilter();
-ServerRuntime runtime = ..
-            <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 = ..
-// 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.)
+                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&lt;T>
+                variables generated from the model. These metadata objects make possible
to create
+                type-safe Expressions and other query parts.</para>
     <section xml:id="cayenne-modeler">
-            <title>Java Preferences API</title>
-            <para>We got rid of HSQLDB-based preferences storage, and are using standard
-                Preferences API for the Modeler preferences. This solved a long-standing
-                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,
+                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 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
-            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
-            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&lt;T> static
variables for
+                expression building. It is also made smarter about its defaults for "destDir"
+                "superPkg".</para>
+        </section>

View raw message