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 <a...@ish.com.au> Authored: Thu Feb 26 09:25:25 2015 +1100 Committer: Ari Maniatis <a...@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>
