You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@cayenne.apache.org by am...@apache.org on 2015/02/25 23:25:50 UTC
cayenne git commit: Fix some typos and make the new feature guide a
little clearer.
Repository: cayenne
Updated Branches:
refs/heads/master 1d949be4c -> 9b9b5e0f9
Fix some typos and make the new feature guide a little clearer.
Project: http://git-wip-us.apache.org/repos/asf/cayenne/repo
Commit: http://git-wip-us.apache.org/repos/asf/cayenne/commit/9b9b5e0f
Tree: http://git-wip-us.apache.org/repos/asf/cayenne/tree/9b9b5e0f
Diff: http://git-wip-us.apache.org/repos/asf/cayenne/diff/9b9b5e0f
Branch: refs/heads/master
Commit: 9b9b5e0f9dabbbdd5c1904b3cb7a0055ad18df18
Parents: 1d949be
Author: Ari Maniatis <ar...@ish.com.au>
Authored: Thu Feb 26 09:25:25 2015 +1100
Committer: Ari Maniatis <ar...@ish.com.au>
Committed: Thu Feb 26 09:25:25 2015 +1100
----------------------------------------------------------------------
.../upgrade-guide/src/docbkx/new-features.xml | 271 +++++++++----------
1 file changed, 122 insertions(+), 149 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/cayenne/blob/9b9b5e0f/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 b6777cd..256b46f 100644
--- a/docs/docbook/upgrade-guide/src/docbkx/new-features.xml
+++ b/docs/docbook/upgrade-guide/src/docbkx/new-features.xml
@@ -15,122 +15,105 @@
License.
-->
<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>
- <para>The examples below often use Java 8 syntax. But those same examples should work
- withour lambdas just as well.</para>
- </section>
- <section xml:id="cayenne-configuration">
- <title>Cayenne Configuration</title>
- <section>
- <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")
+ <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>Minimum required JDK version is 1.6 or newer. Cayenne 4.0 is fully tested with Java 1.6, 1.7, 1.8. </para>
+ <para>The examples below often use Java 8 syntax. But those same examples should work without lambdas just as well.</para>
+ </section>
+ <section xml:id="cayenne-configuration">
+ <title>Cayenne Configuration</title>
+ <section>
+ <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>
- <title>Mapping-free ServerRuntime</title>
- <para>ServerRuntime can now be started without any ORM mapping at all. This is useful
- e.g. in situations when Cayenne is used as a stack to execute raw SQL, in unit
- tests, etc.</para>
- </section>
- </section>
- <section xml:id="framework-api">
- <title>Framework API</title>
- <section>
- <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
+ </section>
+ <section>
+ <title>Mapping-free ServerRuntime</title>
+ <para>ServerRuntime can now be started without any ORM mapping at all. This is useful in situations when Cayenne is used as a stack to
+ execute raw SQL, in unit tests, etc.</para>
+ </section>
+ </section>
+ <section xml:id="framework-api">
+ <title>Framework API</title>
+ <section>
+ <title>Fluent Query API</title>
+ <para>Fluent Query API is one of the most exciting new features in Cayenne 4.0. This syntax is "chainable" so you can 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
+ </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
+ </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 xml:id="objectcontext">
- <title>ObjectContext</title>
- <section>
- <title>Callback-based Object Iterator</title>
- <para>ObjectContext now features a simpler way to iterate over large result sets, based
- on callback interface that can be implemented with a
- lambda:<programlisting>SelectQuery<Artist> q = new SelectQuery<Artist>(Artist.class);
+ </section>
+ </section>
+ <section xml:id="objectcontext">
+ <title>ObjectContext</title>
+ <section>
+ <title>Callback-based Object Iterator</title>
+ <para>ObjectContext now features a simpler way to iterate over large result sets, based on callback interface that can be
+ implemented with a
+ lambda:<programlisting>SelectQuery<Artist> q = new SelectQuery<Artist>(Artist.class);
context.iterate(q, (Artist a) -> {
// do something with the object...
...
});</programlisting></para>
- </section>
- </section>
- <section>
- <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>
- <title>Positional Parameter Bindings </title>
- <para>Expressions and SQLTemplate traditionally supported binding of parameters by name
- as a map. Cayenne 4.0 introduces a very easy form of positional bindings. It works
- with the same named template format, only parameters are bound by position,
- left-to-right. Here we showing a more complex example with the same parameter name
- beijg used more than once in the
- query:<programlisting>// two distinct names, 3 positional parameters.
+ </section>
+ </section>
+ <section>
+ <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>
+ <title>Positional Parameter Bindings </title>
+ <para>Expressions and SQLTemplate traditionally supported binding of parameters by name as a map. Cayenne 4.0 introduces a very easy
+ form of positional bindings. It works with the same named template format, only parameters are bound by position, left-to-right.
+ Here we showing a more complex example with the same parameter name being used more than once in the
+ query:<programlisting>// two distinct names, 3 positional parameters.
// "price" is set to 23, "maxPrice" - to 50
Expression e = ExpressionFactory.exp(
"price = $price or averagePrice = $price and maxPrice = $maxPrice", 23, 50);</programlisting>This
- API is supported in Expressions, SQLTemplate as well as new SQLSelect and can be
- used interchnageably with named parameters with a single template flavor.</para>
- </section>
- <section>
- <title>Improved Transaction API</title>
- <para>Transaction factory is now setup via DI (instead of being configured in the
- Modeler). There's a utility method on ServerRuntime to perform multiple operations
- as one
- transaction:<programlisting>runtime.performInTransaction(() -> {
+ API is supported in Expressions, SQLTemplate as well as new SQLSelect and can be used interchnageably with named parameters with a
+ single template flavor.</para>
+ </section>
+ <section>
+ <title>Improved Transaction API</title>
+ <para>Transaction factory is now setup via DI (instead of being configured in the Modeler). There's a utility method on ServerRuntime
+ to perform multiple operations as one
+ transaction:<programlisting>runtime.performInTransaction(() -> {
// ... do some changes
context.commitChanges();
@@ -139,60 +122,50 @@ Expression e = ExpressionFactory.exp(
return true;
});</programlisting></para>
- </section>
- <section>
- <title>Transparent Database Cryptography with "cayenne-crypto" Module</title>
- <para>Cayenne includes a new module called "cayenne-crypto" that enables transparent
- cryptography for designated data columns. This is a pretty cool feature that allows
- to enable encryption/decryption of your sensitive data pretty much declaratively
- using your regular DB storage. Encrypted values can be stored in (VAR)BINARY and
- (VAR)CHAR columns. Currently "cayenne-crypto" supports AES/CBC/PKCS5Padding
- encryption (though other cyphers can be added). It also supports encrypted data
- compression. Here is an example of building a crypto DI module that can be added to
- ServerRuntime:<programlisting>Module cryptoExtensions = new CryptoModuleBuilder()
+ </section>
+ <section>
+ <title>Transparent Database Cryptography with "cayenne-crypto" Module</title>
+ <para>Cayenne includes a new module called "cayenne-crypto" that enables transparent cryptography for designated data columns. This is
+ a pretty cool feature that allows to enable encryption/decryption of your sensitive data pretty much declaratively using your
+ regular DB storage. Encrypted values can be stored in (VAR)BINARY and (VAR)CHAR columns. Currently "cayenne-crypto" supports
+ AES/CBC/PKCS5Padding encryption (though other cyphers can be added). It also supports encrypted data compression. Here is an example
+ of building a crypto DI module that can be added to
+ ServerRuntime:<programlisting>Module cryptoExtensions = new CryptoModuleBuilder()
.keyStore("file:///mykeystore", "keystorepassword".toCharArray(), "keyalias")
.compress()
.build();</programlisting></para>
- </section>
- </section>
- <section xml:id="cayenne-modeler">
- <title>CayenneModeler</title>
- <section>
- <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="build-tools">
- <title>Build Tools</title>
- <section>
- <title>cdbimport</title>
- <para>"cdbimport" has evolved from an experiment to a full-featured production tool that
- significantly reduces (and sometimes eliminates) the need for manual maintenance of
- the DataMaps in CayenneModeler. The two improvements made it possible. First, smart
- merge algorithm that will ensure that custom chnages to the model are not overridden
- on subsequent runs of "cdbimport". Second, the mechanism for specifing DB
- reverse-engineering parameters, such as name filtering, is made much more powerful
- with many new options. E.g. we started supporting filters by catalogs and schemas,
- table name filters can be added per catalog/schema or at the top level, etc. Also
- configuration can be "inlined" in a Maven pom.xml or specified as a separate
- file.</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>
+ </section>
+ </section>
+ <section xml:id="cayenne-modeler">
+ <title>CayenneModeler</title>
+ <section>
+ <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="build-tools">
+ <title>Build Tools</title>
+ <section>
+ <title>cdbimport</title>
+ <para>"cdbimport" has evolved from an experiment to a full-featured production tool that significantly reduces (and sometimes
+ eliminates) the need for manual maintenance of the DataMaps in CayenneModeler. Two improvements made this possible. First, smart
+ merge algorithm will ensure that custom changes to the model are not overridden on subsequent runs of "cdbimport". Second, the
+ mechanism for specifing DB reverse-engineering parameters, such as name filtering, is made much more powerful with many new options.
+ E.g. we started supporting filters by catalogs and schemas, table name filters can be added per catalog/schema or at the top level,
+ etc. Also configuration can be "inlined" in a Maven pom.xml or specified as a separate file.</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>