cayenne-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ntimof...@apache.org
Subject [01/11] cayenne git commit: CAY-2371 Switch documentation from Docbook to Asciidoctor format
Date Fri, 05 Jan 2018 14:21:29 GMT
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


Mime
View raw message