Repository: cayenne Updated Branches: refs/heads/STABLE-3.1 4cc7a6eec -> 7783cd34a
http://git-wip-us.apache.org/repos/asf/cayenne/blob/7783cd34/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 deleted file mode 100644 index 3251d5d..0000000 --- a/docs/docbook/upgrade-guide/src/docbkx/new-features.xml +++ /dev/null @@ -1,162 +0,0 @@ -<?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. ---> -<article xmlns="http://docbook.org/ns/docbook"; - xmlns:xlink="http://www.w3.org/1999/xlink"; version="5.0"> - <title>Guide to 3.1 Features</title> - <para>This guide highlights the new features and changes introduced in 3.1 release. It is a - high-level overview. For more details consult <emphasis role="bold" - >RELEASE-NOTES.txt</emphasis> file included in each release for the full list of - changes, and <emphasis role="bold">UPGRADE.txt</emphasis> for the release-specific upgrade - instructions.</para> - <section xml:id="ditribution-content-structure"> - <title>Distribution Contents Structure</title> - <para>Cayenne distribution is made leaner and more modular:</para> - <itemizedlist> - <listitem> - <para>"cayenne-modeler.jar" is no longer included in the "lib" folder, as it is no - longer used for loading local JNDI overrides. Of course "CayenneModeler-the-app" - is still included.</para> - </listitem> - <listitem> - <para>Ashwood library used for commit operation sorting is no longer a third-party - dependency. Instead a small subset of the relevant Ashwood classes got included - in Cayenne core.</para> - </listitem> - <listitem> - <para>The following helper modules are split away from Cayenne core: - "cayenne-project" and "cayenne-wocompat". They are bundled in CayenneModeler, - and are available from the source distribution. They are not included as - standalone jars in the binary distribution.</para> - </listitem> - </itemizedlist> - </section> - <section xml:id="cayenne-configuration"> - <title>Cayenne Configuration</title> - - <note><para>The new DI-based bootstrap and configuration - approach is not API-compatible with earlier versions of Cayenne. Make sure - you read the UPGRADE.txt file for instructions how to upgrade the existing - projects.</para></note> - <section> - <title>Dependency Injection Container</title> - <para>Cayenne 3.1 runtime stack is built around the ideas of Dependency Injection (DI), - making it extremely flexible and easy to extend. It bundles a small, flexible - annotations-based DI container to configure its services. The container provides DI - services and exposes Cayenne extension points, but does not interfere with other DI - containers that may be present in the application. I.e. it is invisible to the users - who do not care about advanced Cayenne customization.</para> - </section> - <section> - <title>Bootstrapping Cayenne in Various Environments</title> - <para> Here is a simple example of starting a server-side Cayenne stack:</para> - <programlisting language="java">ServerRuntime runtime = new ServerRuntime("cayenne-UntitledDomain.xml");</programlisting> - <para>For more detailed examples check the tutorials and other documentation.</para> - </section> - <section> - <title>Configuring Local DataSources, Removal of JNDI Hack</title> - <para>Cayenne 3.1 provides a property-based mechanism to override Modeler DataSource - definitions, regardless of whether they are driver configurations, JNDI, DBCP, etc. - A quick configuration example is shown below:</para> - <programlisting>-Dcayenne.jdbc.driver=com.mysql.jdbc.Driver -Dcayenne.jdbc.url=jdbc:mysql://localhost/mydb \ --Dcayenne.jdbc.username=user -Dcayenne.jdbc.password=password</programlisting> - <para>For more details and configuration options see javadocs of - org.apache.cayenne.configuration.server.PropertyDataSourceFactory. </para> - <para>This feature supersedes what was formerly known as "JNDI hack", i.e. JNDI - DataSource failover load strategy based on CayenneModeler preferences database. The - problem with JNDI hack was unstable and frequently corrupted preferences database, - and the need to include hsqldb and cayenne-modeler jars in the runtime. </para> - </section> - </section> - <section xml:id="framework-api"> - <title>Framework API</title> - <para> - <emphasis role="italic">See UPGRADE.txt for the full list of changes</emphasis> - </para> - <section> - <title>Lifecycle Listener Annotations</title> - <para>Cayenne 3.1 features support for annotations on lifecycle listeners (but not yet - on entity callback methods) that simplifies registering listeners via API. Our - experience with Cayenne 3.0 shows that mapping listeners in the Modeler doesn't - scale well to complex applications, and 3.0 API for mapping the listeners is hard to - use. In 3.1 you can annotate listener methods and register multiple callback methods - with a single call. </para> - <programlisting language="java">// declare a listener with annotated methods -class MyListener { - @PostLoad(Entity1.class) - @PostPersist(Entity1.class) - void postLoad(Object object) { - .... - } -} - -// register a listener -ServerRuntime runtime = .. -MyListener listener = new MyListener(); -runtime.getChannel().getEntityResolver().getCallbackRegistry().addListener(listener);</programlisting> - <para>Moreover, unlike JPA annotations, Cayenne allows to attach a listener to a set of - entities not known to the listener upfront, but that are all annotated with some - custom annotation:</para> - <programlisting language="java">class MyListener { - @PostLoad(entityAnnotations = CustomAnnotation.class) - void postLoad(Object object) { - .... - } -}</programlisting> - </section> - <section> - <title>DataChannelFilter for Intercepting DataDomain Operations</title> - <para>Cayenne now features a DataChannelFilter interface that allows to intercept and - alter all DataChannel traffic (i.e. selects and commits between a DataContext and - DataDomain). It provides a chain of command API very similar to servlet filters. - Filters are widely used by "cayenne-lifecyle" extensions and allow to build powerful - custom object lifecycle-aware code. To install a filter, the following API is - used:</para> - <programlisting language="java">class MyFilter implement DataChannelFilter { .. } - -MyFilter filter = new MyFilter(); -ServerRuntime runtime = .. -runtime.getDataDomain().addFilter(filter);</programlisting> - <para>Very often filters mark some of their own methods with lifecycle annotations so - that certain operations can be triggered by Cayenne inside the scope of filter's - onQuery() or onSync() methods. To ensure annotated methods are invoked, filter - registration should be combined with listener registration:</para> - <programlisting language="java">MyFilter filter = new MyFilter(); -ServerRuntime runtime = .. -runtime.getDataDomain().addFilter(filter); -runtime.getDataDomain().getEntityResolver().getCallbackRegistry().addListener(filter); -// noticed that by default runtime.getDataDomain() is equivalent to runtime.getChannel()</programlisting> - </section> - </section> - <section xml:id="cayenne-modeler"> - <title>CayenneModeler</title> - <section> - <title>Java Preferences API</title> - <para>We got rid of HSQLDB-based preferences storage, and are using standard Java - Preferences API for the Modeler preferences. This solved a long-standing stability - issue with Modeler preferences. So no more lost user preferences.</para> - </section> - </section> - <section xml:id="lifecycle-extensions"> - <title>Lifecycle Extensions</title> - <para>Cayenne 3.1 includes an optional cayenne-lifecyle module that implements a few useful - extensions based on DataChannelFilters and lifecycle annotations. Those include a - concept of a String ID (which is a String URL-friendly representation of ObjectId), - support for (de)referencing objects by String ID, String ID-based relationships, - annotation-based cache groups invalidation, annotation-based audit of object changes, - etc.</para> - </section> -</article> http://git-wip-us.apache.org/repos/asf/cayenne/blob/7783cd34/docs/docbook/upgrade-guide/src/images/.gitignore ---------------------------------------------------------------------- diff --git a/docs/docbook/upgrade-guide/src/images/.gitignore b/docs/docbook/upgrade-guide/src/images/.gitignore deleted file mode 100644 index 126477b..0000000 --- a/docs/docbook/upgrade-guide/src/images/.gitignore +++ /dev/null @@ -1,2 +0,0 @@ -# keeping this here to ensure the empty folder is present -# it is expected by a shared docbook plugin config http://git-wip-us.apache.org/repos/asf/cayenne/blob/7783cd34/docs/pom.xml ---------------------------------------------------------------------- diff --git a/docs/pom.xml b/docs/pom.xml index 8e76392..167c2da 100644 --- a/docs/pom.xml +++ b/docs/pom.xml @@ -35,7 +35,7 @@ <modules> <module>doc</module> - <module>docbook</module> + <module>asciidoc</module> </modules> <build> http://git-wip-us.apache.org/repos/asf/cayenne/blob/7783cd34/tutorials/tutorial/src/main/java/org/apache/cayenne/tutorial/Main.java ---------------------------------------------------------------------- diff --git a/tutorials/tutorial/src/main/java/org/apache/cayenne/tutorial/Main.java b/tutorials/tutorial/src/main/java/org/apache/cayenne/tutorial/Main.java index 7fde457..24daec6 100644 --- a/tutorials/tutorial/src/main/java/org/apache/cayenne/tutorial/Main.java +++ b/tutorials/tutorial/src/main/java/org/apache/cayenne/tutorial/Main.java @@ -52,11 +52,14 @@ public class Main { static void newObjectsTutorial(ObjectContext context) { // creating new Artist + // tag::new-artist[] Artist picasso = context.newObject(Artist.class); picasso.setName("Pablo Picasso"); picasso.setDateOfBirthString("18811025"); + // end::new-artist[] // Creating other objects + // tag::new-painting[] Gallery metropolitan = context.newObject(Gallery.class); metropolitan.setName("Metropolitan Museum of Art"); @@ -65,16 +68,21 @@ public class Main { Painting stein = context.newObject(Painting.class); stein.setName("Gertrude Stein"); + // end::new-painting[] // connecting objects together via relationships + // tag::link-objects[] picasso.addToPaintings(girl); picasso.addToPaintings(stein); girl.setGallery(metropolitan); stein.setGallery(metropolitan); + // end::link-objects[] // saving all the changes above + // tag::commit[] context.commitChanges(); + // end::commit[] } static void selectTutorial(ObjectContext context) { http://git-wip-us.apache.org/repos/asf/cayenne/blob/7783cd34/tutorials/tutorial/src/main/java/org/apache/cayenne/tutorial/persistent/Artist.java ---------------------------------------------------------------------- diff --git a/tutorials/tutorial/src/main/java/org/apache/cayenne/tutorial/persistent/Artist.java b/tutorials/tutorial/src/main/java/org/apache/cayenne/tutorial/persistent/Artist.java index 8846edc..d9f8cf7 100644 --- a/tutorials/tutorial/src/main/java/org/apache/cayenne/tutorial/persistent/Artist.java +++ b/tutorials/tutorial/src/main/java/org/apache/cayenne/tutorial/persistent/Artist.java @@ -24,6 +24,7 @@ import java.util.Date; import org.apache.cayenne.tutorial.persistent.auto._Artist; +// tag::content[] public class Artist extends _Artist { static final String DEFAULT_DATE_FORMAT = "yyyyMMdd"; @@ -50,3 +51,4 @@ public class Artist extends _Artist { } } } +// end::content[] \ No newline at end of file http://git-wip-us.apache.org/repos/asf/cayenne/blob/7783cd34/tutorials/tutorial/src/main/webapp/detail.jsp ---------------------------------------------------------------------- diff --git a/tutorials/tutorial/src/main/webapp/detail.jsp b/tutorials/tutorial/src/main/webapp/detail.jsp index d031a8d..7e87096 100644 --- a/tutorials/tutorial/src/main/webapp/detail.jsp +++ b/tutorials/tutorial/src/main/webapp/detail.jsp @@ -24,6 +24,7 @@ <%@ page import="java.util.*" %> <%@ page import="java.text.*" %> +// tag::content[] <% ObjectContext context = BaseContext.getThreadObjectContext(); String id = request.getParameter("id"); @@ -84,4 +85,5 @@ </table> </form> </body> -</html> \ No newline at end of file +</html> +// end::content[] \ No newline at end of file http://git-wip-us.apache.org/repos/asf/cayenne/blob/7783cd34/tutorials/tutorial/src/main/webapp/index.jsp ---------------------------------------------------------------------- diff --git a/tutorials/tutorial/src/main/webapp/index.jsp b/tutorials/tutorial/src/main/webapp/index.jsp index da44af1..5876fe4 100644 --- a/tutorials/tutorial/src/main/webapp/index.jsp +++ b/tutorials/tutorial/src/main/webapp/index.jsp @@ -25,6 +25,7 @@ <%@ page import="org.apache.cayenne.exp.*" %> <%@ page import="java.util.*" %> +// tag::content[] <% SelectQuery query = new SelectQuery(Artist.class); query.addOrdering(Artist.NAME_PROPERTY, SortOrder.ASCENDING); @@ -51,4 +52,5 @@ <hr> <p><a href="detail.jsp">Create new artist...</a></p> </body> -</html> \ No newline at end of file +</html> +// end::content[] \ No newline at end of file
