Cayenne additional modules documentation (cherry picked from commit b073b48)
Project: http://git-wip-us.apache.org/repos/asf/cayenne/repo Commit: http://git-wip-us.apache.org/repos/asf/cayenne/commit/562aac45 Tree: http://git-wip-us.apache.org/repos/asf/cayenne/tree/562aac45 Diff: http://git-wip-us.apache.org/repos/asf/cayenne/diff/562aac45 Branch: refs/heads/STABLE-4.0 Commit: 562aac450f55cfa11bfddaf1d14ea7815632a1ac Parents: de25580 Author: Nikita Timofeev <stari...@gmail.com> Authored: Fri Sep 1 14:38:26 2017 +0300 Committer: Nikita Timofeev <stari...@gmail.com> Committed: Fri Sep 22 17:04:37 2017 +0300 ---------------------------------------------------------------------- .../src/docbkx/ext-cache-invalidation.xml | 92 +++++++++++++ .../cayenne-guide/src/docbkx/ext-commit-log.xml | 89 ++++++++++++ .../cayenne-guide/src/docbkx/ext-crypto.xml | 134 +++++++++++++++++++ .../cayenne-guide/src/docbkx/ext-dbcp2.xml | 59 ++++++++ .../cayenne-guide/src/docbkx/ext-java8.xml | 53 ++++++++ .../cayenne-guide/src/docbkx/ext-jcache.xml | 61 +++++++++ .../cayenne-guide/src/docbkx/ext-joda.xml | 53 ++++++++ .../src/docbkx/ext-project-compatibility.xml | 59 ++++++++ .../cayenne-guide/src/docbkx/ext-velocity.xml | 79 +++++++++++ docs/docbook/cayenne-guide/src/docbkx/index.xml | 1 + docs/docbook/cayenne-guide/src/docbkx/part5.xml | 32 +++++ .../src/docbkx/queries-sqltemplate.xml | 30 +---- docs/docbook/cayenne-guide/src/docbkx/setup.xml | 5 + .../src/images/ext-crypto-obj-entity.png | Bin 0 -> 18145 bytes .../cayenne-guide/src/images/ext-dbcp-setup.png | Bin 0 -> 33026 bytes .../upgrade-guide/src/docbkx/new-features.xml | 57 ++++++-- 16 files changed, 766 insertions(+), 38 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/cayenne/blob/562aac45/docs/docbook/cayenne-guide/src/docbkx/ext-cache-invalidation.xml ---------------------------------------------------------------------- diff --git a/docs/docbook/cayenne-guide/src/docbkx/ext-cache-invalidation.xml b/docs/docbook/cayenne-guide/src/docbkx/ext-cache-invalidation.xml new file mode 100644 index 0000000..e597f42 --- /dev/null +++ b/docs/docbook/cayenne-guide/src/docbkx/ext-cache-invalidation.xml @@ -0,0 +1,92 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!--~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + ~ Licensed to the Apache Software Foundation (ASF) under one + ~ or more contributor license agreements. See the NOTICE file + ~ distributed with this work for additional information + ~ regarding copyright ownership. The ASF licenses this file + ~ to you under the Apache License, Version 2.0 (the + ~ "License"); you may not use this file except in compliance + ~ with the License. You may obtain a copy of the License at + ~ + ~ http://www.apache.org/licenses/LICENSE-2.0 + ~ + ~ Unless required by applicable law or agreed to in writing, + ~ software distributed under the License is distributed on an + ~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + ~ KIND, either express or implied. See the License for the + ~ specific language governing permissions and limitations + ~ under the License. + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~--> +<chapter xmlns="http://docbook.org/ns/docbook"; xmlns:xlink="http://www.w3.org/1999/xlink"; + version="5.0" xml:id="ext-cache-invalidation"> + <title>Cache invalidation extension</title> + <section> + <title>Description</title> + <para>Cache invalidation module is small extensions that allows easily manage cache invalidation policy.</para> + </section> + <section> + <title>Including in a Project</title> + <section> + <title>Maven</title> + <para> + <programlisting language="xml"><dependency> + <groupId>org.apache.cayenne</groupId> + <artifactId>cayenne-cache-invalidation</artifactId> + <version><?eval ${project.version}?></version> +</dependency></programlisting> + </para> + </section> + <section> + <title>Gradle</title> + <para> + <programlisting language="groovy">compile 'org.apache.cayenne:cayenne-cache-invalidation:<?eval ${project.version}?>'</programlisting> + </para> + </section> + </section> + <section> + <title>Usage</title> + <para> + Module supports autoloading mechanism, so no other actions required to start using it. + Just mark you entities with <code>@CacheGroups</code> annotation: + <programlisting language="java"><![CDATA[ +@CacheGroups("some-group") +public class MyEntity extends _MyEntity { + // ... +}]]></programlisting> + That's all, now after any modification of <code>MyEntity</code> objects cache group <code>"some-group"</code> + will be invalidated automatically. + <note> + <para>You can read more about cache and cache groups in corresponding <link linkend="caching-and-fresh-data">chapter</link> of this documentation.</para> + </note> + </para> + <para> + In case you need some complex logic of cache invalidation you can disable this default behaviour and + provide you own logic. + </para> + <para> + To do so you need to implement <code>org.apache.cayenne.cache.invalidation.InvalidationHandler</code> interface and tell Cache Invalidation module to + use it. + Let's assume we have our implementation class called <code>CustomInvalidationHandler</code> that will simply match + all entities with <code>"custom-group"</code> cache group: + <programlisting language="java"><![CDATA[ +public class CustomInvalidationHandler implements InvalidationHandler { + @Override + public InvalidationFunction canHandle(Class<? extends Persistent> type) { + return p -> Collections.singleton(new CacheGroupDescriptor("custom-group")); + } +}]]></programlisting> + Now we'll set up it's usage by <code>ServerRuntime</code>: + <programlisting language="java"><![CDATA[ +ServerRuntime.builder() + .addModule(CacheInvalidationModule.extend() + // this will disable default handler based on @CacheGroups, and this is optional + .noCacheGroupsHandler() + .addHandler(CustomInvalidationHandler.class) + .module()) +]]></programlisting> + <note> + <para>You can combine as many invalidation handlers as you need.</para> + </note> + </para> + </section> +</chapter> http://git-wip-us.apache.org/repos/asf/cayenne/blob/562aac45/docs/docbook/cayenne-guide/src/docbkx/ext-commit-log.xml ---------------------------------------------------------------------- diff --git a/docs/docbook/cayenne-guide/src/docbkx/ext-commit-log.xml b/docs/docbook/cayenne-guide/src/docbkx/ext-commit-log.xml new file mode 100644 index 0000000..97c38df --- /dev/null +++ b/docs/docbook/cayenne-guide/src/docbkx/ext-commit-log.xml @@ -0,0 +1,89 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!--~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + ~ Licensed to the Apache Software Foundation (ASF) under one + ~ or more contributor license agreements. See the NOTICE file + ~ distributed with this work for additional information + ~ regarding copyright ownership. The ASF licenses this file + ~ to you under the Apache License, Version 2.0 (the + ~ "License"); you may not use this file except in compliance + ~ with the License. You may obtain a copy of the License at + ~ + ~ http://www.apache.org/licenses/LICENSE-2.0 + ~ + ~ Unless required by applicable law or agreed to in writing, + ~ software distributed under the License is distributed on an + ~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + ~ KIND, either express or implied. See the License for the + ~ specific language governing permissions and limitations + ~ under the License. + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~--> +<chapter xmlns="http://docbook.org/ns/docbook"; xmlns:xlink="http://www.w3.org/1999/xlink"; + version="5.0" xml:id="ext-commit-log"> + <title>Commit log extension</title> + <section> + <title>Description</title> + <para>The goal of this module is to capture commit changes and present them to interested parties in an easy-to-process format.</para> + </section> + <section> + <title>Including in a Project</title> + <section> + <title>Maven</title> + <para> + <programlisting language="xml"><dependency> + <groupId>org.apache.cayenne</groupId> + <artifactId>cayenne-commitlog</artifactId> + <version><?eval ${project.version}?></version> +</dependency></programlisting> + </para> + </section> + <section> + <title>Gradle</title> + <para> + <programlisting language="groovy">compile 'org.apache.cayenne:cayenne-commitlog:<?eval ${project.version}?>'</programlisting> + </para> + </section> + </section> + <section> + <title>Usage</title> + <para> + In order to use <code>commitlog</code> module you need to perform three easy steps: + <orderedlist> + <listitem> + <para>Mark all entities that changes you interested in with <code>@org.apache.cayenne.commitlog.CommitLog</code> annotation</para> + <programlisting language="java"><![CDATA[ +@CommitLog(ignoredProperties = {"somePropertyToSkip"}) +public class MyEntity extends _MyEntity { + // ... +}]]></programlisting> + </listitem> + <listitem> + <para> + Implement <code>CommitLogListener</code> interface. + <programlisting language="java"><![CDATA[ +public class MyCommitLogListener implements CommitLogListener { + @Override + public void onPostCommit(ObjectContext originatingContext, ChangeMap changes) { + // ChangeMap will contain all information about changes happened in performed commit + // this example will simply print IDs of all inserted objects + changes.getUniqueChanges().stream() + .filter(change -> change.getType() == ObjectChangeType.INSERT) + .map(ObjectChange::getPostCommitId) + .forEach(id -> System.out.println("Inserted new entity with id: " + id)); + } +}]]></programlisting> + </para> + </listitem> + <listitem> + <para> + Inject your listener into <code>ServerRuntime</code> + <programlisting language="java"><![CDATA[ +ServerRuntime.builder() + .addModule(CommitLogModule.extend() + .addListener(MyCommitLogListener.class) + .module())]]></programlisting> + </para> + </listitem> + </orderedlist> + </para> + </section> +</chapter> http://git-wip-us.apache.org/repos/asf/cayenne/blob/562aac45/docs/docbook/cayenne-guide/src/docbkx/ext-crypto.xml ---------------------------------------------------------------------- diff --git a/docs/docbook/cayenne-guide/src/docbkx/ext-crypto.xml b/docs/docbook/cayenne-guide/src/docbkx/ext-crypto.xml new file mode 100644 index 0000000..082e640 --- /dev/null +++ b/docs/docbook/cayenne-guide/src/docbkx/ext-crypto.xml @@ -0,0 +1,134 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!--~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + ~ Licensed to the Apache Software Foundation (ASF) under one + ~ or more contributor license agreements. See the NOTICE file + ~ distributed with this work for additional information + ~ regarding copyright ownership. The ASF licenses this file + ~ to you under the Apache License, Version 2.0 (the + ~ "License"); you may not use this file except in compliance + ~ with the License. You may obtain a copy of the License at + ~ + ~ http://www.apache.org/licenses/LICENSE-2.0 + ~ + ~ Unless required by applicable law or agreed to in writing, + ~ software distributed under the License is distributed on an + ~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + ~ KIND, either express or implied. See the License for the + ~ specific language governing permissions and limitations + ~ under the License. + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~--> +<chapter xmlns="http://docbook.org/ns/docbook"; xmlns:xlink="http://www.w3.org/1999/xlink"; + version="5.0" xml:id="ext-crypto"> + <title>Crypto extension</title> + <section> + <title>Description</title> + <para>Crypto module allows encrypt and decrypt values stored in DB transparently to your Java app.</para> + </section> + <section> + <title>Including in a Project</title> + <section> + <title>Maven</title> + <para> + <programlisting language="xml"><dependency> + <groupId>org.apache.cayenne</groupId> + <artifactId>cayenne-crypto</artifactId> + <version><?eval ${project.version}?></version> +</dependency></programlisting> + </para> + </section> + <section> + <title>Gradle</title> + <para> + <programlisting language="groovy">compile 'org.apache.cayenne:cayenne-crypto:<?eval ${project.version}?>'</programlisting> + </para> + </section> + </section> + <section> + <title>Usage</title> + <section> + <title>Setup your model and DB</title> + <para> + To use crypto you must prepare your database structure to allow <code>byte[]</code> storage. + Also you should define naming convention to mark encrypted columns and set appropriate SQL type. + Default naming strategy that doesn't require additional setup is using <code>"CRYPTO_"</code> prefix on columns + that will contain encrypted data. + If you need to you can change this default strategy by injecting you own implementation of + <code>org.apache.cayenne.crypto.map.ColumnMapper</code> interface. + <programlisting language="java"><![CDATA[ +ServerRuntime.builder() + .addModule(CryptoModule.extend() + .columnMapper(MyColumnMapper.class) + .module())]]></programlisting> + </para> + <para> + Currently supported SQL types that can be used to store encrypted data are: + <orderedlist> + <listitem> + <para> + Binary types: <code>BINARY, BLOB, VARBINARY, LONGVARBINARY</code>. + This types are preferred. + </para> + </listitem> + <listitem> + <para>Character types, that will store <code>base64</code> encoded value: + <code>CHAR, NCHAR, CLOB, NCLOB, LONGVARCHAR, LONGNVARCHAR, VARCHAR, NVARCHAR</code></para> + </listitem> + </orderedlist> + <note> + <para>Not all data types may be supported by your database.</para> + </note> + </para> + <para> + Here is example of how your <code>ObjEntity</code> with two encrypted and two unencrypted properties + can look like in the Cayenne Modeler: + </para> + <para><inlinemediaobject> + <imageobject> + <imagedata fileref="images/ext-crypto-obj-entity.png" scalefit="1" width="100%"/> + </imageobject> + </inlinemediaobject></para> + </section> + <section> + <title>Setup keystore</title> + <para> + To perform encryption you must provide <code>KEYSTORE_URL</code> and <code>KEY_PASSWORD</code> to this module. + Currently crypto module supports only Java "jceks" KeyStore. + <programlisting language="java"><![CDATA[ +ServerRuntime.builder() + .addModule(CryptoModule.extend() + .keyStore(this.getClass().getResource("keystore.jcek"), "my-password".toCharArray(), "my-key-alias") + .module())]]></programlisting> + </para> + </section> + <section> + <title>Additional settings</title> + <para> + Additionally to <code>ColumnMapper</code> mentioned above you can customize other parts of + <code>crypto module</code>. + You can enable <code>gzip</code> compression and <code>HMAC</code> usage (this will ensure integrity of data). + <programlisting language="java"><![CDATA[ +ServerRuntime.builder() + .addModule(CryptoModule.extend() + .compress() + .useHMAC() + .module())]]></programlisting> + </para> + <para> + Another useful extension point is support for custom Java value types. To add support for your + data type you need to implement <code>org.apache.cayenne.crypto.transformer.value.BytesConverter</code> + interface that will convert required type to and from <code>byte[]</code>. + <programlisting language="java"><![CDATA[ +ServerRuntime.builder() + .addModule(CryptoModule.extend() + .objectToBytesConverter(MyClass.class, new MyClassBytesConverter()) + .module())]]></programlisting> + </para> + <note> + <para>In addition to Java primitive types (and their object counterparts), <code>crypto module</code> + by default supports encryption only of <code>java.util.Date</code>, <code>java.math.BigInteger</code> + and <code>java.math.BigDecimal</code> types. + </para> + </note> + </section> + </section> +</chapter> http://git-wip-us.apache.org/repos/asf/cayenne/blob/562aac45/docs/docbook/cayenne-guide/src/docbkx/ext-dbcp2.xml ---------------------------------------------------------------------- diff --git a/docs/docbook/cayenne-guide/src/docbkx/ext-dbcp2.xml b/docs/docbook/cayenne-guide/src/docbkx/ext-dbcp2.xml new file mode 100644 index 0000000..00097a6 --- /dev/null +++ b/docs/docbook/cayenne-guide/src/docbkx/ext-dbcp2.xml @@ -0,0 +1,59 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!--~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + ~ Licensed to the Apache Software Foundation (ASF) under one + ~ or more contributor license agreements. See the NOTICE file + ~ distributed with this work for additional information + ~ regarding copyright ownership. The ASF licenses this file + ~ to you under the Apache License, Version 2.0 (the + ~ "License"); you may not use this file except in compliance + ~ with the License. You may obtain a copy of the License at + ~ + ~ http://www.apache.org/licenses/LICENSE-2.0 + ~ + ~ Unless required by applicable law or agreed to in writing, + ~ software distributed under the License is distributed on an + ~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + ~ KIND, either express or implied. See the License for the + ~ specific language governing permissions and limitations + ~ under the License. + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~--> +<chapter xmlns="http://docbook.org/ns/docbook"; xmlns:xlink="http://www.w3.org/1999/xlink"; + version="5.0" xml:id="ext-dbcp2"> + <title>Apache Commons DBCP integration</title> + <section> + <title>Description</title> + <para> + This module enables usage of Apache Commons DBCP2 connection pool. + </para> + </section> + <section> + <title>Including in a Project</title> + <section> + <title>Maven</title> + <para> + <programlisting language="xml"><dependency> + <groupId>org.apache.cayenne</groupId> + <artifactId>cayenne-dbcp2</artifactId> + <version><?eval ${project.version}?></version> +</dependency></programlisting> + </para> + </section> + <section> + <title>Gradle</title> + <para> + <programlisting language="groovy">compile 'org.apache.cayenne:cayenne-dbcp2:<?eval ${project.version}?>'</programlisting> + </para> + </section> + </section> + <section> + <title>Usage</title> + <para> + To use DBCP2 pool you can just setup it in <code>DataNode</code> settings in Cayenne Modeler: + </para> + <para><inlinemediaobject> + <imageobject> + <imagedata fileref="images/ext-dbcp-setup.png" scalefit="1" width="100%"/> + </imageobject> + </inlinemediaobject></para> + </section> +</chapter> http://git-wip-us.apache.org/repos/asf/cayenne/blob/562aac45/docs/docbook/cayenne-guide/src/docbkx/ext-java8.xml ---------------------------------------------------------------------- diff --git a/docs/docbook/cayenne-guide/src/docbkx/ext-java8.xml b/docs/docbook/cayenne-guide/src/docbkx/ext-java8.xml new file mode 100644 index 0000000..912de55 --- /dev/null +++ b/docs/docbook/cayenne-guide/src/docbkx/ext-java8.xml @@ -0,0 +1,53 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!--~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + ~ Licensed to the Apache Software Foundation (ASF) under one + ~ or more contributor license agreements. See the NOTICE file + ~ distributed with this work for additional information + ~ regarding copyright ownership. The ASF licenses this file + ~ to you under the Apache License, Version 2.0 (the + ~ "License"); you may not use this file except in compliance + ~ with the License. You may obtain a copy of the License at + ~ + ~ http://www.apache.org/licenses/LICENSE-2.0 + ~ + ~ Unless required by applicable law or agreed to in writing, + ~ software distributed under the License is distributed on an + ~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + ~ KIND, either express or implied. See the License for the + ~ specific language governing permissions and limitations + ~ under the License. + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~--> +<chapter xmlns="http://docbook.org/ns/docbook"; xmlns:xlink="http://www.w3.org/1999/xlink"; + version="5.0" xml:id="ext-java8"> + <title>Java 8 extension</title> + <section> + <title>Description</title> + <para>Java 8 module allows to use <code>java.time.LocalTime</code>, <code>java.time.LocalDate</code> + and <code>java.time.LocalDateTime</code> types for entity attributes</para> + </section> + <section> + <title>Including in a Project</title> + <section> + <title>Maven</title> + <para> + <programlisting language="xml"><dependency> + <groupId>org.apache.cayenne</groupId> + <artifactId>cayenne-java8</artifactId> + <version><?eval ${project.version}?></version> +</dependency></programlisting> + </para> + </section> + <section> + <title>Gradle</title> + <para> + <programlisting language="groovy">compile 'org.apache.cayenne:cayenne-java8:<?eval ${project.version}?>'</programlisting> + </para> + </section> + </section> + <section> + <title>Usage</title> + <para> + This module doesn't require any additional setup, you can just use new data types in your model. + </para> + </section> +</chapter> http://git-wip-us.apache.org/repos/asf/cayenne/blob/562aac45/docs/docbook/cayenne-guide/src/docbkx/ext-jcache.xml ---------------------------------------------------------------------- diff --git a/docs/docbook/cayenne-guide/src/docbkx/ext-jcache.xml b/docs/docbook/cayenne-guide/src/docbkx/ext-jcache.xml new file mode 100644 index 0000000..4756eae --- /dev/null +++ b/docs/docbook/cayenne-guide/src/docbkx/ext-jcache.xml @@ -0,0 +1,61 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!--~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + ~ Licensed to the Apache Software Foundation (ASF) under one + ~ or more contributor license agreements. See the NOTICE file + ~ distributed with this work for additional information + ~ regarding copyright ownership. The ASF licenses this file + ~ to you under the Apache License, Version 2.0 (the + ~ "License"); you may not use this file except in compliance + ~ with the License. You may obtain a copy of the License at + ~ + ~ http://www.apache.org/licenses/LICENSE-2.0 + ~ + ~ Unless required by applicable law or agreed to in writing, + ~ software distributed under the License is distributed on an + ~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + ~ KIND, either express or implied. See the License for the + ~ specific language governing permissions and limitations + ~ under the License. + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~--> +<chapter xmlns="http://docbook.org/ns/docbook"; xmlns:xlink="http://www.w3.org/1999/xlink"; + version="5.0" xml:id="ext-jcache"> + <title>JCache integration</title> + <section> + <title>Description</title> + <para>This module allows integrate any JCache (JSR 107) compatible caching provider with Cayenne.</para> + </section> + <section> + <title>Including in a Project</title> + <section> + <title>Maven</title> + <para> + <programlisting language="xml"><dependency> + <groupId>org.apache.cayenne</groupId> + <artifactId>cayenne-jcache</artifactId> + <version><?eval ${project.version}?></version> +</dependency></programlisting> + </para> + </section> + <section> + <title>Gradle</title> + <para> + <programlisting language="groovy">compile 'org.apache.cayenne:cayenne-jcache:<?eval ${project.version}?>'</programlisting> + </para> + </section> + </section> + <section> + <title>Usage</title> + <para> + All you need is to include this module and any compatible caching provider (e.g. Ehcache). + If required you can provide own implementation of <code>org.apache.cayenne.jcache.JCacheConfigurationFactory</code> + to customize cache configuration. + </para> + <para> + For advanced configuration and management please use provider specific options and tools. + </para> + <note> + <para>You can read about using cache in Cayenne in <link linkend="caching-and-fresh-data">this</link> chapter.</para> + <para>You may alse be interested in <link linkend="ext-cache-invalidation">cache invalidation</link> extension.</para> + </note> + </section> +</chapter> http://git-wip-us.apache.org/repos/asf/cayenne/blob/562aac45/docs/docbook/cayenne-guide/src/docbkx/ext-joda.xml ---------------------------------------------------------------------- diff --git a/docs/docbook/cayenne-guide/src/docbkx/ext-joda.xml b/docs/docbook/cayenne-guide/src/docbkx/ext-joda.xml new file mode 100644 index 0000000..47fd080 --- /dev/null +++ b/docs/docbook/cayenne-guide/src/docbkx/ext-joda.xml @@ -0,0 +1,53 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!--~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + ~ Licensed to the Apache Software Foundation (ASF) under one + ~ or more contributor license agreements. See the NOTICE file + ~ distributed with this work for additional information + ~ regarding copyright ownership. The ASF licenses this file + ~ to you under the Apache License, Version 2.0 (the + ~ "License"); you may not use this file except in compliance + ~ with the License. You may obtain a copy of the License at + ~ + ~ http://www.apache.org/licenses/LICENSE-2.0 + ~ + ~ Unless required by applicable law or agreed to in writing, + ~ software distributed under the License is distributed on an + ~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + ~ KIND, either express or implied. See the License for the + ~ specific language governing permissions and limitations + ~ under the License. + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~--> +<chapter xmlns="http://docbook.org/ns/docbook"; xmlns:xlink="http://www.w3.org/1999/xlink"; + version="5.0" xml:id="ext-joda"> + <title>Joda time extension</title> + <section> + <title>Description</title> + <para>Joda time module allows to use <code>org.joda.time.LocalTime</code>, <code>org.joda.time.LocalDate</code>, + <code>org.joda.time.LocalDateTime</code> and <code>org.joda.time.DateTime</code> types for entity attributes</para> + </section> + <section> + <title>Including in a Project</title> + <section> + <title>Maven</title> + <para> + <programlisting language="xml"><dependency> + <groupId>org.apache.cayenne</groupId> + <artifactId>cayenne-joda</artifactId> + <version><?eval ${project.version}?></version> +</dependency></programlisting> + </para> + </section> + <section> + <title>Gradle</title> + <para> + <programlisting language="groovy">compile 'org.apache.cayenne:cayenne-joda:<?eval ${project.version}?>'</programlisting> + </para> + </section> + </section> + <section> + <title>Usage</title> + <para> + This module doesn't require any additional setup, you can just use new data types in your model. + </para> + </section> +</chapter> http://git-wip-us.apache.org/repos/asf/cayenne/blob/562aac45/docs/docbook/cayenne-guide/src/docbkx/ext-project-compatibility.xml ---------------------------------------------------------------------- diff --git a/docs/docbook/cayenne-guide/src/docbkx/ext-project-compatibility.xml b/docs/docbook/cayenne-guide/src/docbkx/ext-project-compatibility.xml new file mode 100644 index 0000000..eb8fb73 --- /dev/null +++ b/docs/docbook/cayenne-guide/src/docbkx/ext-project-compatibility.xml @@ -0,0 +1,59 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!--~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + ~ Licensed to the Apache Software Foundation (ASF) under one + ~ or more contributor license agreements. See the NOTICE file + ~ distributed with this work for additional information + ~ regarding copyright ownership. The ASF licenses this file + ~ to you under the Apache License, Version 2.0 (the + ~ "License"); you may not use this file except in compliance + ~ with the License. You may obtain a copy of the License at + ~ + ~ http://www.apache.org/licenses/LICENSE-2.0 + ~ + ~ Unless required by applicable law or agreed to in writing, + ~ software distributed under the License is distributed on an + ~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + ~ KIND, either express or implied. See the License for the + ~ specific language governing permissions and limitations + ~ under the License. + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~--> +<chapter xmlns="http://docbook.org/ns/docbook"; xmlns:xlink="http://www.w3.org/1999/xlink"; + version="5.0" xml:id="ext-project-compatibility"> + <title>Project compatibility extension</title> + <section> + <title>Description</title> + <para>Since version <emphasis>4.1</emphasis> Cayenne doesn't allow to load project XML files + from previous versions as this can lead to unexpected errors in runtime. This module allows to + use project files from older versions performing their upgrade on the fly. + This can be useful when using Caynnne models from third-party libraries in your app. + <note> + <para>You should prefer explicit project upgrade via Cayenne Modeler.</para> + </note> + </para> + </section> + <section> + <title>Including in a Project</title> + <section> + <title>Maven</title> + <para> + <programlisting language="xml"><dependency> + <groupId>org.apache.cayenne</groupId> + <artifactId>cayenne-project-compatibility</artifactId> + <version><?eval ${project.version}?></version> +</dependency></programlisting> + </para> + </section> + <section> + <title>Gradle</title> + <para> + <programlisting language="groovy">compile 'org.apache.cayenne:cayenne-project-compatibility:<?eval ${project.version}?>'</programlisting> + </para> + </section> + </section> + <section> + <title>Usage</title> + <para> + This module doesn't require any additional setup. + </para> + </section> +</chapter> http://git-wip-us.apache.org/repos/asf/cayenne/blob/562aac45/docs/docbook/cayenne-guide/src/docbkx/ext-velocity.xml ---------------------------------------------------------------------- diff --git a/docs/docbook/cayenne-guide/src/docbkx/ext-velocity.xml b/docs/docbook/cayenne-guide/src/docbkx/ext-velocity.xml new file mode 100644 index 0000000..5ddfc98 --- /dev/null +++ b/docs/docbook/cayenne-guide/src/docbkx/ext-velocity.xml @@ -0,0 +1,79 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!--~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + ~ Licensed to the Apache Software Foundation (ASF) under one + ~ or more contributor license agreements. See the NOTICE file + ~ distributed with this work for additional information + ~ regarding copyright ownership. The ASF licenses this file + ~ to you under the Apache License, Version 2.0 (the + ~ "License"); you may not use this file except in compliance + ~ with the License. You may obtain a copy of the License at + ~ + ~ http://www.apache.org/licenses/LICENSE-2.0 + ~ + ~ Unless required by applicable law or agreed to in writing, + ~ software distributed under the License is distributed on an + ~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + ~ KIND, either express or implied. See the License for the + ~ specific language governing permissions and limitations + ~ under the License. + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~--> +<chapter xmlns="http://docbook.org/ns/docbook"; xmlns:xlink="http://www.w3.org/1999/xlink"; + version="5.0" xml:id="ext-velocity"> + <title>Apache Velocity extension</title> + <section> + <title>Description</title> + <para>This module enables usage of full featured Apache Velocity templates in <code>org.apache.cayenne.query.SQLTemplate</code> + queries.</para> + </section> + <section> + <title>Including in a Project</title> + <section> + <title>Maven</title> + <para> + <programlisting language="xml"><dependency> + <groupId>org.apache.cayenne</groupId> + <artifactId>cayenne-velocity</artifactId> + <version><?eval ${project.version}?></version> +</dependency></programlisting> + </para> + </section> + <section> + <title>Gradle</title> + <para> + <programlisting language="groovy">compile 'org.apache.cayenne:cayenne-velocity:<?eval ${project.version}?>'</programlisting> + </para> + </section> + </section> + <section> + <title>Usage</title> + <para> + This module doesn't require any additional setup. + </para> + <para> + In addition of directives mentioned in <link linkend="sqltemplate-bind-directive">this</link> chapter, this module enables <code>#chain</code> and <code>#chunk</code> + directives. + </para> + <para><code>#chain</code> and <code>#chunk</code> directives are used for + conditional inclusion of SQL code. They are used together with + <code>#chain</code> wrapping multiple <code>#chunks</code>. A chunk + evaluates its parameter expression and if it is NULL suppresses rendering of the + enclosed SQL block. A chain renders its prefix and its chunks joined by the + operator. If all the chunks are suppressed, the chain itself is suppressed. This + allows to work with otherwise hard to script SQL semantics. E.g. a WHERE clause + can contain multiple conditions joined with AND or OR. Application code would + like to exclude a condition if its right-hand parameter is not present (similar + to Expression pruning discussed above). If all conditions are excluded, the + entire WHERE clause should be excluded. chain/chunk allows to do that.</para> + <para> + <emphasis role="italic" + >Semantics</emphasis>:<programlisting language="java">#chain(operator) ... #end +#chain(operator prefix) ... #end +#chunk() ... #end +#chunk(param) ... #end </programlisting></para> + <para><emphasis role="italic">Full + example:</emphasis><programlisting language="java">#chain('OR' 'WHERE') + #chunk($name) NAME LIKE #bind($name) #end + #chunk($id) ARTIST_ID > #bind($id) #end +#end" </programlisting></para> + </section> +</chapter> http://git-wip-us.apache.org/repos/asf/cayenne/blob/562aac45/docs/docbook/cayenne-guide/src/docbkx/index.xml ---------------------------------------------------------------------- diff --git a/docs/docbook/cayenne-guide/src/docbkx/index.xml b/docs/docbook/cayenne-guide/src/docbkx/index.xml index b3dc9f2..8ac6c61 100644 --- a/docs/docbook/cayenne-guide/src/docbkx/index.xml +++ b/docs/docbook/cayenne-guide/src/docbkx/index.xml @@ -42,6 +42,7 @@ <xi:include href="part2.xml"/> <xi:include href="part3.xml"/> <xi:include href="part4.xml"/> + <xi:include href="part5.xml"/> <xi:include href="appendix-a.xml"/> <xi:include href="appendix-b.xml"/> <xi:include href="appendix-c.xml"/> http://git-wip-us.apache.org/repos/asf/cayenne/blob/562aac45/docs/docbook/cayenne-guide/src/docbkx/part5.xml ---------------------------------------------------------------------- diff --git a/docs/docbook/cayenne-guide/src/docbkx/part5.xml b/docs/docbook/cayenne-guide/src/docbkx/part5.xml new file mode 100644 index 0000000..67919f9 --- /dev/null +++ b/docs/docbook/cayenne-guide/src/docbkx/part5.xml @@ -0,0 +1,32 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!--~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + ~ Licensed to the Apache Software Foundation (ASF) under one + ~ or more contributor license agreements. See the NOTICE file + ~ distributed with this work for additional information + ~ regarding copyright ownership. The ASF licenses this file + ~ to you under the Apache License, Version 2.0 (the + ~ "License"); you may not use this file except in compliance + ~ with the License. You may obtain a copy of the License at + ~ + ~ http://www.apache.org/licenses/LICENSE-2.0 + ~ + ~ Unless required by applicable law or agreed to in writing, + ~ software distributed under the License is distributed on an + ~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + ~ KIND, either express or implied. See the License for the + ~ specific language governing permissions and limitations + ~ under the License. + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~--> +<part xmlns="http://docbook.org/ns/docbook"; xmlns:xlink="http://www.w3.org/1999/xlink"; version="5.0" + xml:id="cayenne-guide-part5" xmlns:xi="http://www.w3.org/2001/XInclude";> + <title>Cayenne Additional Modules</title> + <xi:include href="ext-cache-invalidation.xml"/> + <xi:include href="ext-commit-log.xml"/> + <xi:include href="ext-crypto.xml"/> + <xi:include href="ext-dbcp2.xml"/> + <xi:include href="ext-java8.xml"/> + <xi:include href="ext-jcache.xml"/> + <xi:include href="ext-joda.xml"/> + <xi:include href="ext-project-compatibility.xml"/> + <xi:include href="ext-velocity.xml"/> +</part> http://git-wip-us.apache.org/repos/asf/cayenne/blob/562aac45/docs/docbook/cayenne-guide/src/docbkx/queries-sqltemplate.xml ---------------------------------------------------------------------- diff --git a/docs/docbook/cayenne-guide/src/docbkx/queries-sqltemplate.xml b/docs/docbook/cayenne-guide/src/docbkx/queries-sqltemplate.xml index 4d0b21c..bbfa559 100644 --- a/docs/docbook/cayenne-guide/src/docbkx/queries-sqltemplate.xml +++ b/docs/docbook/cayenne-guide/src/docbkx/queries-sqltemplate.xml @@ -281,33 +281,9 @@ select.setParameters(Collections.singletonMap("a", a)); </programlisting></para> #result('SALARY' 'float') </programlisting></para> <para><emphasis role="italic">Full example:</emphasis><programlisting language="sql">SELECT #result('ID' 'int'), #result('NAME' 'String'), #result('DATE_OF_BIRTH' 'java.util.Date') FROM ARTIST</programlisting></para> - </section> - <section> - <title>#chain and #chunk</title> - - <para><code>#chain</code> and <code>#chunk</code> directives are used for - conditional inclusion of SQL code. They are used together with - <code>#chain</code> wrapping multiple <code>#chunks</code>. A chunk - evaluates its parameter expression and if it is NULL suppresses rendering of the - enclosed SQL block. A chain renders its prefix and its chunks joined by the - operator. If all the chunks are suppressed, the chain itself is suppressed. This - allows to work with otherwise hard to script SQL semantics. E.g. a WHERE clause - can contain multiple conditions joined with AND or OR. Application code would - like to exclude a condition if its right-hand parameter is not present (similar - to Expression pruning discussed above). If all conditions are excluded, the - entire WHERE clause should be excluded. chain/chunk allows to do that.</para> - <para> - <emphasis role="italic" - >Semantics</emphasis>:<programlisting language="java">#chain(operator) ... #end -#chain(operator prefix) ... #end -#chunk() ... #end -#chunk(param) ... #end </programlisting></para> - <para><emphasis role="italic">Full - example:</emphasis><programlisting language="java">#chain('OR' 'WHERE') - #chunk($name) NAME LIKE #bind($name) #end - #chunk($id) ARTIST_ID > #bind($id) #end -#end" </programlisting></para> - + <note> + <para>For advanced features you may look at the <link linkend="ext-velocity">Apache Velocity extension</link></para> + </note> </section> </section> <section> http://git-wip-us.apache.org/repos/asf/cayenne/blob/562aac45/docs/docbook/cayenne-guide/src/docbkx/setup.xml ---------------------------------------------------------------------- diff --git a/docs/docbook/cayenne-guide/src/docbkx/setup.xml b/docs/docbook/cayenne-guide/src/docbkx/setup.xml index 023004e..ba804a6 100644 --- a/docs/docbook/cayenne-guide/src/docbkx/setup.xml +++ b/docs/docbook/cayenne-guide/src/docbkx/setup.xml @@ -38,6 +38,11 @@ <th>Status</th> </tr> <tr> + <td>4.1</td> + <td>Java 1.8 or newer</td> + <td>Development</td> + </tr> + <tr> <td>4.0</td> <td>Java 1.7 or newer</td> <td>Beta</td> http://git-wip-us.apache.org/repos/asf/cayenne/blob/562aac45/docs/docbook/cayenne-guide/src/images/ext-crypto-obj-entity.png ---------------------------------------------------------------------- diff --git a/docs/docbook/cayenne-guide/src/images/ext-crypto-obj-entity.png b/docs/docbook/cayenne-guide/src/images/ext-crypto-obj-entity.png new file mode 100644 index 0000000..2d8c32a Binary files /dev/null and b/docs/docbook/cayenne-guide/src/images/ext-crypto-obj-entity.png differ http://git-wip-us.apache.org/repos/asf/cayenne/blob/562aac45/docs/docbook/cayenne-guide/src/images/ext-dbcp-setup.png ---------------------------------------------------------------------- diff --git a/docs/docbook/cayenne-guide/src/images/ext-dbcp-setup.png b/docs/docbook/cayenne-guide/src/images/ext-dbcp-setup.png new file mode 100644 index 0000000..f681b9d Binary files /dev/null and b/docs/docbook/cayenne-guide/src/images/ext-dbcp-setup.png differ http://git-wip-us.apache.org/repos/asf/cayenne/blob/562aac45/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 1ae6b9a..6481ae3 100644 --- a/docs/docbook/upgrade-guide/src/docbkx/new-features.xml +++ b/docs/docbook/upgrade-guide/src/docbkx/new-features.xml @@ -33,7 +33,7 @@ <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 language="java">ServerRuntime runtime = new ServerRuntimeBuilder("myproject") + E.g.:<programlisting language="java">ServerRuntime runtime = ServerRuntime.builder("myproject") .addConfigs("cayenne-project1.xml", "cayenne-project2.xml") .addModule(binder -> binder.bind(JdbcEventLogger.class).toInstance(myLogger)) .dataSource(myDataSource) @@ -50,7 +50,8 @@ decorators. True to the "smallest-footprint" DI philosophy, decorator approach is very simple and does not require proxies or class enhancement. Just implement the decorated interface and provide a constructor that takes a delegate instance being - decorated:<programlisting language="java">public class MyInterfaceDecorator implements MyInterface { + decorated: + <programlisting language="java">public class MyInterfaceDecorator implements MyInterface { private MyInterface delegate; @@ -64,13 +65,9 @@ } } -Module module = new Module() { - - @Override - public void configure(Binder binder) { - binder.decorate(MyInterface.class).before(MyInterfaceDecorator.class); - } -};</programlisting></para> +Module module = binder -> + binder.decorate(MyInterface.class).before(MyInterfaceDecorator.class);</programlisting> + </para> </section> </section> <section xml:id="framework-api"> @@ -88,6 +85,17 @@ Module module = new Module() { .selectOne(context);</programlisting></para> </section> <section> + <title>ColumnSelect</title> + <para> + This query allows you directly access individual properties of Objects and use functions (including aggregate) + via type-safe API. + <programlisting language="java"><![CDATA[List<String> names = ObjectSelect + .columnQuery(Artist.class, Artist.ARTIST_NAME) + .where(Artist.ARTIST_NAME.length().gt(6)) + .select(context);]]></programlisting> + </para> + </section> + <section> <title>SQLSelect</title> <para>A "chainable" analog of SQLTemplate used specifically to run selecting raw SQL:<programlisting language="java">List<Long> ids = SQLSelect @@ -161,10 +169,10 @@ Expression e = ExpressionFactory.exp( 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 language="java">Module cryptoExtensions = new CryptoModuleBuilder() + ServerRuntime:<programlisting language="java">Module cryptoExtensions = CryptoModule.extend() .keyStore("file:///mykeystore", "keystorepassword".toCharArray(), "keyalias") .compress() - .build();</programlisting></para> + .module();</programlisting></para> </section> </section> <section xml:id="cayenne-modeler"> @@ -179,6 +187,7 @@ Expression e = ExpressionFactory.exp( <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 language="java">runtime.getDataDomain().addListener(myListener);</programlisting> + or via DI: <programlisting language="java"><![CDATA[Module module = binder -> ServerModule.contributeDomainListeners(myListener);]]></programlisting> Entity callbacks on the other hand are managed in the Modeler as before.</para> </section> </section> @@ -199,5 +208,31 @@ Expression e = ExpressionFactory.exp( <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> + <title>Gradle Plugin</title> + <para> + Cayenne now provides it's own Gradle Plugin that allows you easily integrate <code>cdbimport</code> + and <code>cgen</code> tools into your build process. + Here is example of it's usage: + <programlisting language="groovy"> +buildscript { + repositories { + mavenCentral() + } + dependencies { + classpath group: 'org.apache.cayenne.plugins', name: 'cayenne-gradle-plugin', version: '<?eval ${project.version}?>' + } +} + +apply plugin: 'org.apache.cayenne' + +cayenne.defaultDataMap 'datamap.map.xml' + +dependencies { + compile cayenne.dependency('server') + compile cayenne.dependency('java8') +}</programlisting> + </para> + </section> </section> </article>
