You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@cayenne.apache.org by nt...@apache.org on 2018/01/05 13:10:28 UTC
[01/13] cayenne git commit: CAY-2371 Switch documentation from
Docbook to Asciidoctor format
Repository: cayenne
Updated Branches:
refs/heads/STABLE-4.0 2f472cea0 -> cde78f0b4
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/getting-started/src/docbkx/webapp.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/getting-started/src/docbkx/webapp.xml b/docs/docbook/getting-started/src/docbkx/webapp.xml
deleted file mode 100644
index bab9815..0000000
--- a/docs/docbook/getting-started/src/docbkx/webapp.xml
+++ /dev/null
@@ -1,308 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<?xml-model href="http://www.oasis-open.org/docbook/xml/5.0/rng/docbook.rng" schematypens="http://relaxng.org/ns/structure/1.0"?>
-<!--
- 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.
--->
-<section xmlns="http://docbook.org/ns/docbook"
- xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0">
- <title>Converting to Web Application</title>
- <para>This chapter shows how to work with Cayenne in a web application.</para>
- <section xml:id="converting-to-webapp">
- <title>Converting Tutorial to a Web Application</title>
- <para>The web part of the web application tutorial is done in JSP, which is the least common
- denominator of the Java web technologies, and is intentionally simplistic from the UI
- perspective, to concentrate on Cayenne integration aspect, rather than the interface. A
- typical Cayenne web application works like this:</para>
- <itemizedlist>
- <listitem>
- <para>Cayenne configuiration is loaded when an application context is started, using
- a special servlet filter.</para>
- </listitem>
- <listitem>
- <para>User requests are intercepted by the filter, and the DataContext is bound to
- the request thread, so the application can access it easily from
- anywhere.</para>
- </listitem>
- <listitem>
- <para>The same DataContext instance is reused within a single user session;
- different sessions use different DataContexts (and therefore different sets of
- objects). <emphasis role="italic">The context can be scoped differently
- depending on the app specifics. For the tutorial we'll be using a
- session-scoped context.</emphasis></para>
- </listitem>
- </itemizedlist>
- <para>So let's convert the tutorial that we created to a web application:</para>
- <itemizedlist>
- <listitem>
- <para>In IDEA under "tutorial" project folder create a new folder
- "<code>src/main/webapp/WEB-INF</code>".</para>
- </listitem>
- <listitem>
- <para>Under "<code>WEB-INF</code>" create a new file "<code>web.xml</code>" (a standard web app descriptor): </para>
- <para>
- <emphasis role="bold">web.xml</emphasis>
- <programlisting language="xml"><?xml version="1.0" encoding="utf-8"?>
- <!DOCTYPE web-app
- PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
- "http://java.sun.com/dtd/web-app_2_3.dtd">
-<web-app>
- <display-name>Cayenne Tutorial</display-name>
-
- <!-- This filter bootstraps ServerRuntime and then provides each request thread
- with a session-bound DataContext. Note that the name of the filter is important,
- as it points it to the right named configuration file.
- -->
- <filter>
- <filter-name>cayenne-project</filter-name>
- <filter-class>org.apache.cayenne.configuration.web.CayenneFilter</filter-class>
- </filter>
- <filter-mapping>
- <filter-name>cayenne-project</filter-name>
- <url-pattern>/*</url-pattern>
- </filter-mapping>
- <welcome-file-list>
- <welcome-file>index.jsp</welcome-file>
- </welcome-file-list>
-</web-app></programlisting></para>
- </listitem>
- <listitem>
- <para>Create the artist browser page <code>src/main/webapp/index.jsp</code> file with the
- following contents: </para>
- <para><emphasis role="bold">webapp/index.jsp</emphasis>
- <programlisting language="jsp"><%@ page language="java" contentType="text/html" %>
-<%@ page import="org.example.cayenne.persistent.*" %>
-<%@ page import="org.apache.cayenne.*" %>
-<%@ page import="org.apache.cayenne.query.*" %>
-<%@ page import="org.apache.cayenne.exp.*" %>
-<%@ page import="java.util.*" %>
-
-<%
- ObjectContext context = BaseContext.getThreadObjectContext();
- List<Artist> artists = ObjectSelect.query(Artist.class)
- .orderBy(Artist.NAME.asc())
- .select(context);
-%>
-
-<html>
- <head>
- <title>Main</title>
- </head>
- <body>
- <h2>Artists:</h2>
-
- <% if(artists.isEmpty()) {%>
- <p>No artists found</p>
- <% } else {
- for(Artist a : artists) {
- %>
- <p><a href="detail.jsp?id=<%=Cayenne.intPKForObject(a)%>"> <%=a.getName()%> </a></p>
- <%
- }
- } %>
- <hr>
- <p><a href="detail.jsp">Create new artist...</a></p>
- </body>
-</html> </programlisting></para>
- </listitem>
- <listitem>
- <para>Create the artist editor page <code>src/main/webapp/detail.jsp</code> with the following
- content: </para>
- <para><emphasis role="bold">webapp/detail.jsp</emphasis>
- <programlisting language="jsp"><%@ page language="java" contentType="text/html" %>
-<%@ page import="org.example.cayenne.persistent.*" %>
-<%@ page import="org.apache.cayenne.*" %>
-<%@ page import="org.apache.cayenne.query.*" %>
-<%@ page import="java.util.*" %>
-<%@ page import="java.text.*" %>
-<%@ page import="java.time.format.DateTimeFormatter" %>
-
-<%
- ObjectContext context = BaseContext.getThreadObjectContext();
- String id = request.getParameter("id");
-
- // find artist for id
- Artist artist = null;
- if(id != null && id.trim().length() > 0) {
- artist = SelectById.query(Artist.class, Integer.parseInt(id)).selectOne(context);
- }
-
- if("POST".equals(request.getMethod())) {
- // if no id is saved in the hidden field, we are dealing with
- // create new artist request
- if(artist == null) {
- artist = context.newObject(Artist.class);
- }
-
- // note that in a real application we would so dome validation ...
- // here we just hope the input is correct
- artist.setName(request.getParameter("name"));
- artist.setDateOfBirthString(request.getParameter("dateOfBirth"));
-
- context.commitChanges();
-
- response.sendRedirect("index.jsp");
- }
-
- if(artist == null) {
- // create transient artist for the form response rendering
- artist = new Artist();
- }
-
- String name = artist.getName() == null ? "" : artist.getName();
-
- DateTimeFormatter formatter = DateTimeFormatter.ofPattern("yyyyMMdd");
- String dob = artist.getDateOfBirth() == null
- ? "" :artist.getDateOfBirth().format(formatter);
-%>
-<html>
- <head>
- <title>Artist Details</title>
- </head>
- <body>
- <h2>Artists Details</h2>
- <form name="EditArtist" action="detail.jsp" method="POST">
- <input type="hidden" name="id" value="<%= id != null ? id : "" %>" />
- <table border="0">
- <tr>
- <td>Name:</td>
- <td><input type="text" name="name" value="<%= name %>"/></td>
- </tr>
- <tr>
- <td>Date of Birth (yyyyMMdd):</td>
- <td><input type="text" name="dateOfBirth" value="<%= dob %>"/></td>
- </tr>
- <tr>
- <td></td>
- <td align="right"><input type="submit" value="Save" /></td>
- </tr>
- </table>
- </form>
- </body>
-</html></programlisting></para>
- </listitem>
- </itemizedlist>
- </section>
- <section xml:id="running-webapp">
- <title>Running Web Application</title>
- <para>We need to provide javax servlet-api for our application.</para>
- <programlisting language="xml"><dependency>
- <groupId>javax.servlet</groupId>
- <artifactId>javax.servlet-api</artifactId>
- <version>3.1.0</version>
- <scope>provided</scope>
-</dependency></programlisting>
-
- <para>Also to run the web application we'll use "maven-jetty-plugin". To activate it,
- let's add the following piece of code to the "<code>pom.xml</code>" file, following the "dependencies"
- section and save the POM:</para>
- <programlisting language="xml"><build>
- <plugins>
- <plugin>
- <groupId>org.eclipse.jetty</groupId>
- <artifactId>jetty-maven-plugin</artifactId>
- <version>9.3.14.v20161028</version>
- </plugin>
- </plugins>
-</build></programlisting>
- <itemizedlist>
- <listitem>
- <para>Go to "Select Run/Debug Configuration" menu, and then "Edit Configuration..."</para>
- <para><inlinemediaobject>
- <imageobject>
- <imagedata fileref="images/idea-edit-configurations.png"/>
- </imageobject>
- </inlinemediaobject>
- </para>
- </listitem>
- <listitem>
- <para>Click "+" button and select "Maven". Enter "Name" and "Command line" as shown on screenshot:</para>
- <para><inlinemediaobject>
- <imageobject>
- <imagedata fileref="images/idea-run-configuration.png" scalefit="1" width="100%"/>
- </imageobject>
- </inlinemediaobject></para>
- </listitem>
- </itemizedlist>
- <itemizedlist>
- <listitem>
- <para>Click "Apply" and "Run". On the first execution it may take a few minutes for
- Jetty plugin to download all dependencies, but eventually you'll see the logs
- like this:</para>
- <screen>[INFO] ------------------------------------------------------------------------
-[INFO] Building tutorial 0.0.1-SNAPSHOT
-[INFO] ------------------------------------------------------------------------
-...
-[INFO] Configuring Jetty for project: tutorial
-[INFO] webAppSourceDirectory not set. Trying src/main/webapp
-[INFO] Reload Mechanic: automatic
-[INFO] Classes = /.../tutorial/target/classes
-[INFO] Logging initialized @1617ms
-[INFO] Context path = /
-[INFO] Tmp directory = /.../tutorial/target/tmp
-[INFO] Web defaults = org/eclipse/jetty/webapp/webdefault.xml
-[INFO] Web overrides = none
-[INFO] web.xml file = file:/.../tutorial/src/main/webapp/WEB-INF/web.xml
-[INFO] Webapp directory = /.../tutorial/src/main/webapp
-[INFO] jetty-9.3.0.v20150612
-[INFO] Started o.e.j.m.p.JettyWebAppContext@6872f9c8{/,file:/.../tutorial/src/main/webapp/,AVAILABLE}{file:/.../tutorial/src/main/webapp/}
-[INFO] Started ServerConnector@723875bc{HTTP/1.1,[http/1.1]}{0.0.0.0:8080}
-[INFO] Started @2367ms
-[INFO] Started Jetty Server</screen>
- </listitem>
- </itemizedlist>
- <itemizedlist>
- <listitem>
- <para>So the Jetty container just started.</para>
- </listitem>
- <listitem>
- <para>Now go to <link xlink:href="http://localhost:8080/">http://localhost:8080/</link>
- URL. You should see "No artists found message" in the web browser and
- the following output in the IDEA console:</para>
- <screen>INFO: Loading XML configuration resource from file:/.../tutorial/target/classes/cayenne-project.xml
-INFO: loading user name and password.
-INFO: Connecting to 'jdbc:derby:memory:testdb;create=true' as 'null'
-INFO: +++ Connecting: SUCCESS.
-INFO: setting DataNode 'datanode' as default, used by all unlinked DataMaps
-INFO: Detected and installed adapter: org.apache.cayenne.dba.derby.DerbyAdapter
-INFO: --- transaction started.
-INFO: No schema detected, will create mapped tables
-INFO: CREATE TABLE GALLERY (ID INTEGER NOT NULL, NAME VARCHAR (200), PRIMARY KEY (ID))
-INFO: CREATE TABLE ARTIST (DATE_OF_BIRTH DATE, ID INTEGER NOT NULL, NAME VARCHAR (200), PRIMARY KEY (ID))
-INFO: CREATE TABLE PAINTING (ARTIST_ID INTEGER, GALLERY_ID INTEGER, ID INTEGER NOT NULL,
- NAME VARCHAR (200), PRIMARY KEY (ID))
-INFO: ALTER TABLE PAINTING ADD FOREIGN KEY (ARTIST_ID) REFERENCES ARTIST (ID)
-INFO: ALTER TABLE PAINTING ADD FOREIGN KEY (GALLERY_ID) REFERENCES GALLERY (ID)
-INFO: CREATE TABLE AUTO_PK_SUPPORT (
- TABLE_NAME CHAR(100) NOT NULL, NEXT_ID BIGINT NOT NULL, PRIMARY KEY(TABLE_NAME))
-...
-INFO: SELECT t0.DATE_OF_BIRTH, t0.NAME, t0.ID FROM ARTIST t0 ORDER BY t0.NAME
-INFO: === returned 0 rows. - took 17 ms.
-INFO: +++ transaction committed.</screen>
- </listitem>
- </itemizedlist>
- <itemizedlist>
- <listitem>
- <para>You can click on "Create new artist" link to create artists. Existing artists
- can be edited by clicking on their name:</para>
- <para><inlinemediaobject>
- <imageobject>
- <imagedata fileref="images/chrome-webapp.png" scalefit="1" width="100%"/>
- </imageobject>
- </inlinemediaobject></para>
- </listitem>
- </itemizedlist>
- <para>You are done with the tutorial!</para>
- </section>
-</section>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/getting-started/src/images/base-datamap.png
----------------------------------------------------------------------
diff --git a/docs/docbook/getting-started/src/images/base-datamap.png b/docs/docbook/getting-started/src/images/base-datamap.png
deleted file mode 100644
index a12bc01..0000000
Binary files a/docs/docbook/getting-started/src/images/base-datamap.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/getting-started/src/images/base-datanode.png
----------------------------------------------------------------------
diff --git a/docs/docbook/getting-started/src/images/base-datanode.png b/docs/docbook/getting-started/src/images/base-datanode.png
deleted file mode 100644
index 69939bb..0000000
Binary files a/docs/docbook/getting-started/src/images/base-datanode.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/getting-started/src/images/chrome-webapp.png
----------------------------------------------------------------------
diff --git a/docs/docbook/getting-started/src/images/chrome-webapp.png b/docs/docbook/getting-started/src/images/chrome-webapp.png
deleted file mode 100644
index 603e1df..0000000
Binary files a/docs/docbook/getting-started/src/images/chrome-webapp.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/getting-started/src/images/database-schema.jpg
----------------------------------------------------------------------
diff --git a/docs/docbook/getting-started/src/images/database-schema.jpg b/docs/docbook/getting-started/src/images/database-schema.jpg
deleted file mode 100644
index 9d4ee21..0000000
Binary files a/docs/docbook/getting-started/src/images/database-schema.jpg and /dev/null differ
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/getting-started/src/images/icon-attribute.png
----------------------------------------------------------------------
diff --git a/docs/docbook/getting-started/src/images/icon-attribute.png b/docs/docbook/getting-started/src/images/icon-attribute.png
deleted file mode 100755
index 77a68eb..0000000
Binary files a/docs/docbook/getting-started/src/images/icon-attribute.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/getting-started/src/images/icon-datamap.png
----------------------------------------------------------------------
diff --git a/docs/docbook/getting-started/src/images/icon-datamap.png b/docs/docbook/getting-started/src/images/icon-datamap.png
deleted file mode 100755
index 2ea96ca..0000000
Binary files a/docs/docbook/getting-started/src/images/icon-datamap.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/getting-started/src/images/icon-dbentity.png
----------------------------------------------------------------------
diff --git a/docs/docbook/getting-started/src/images/icon-dbentity.png b/docs/docbook/getting-started/src/images/icon-dbentity.png
deleted file mode 100755
index 87d9d8a..0000000
Binary files a/docs/docbook/getting-started/src/images/icon-dbentity.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/getting-started/src/images/icon-edit.png
----------------------------------------------------------------------
diff --git a/docs/docbook/getting-started/src/images/icon-edit.png b/docs/docbook/getting-started/src/images/icon-edit.png
deleted file mode 100755
index 027c482..0000000
Binary files a/docs/docbook/getting-started/src/images/icon-edit.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/getting-started/src/images/icon-new_objentity.png
----------------------------------------------------------------------
diff --git a/docs/docbook/getting-started/src/images/icon-new_objentity.png b/docs/docbook/getting-started/src/images/icon-new_objentity.png
deleted file mode 100755
index 8735d7a..0000000
Binary files a/docs/docbook/getting-started/src/images/icon-new_objentity.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/getting-started/src/images/icon-node.png
----------------------------------------------------------------------
diff --git a/docs/docbook/getting-started/src/images/icon-node.png b/docs/docbook/getting-started/src/images/icon-node.png
deleted file mode 100755
index 2ff4383..0000000
Binary files a/docs/docbook/getting-started/src/images/icon-node.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/getting-started/src/images/icon-relationship.png
----------------------------------------------------------------------
diff --git a/docs/docbook/getting-started/src/images/icon-relationship.png b/docs/docbook/getting-started/src/images/icon-relationship.png
deleted file mode 100755
index 44ed7eb..0000000
Binary files a/docs/docbook/getting-started/src/images/icon-relationship.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/getting-started/src/images/icon-sync.png
----------------------------------------------------------------------
diff --git a/docs/docbook/getting-started/src/images/icon-sync.png b/docs/docbook/getting-started/src/images/icon-sync.png
deleted file mode 100755
index 03e8623..0000000
Binary files a/docs/docbook/getting-started/src/images/icon-sync.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/getting-started/src/images/idea-edit-configurations.png
----------------------------------------------------------------------
diff --git a/docs/docbook/getting-started/src/images/idea-edit-configurations.png b/docs/docbook/getting-started/src/images/idea-edit-configurations.png
deleted file mode 100644
index df1d524..0000000
Binary files a/docs/docbook/getting-started/src/images/idea-edit-configurations.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/getting-started/src/images/idea-file-run-menu.png
----------------------------------------------------------------------
diff --git a/docs/docbook/getting-started/src/images/idea-file-run-menu.png b/docs/docbook/getting-started/src/images/idea-file-run-menu.png
deleted file mode 100644
index 30cf05e..0000000
Binary files a/docs/docbook/getting-started/src/images/idea-file-run-menu.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/getting-started/src/images/idea-generated-classes.png
----------------------------------------------------------------------
diff --git a/docs/docbook/getting-started/src/images/idea-generated-classes.png b/docs/docbook/getting-started/src/images/idea-generated-classes.png
deleted file mode 100644
index 504dce5..0000000
Binary files a/docs/docbook/getting-started/src/images/idea-generated-classes.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/getting-started/src/images/idea-run-configuration.png
----------------------------------------------------------------------
diff --git a/docs/docbook/getting-started/src/images/idea-run-configuration.png b/docs/docbook/getting-started/src/images/idea-run-configuration.png
deleted file mode 100644
index 3ebbb62..0000000
Binary files a/docs/docbook/getting-started/src/images/idea-run-configuration.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/getting-started/src/images/idea-xmlfiles.png
----------------------------------------------------------------------
diff --git a/docs/docbook/getting-started/src/images/idea-xmlfiles.png b/docs/docbook/getting-started/src/images/idea-xmlfiles.png
deleted file mode 100644
index 1b4707d..0000000
Binary files a/docs/docbook/getting-started/src/images/idea-xmlfiles.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/getting-started/src/images/modeler-artistid.png
----------------------------------------------------------------------
diff --git a/docs/docbook/getting-started/src/images/modeler-artistid.png b/docs/docbook/getting-started/src/images/modeler-artistid.png
deleted file mode 100644
index fb8c1dd..0000000
Binary files a/docs/docbook/getting-started/src/images/modeler-artistid.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/getting-started/src/images/modeler-dbrelationship.png
----------------------------------------------------------------------
diff --git a/docs/docbook/getting-started/src/images/modeler-dbrelationship.png b/docs/docbook/getting-started/src/images/modeler-dbrelationship.png
deleted file mode 100644
index 4b23eb5..0000000
Binary files a/docs/docbook/getting-started/src/images/modeler-dbrelationship.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/getting-started/src/images/modeler-deleterule.png
----------------------------------------------------------------------
diff --git a/docs/docbook/getting-started/src/images/modeler-deleterule.png b/docs/docbook/getting-started/src/images/modeler-deleterule.png
deleted file mode 100644
index 86ada13..0000000
Binary files a/docs/docbook/getting-started/src/images/modeler-deleterule.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/getting-started/src/images/modeler-started.png
----------------------------------------------------------------------
diff --git a/docs/docbook/getting-started/src/images/modeler-started.png b/docs/docbook/getting-started/src/images/modeler-started.png
deleted file mode 100644
index dbf8324..0000000
Binary files a/docs/docbook/getting-started/src/images/modeler-started.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/getting-started/src/images/tutorial-idea-project.png
----------------------------------------------------------------------
diff --git a/docs/docbook/getting-started/src/images/tutorial-idea-project.png b/docs/docbook/getting-started/src/images/tutorial-idea-project.png
deleted file mode 100644
index 058dc1d..0000000
Binary files a/docs/docbook/getting-started/src/images/tutorial-idea-project.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/pom.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/pom.xml b/docs/docbook/pom.xml
deleted file mode 100644
index b7c411b..0000000
--- a/docs/docbook/pom.xml
+++ /dev/null
@@ -1,126 +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.
---><project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
-
- <modelVersion>4.0.0</modelVersion>
- <prerequisites>
- <maven>3</maven>
- </prerequisites>
-
- <parent>
- <groupId>org.apache.cayenne.docs</groupId>
- <artifactId>cayenne-docs-parent</artifactId>
- <version>4.0.B3-SNAPSHOT</version>
- </parent>
-
- <modules>
- <module>docbook-stylesheets</module>
- <module>cayenne-guide</module>
- <module>getting-started</module>
- <module>getting-started-rop</module>
- <module>upgrade-guide</module>
- </modules>
-
- <properties>
- <project.stylesheetdir>${project.parent.basedir}/docbook-stylesheets/target/classes</project.stylesheetdir>
-
- <!-- This property allows to only expose major version in the docs metadata to avoid confusing SEO -->
- <cayenne.version.major>4.0</cayenne.version.major>
- </properties>
-
- <artifactId>cayenne-docbook</artifactId>
- <packaging>pom</packaging>
- <name>cayenne-docbook: Cayenne Docbook Documentation</name>
-
- <build>
- <pluginManagement>
- <plugins>
- <plugin>
- <groupId>com.agilejava.docbkx</groupId>
- <artifactId>docbkx-maven-plugin</artifactId>
- <version>2.0.17</version>
- <dependencies>
- <dependency>
- <groupId>org.docbook</groupId>
- <artifactId>docbook-xml</artifactId>
- <version>4.4</version>
- <scope>runtime</scope>
- </dependency>
- </dependencies>
- </plugin>
- </plugins>
- </pluginManagement>
-
-
- <plugins>
- <plugin>
- <groupId>com.agilejava.docbkx</groupId>
- <artifactId>docbkx-maven-plugin</artifactId>
- <configuration>
- <xincludeSupported>true</xincludeSupported>
- <highlightSource>true</highlightSource>
- <targetDirectory>${basedir}/target/site/</targetDirectory>
- <includes>index.xml</includes>
- </configuration>
- <executions>
- <execution>
- <id>build-pdf</id>
- <configuration>
- <foCustomization>${project.stylesheetdir}/stylesheets/pdf.xsl</foCustomization>
- <postProcess>
- <delete failonerror="false">
- <fileset dir="target/site/" includes="*.fo" />
- </delete>
- <move file="target/site/index.pdf" tofile="target/site/${project.artifactId}.pdf" />
- </postProcess>
- </configuration>
- <phase>generate-resources</phase>
- <goals>
- <goal>generate-pdf</goal>
- </goals>
- </execution>
- <execution>
- <id>build-html</id>
- <configuration>
- <htmlCustomization>${project.stylesheetdir}/stylesheets/html.xsl</htmlCustomization>
- <chunkedOutput>true</chunkedOutput>
- <postProcess>
- <move todir="${basedir}/target/site/index">
- <fileset dir="${basedir}/target/site/">
- <include name="*.html" />
- </fileset>
- </move>
- <copy todir="${basedir}/target/site/index/css">
- <fileset dir="${project.stylesheetdir}/css" />
- </copy>
- <copy todir="${basedir}/target/site/index/images">
- <fileset dir="${basedir}/src/images" />
- </copy>
- </postProcess>
- </configuration>
- <phase>generate-resources</phase>
- <goals>
- <goal>generate-html</goal>
- </goals>
- </execution>
- </executions>
- </plugin>
- </plugins>
- </build>
-</project>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/upgrade-guide/pom.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/upgrade-guide/pom.xml b/docs/docbook/upgrade-guide/pom.xml
deleted file mode 100644
index a3c5973..0000000
--- a/docs/docbook/upgrade-guide/pom.xml
+++ /dev/null
@@ -1,38 +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.
--->
-
-<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
- <parent>
- <groupId>org.apache.cayenne.docs</groupId>
- <artifactId>cayenne-docbook</artifactId>
- <version>4.0.B3-SNAPSHOT</version>
- </parent>
- <modelVersion>4.0.0</modelVersion>
- <artifactId>upgrade-guide</artifactId>
- <name>upgrade-guide: Docbook - Cayenne New Features and Upgrade Guide</name>
-
- <build>
- <resources>
- <resource>
- <directory>target/site</directory>
- </resource>
- </resources>
- </build>
-</project>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/upgrade-guide/src/docbkx/index.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/upgrade-guide/src/docbkx/index.xml b/docs/docbook/upgrade-guide/src/docbkx/index.xml
deleted file mode 100644
index 91b0609..0000000
--- a/docs/docbook/upgrade-guide/src/docbkx/index.xml
+++ /dev/null
@@ -1,27 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<book xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
- xml:id="upgrade-guide" xmlns:xi="http://www.w3.org/2001/XInclude">
- <info>
- <title>Cayenne 4.0 New Features and Upgrade Guide</title>
- <copyright>
- <year>2011-<?dbtimestamp format="Y"?></year>
- <holder>Apache Software Foundation and individual authors</holder>
- </copyright>
- <legalnotice>
- <title>License</title>
- <para>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</para>
-
- <para>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.</para>
- </legalnotice>
- </info>
- <xi:include href="new-features.xml"/>
-</book>
-
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/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 6481ae3..0000000
--- a/docs/docbook/upgrade-guide/src/docbkx/new-features.xml
+++ /dev/null
@@ -1,238 +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"
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd">
- <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.7 or newer. Cayenne 4.0 is fully tested with Java 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 language="java">ServerRuntime runtime = ServerRuntime.builder("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 in situations when Cayenne is used as a stack to
- execute raw SQL, in unit tests, etc.</para>
- </section>
- <section>
- <title>DI Container Decorators</title>
- <para>In addition to overriding services in DI container, Cayenne now allows to supply
- 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 {
-
- private MyInterface delegate;
-
- public MockInterface1_Decorator3(@Inject MyInterface delegate) {
- this.delegate = delegate;
- }
-
- @Override
- public String getName() {
- return "<" + delegate.getName() + ">";
- }
-}
-
-Module module = binder ->
- binder.decorate(MyInterface.class).before(MyInterfaceDecorator.class);</programlisting>
- </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 language="java">Artist a = ObjectSelect
- .query(Artist.class)
- .where(Artist.ARTIST_NAME.eq("Picasso"))
- .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
- .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 language="java">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 language="java">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 being used more than once in the
- query:<programlisting language="java">// 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 language="java">runtime.performInTransaction(() -> {
- // ... do some changes
- context.commitChanges();
-
- // ... do more changes
- context.commitChanges();
-
- 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 language="java">Module cryptoExtensions = CryptoModule.extend()
- .keyStore("file:///mykeystore", "keystorepassword".toCharArray(), "keyalias")
- .compress()
- .module();</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 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>
- <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.
- </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>
- <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>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/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/cde78f0b/docs/pom.xml
----------------------------------------------------------------------
diff --git a/docs/pom.xml b/docs/pom.xml
index 0ad1709..21a6053 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/cde78f0b/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 923c014..e4666be 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
@@ -48,11 +48,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");
@@ -61,16 +64,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/cde78f0b/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 318ceb0..0084bd4 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.time.format.DateTimeParseException;
import org.apache.cayenne.tutorial.persistent.auto._Artist;
+// tag::content[]
public class Artist extends _Artist {
static final String DEFAULT_DATE_FORMAT = "yyyyMMdd";
@@ -38,13 +39,16 @@ public class Artist extends _Artist {
LocalDate date;
try {
- DateTimeFormatter formatter = DateTimeFormatter.ofPattern(DEFAULT_DATE_FORMAT);
+ DateTimeFormatter formatter = DateTimeFormatter
+ .ofPattern(DEFAULT_DATE_FORMAT);
date = LocalDate.parse(yearMonthDay, formatter);
} catch (DateTimeParseException e) {
- throw new IllegalArgumentException("A date argument must be in format '"
- + DEFAULT_DATE_FORMAT + "': " + yearMonthDay);
+ throw new IllegalArgumentException(
+ "A date argument must be in format '"
+ + DEFAULT_DATE_FORMAT + "': " + yearMonthDay);
}
setDateOfBirth(date);
}
}
}
+// end::content[]
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/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 448a8eb..d5a2877 100644
--- a/tutorials/tutorial/src/main/webapp/detail.jsp
+++ b/tutorials/tutorial/src/main/webapp/detail.jsp
@@ -24,6 +24,7 @@
<%@ page import="java.text.*" %>
<%@ page import="java.time.format.DateTimeFormatter"%>
+// tag::content[]
<%
ObjectContext context = BaseContext.getThreadObjectContext();
String id = request.getParameter("id");
@@ -85,4 +86,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/cde78f0b/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 36f630e..fe078fd 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[]
<%
ObjectContext context = BaseContext.getThreadObjectContext();
List<Artist> artists = ObjectSelect.query(Artist.class)
@@ -50,4 +51,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
[05/13] cayenne git commit: CAY-2371 Switch documentation from
Docbook to Asciidoctor format
Posted by nt...@apache.org.
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/cayenne-guide/src/docbkx/performance-tuning.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/cayenne-guide/src/docbkx/performance-tuning.xml b/docs/docbook/cayenne-guide/src/docbkx/performance-tuning.xml
deleted file mode 100644
index 2b569dd..0000000
--- a/docs/docbook/cayenne-guide/src/docbkx/performance-tuning.xml
+++ /dev/null
@@ -1,379 +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.
--->
-<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
- version="5.0" xml:id="performance-tuning">
- <title>Performance Tuning</title>
- <section xml:id="prefetching">
- <title>Prefetching</title>
- <para>Prefetching is a technique that allows to bring back in one query not only the queried
- objects, but also objects related to them. In other words it is a controlled eager
- relationship resolving mechanism. Prefetching is discussed in the "Performance Tuning"
- chapter, as it is a powerful performance optimization method. However another common
- application of prefetching is to refresh stale object relationships, so more generally
- it can be viewed as a technique for managing subsets of the object graph.</para>
- <para>Prefetching example:
- <programlisting language="java">ObjectSelect<Artist> query = ObjectSelect.query(Artist.class);
-
-// instructs Cayenne to prefetch one of Artist's relationships
-query.prefetch(Artist.PAINTINGS.disjoint());
-
-// the above line is equivalent to the following:
-// query.prefetch("paintings", PrefetchTreeNode.DISJOINT_PREFETCH_SEMANTICS);
-
-// query is expecuted as usual, but the resulting Artists will have
-// their paintings "inflated"
-List<Artist> artists = query.select(context);</programlisting>All
- types of relationships can be preftetched - to-one, to-many, flattened. A prefetch can
- span multiple relationships:
- <programlisting language="java">query.prefetch(Artist.PAINTINGS.dot(Painting.GALLERY).disjoint());</programlisting></para>
- <para>A query can have multiple
- prefetches:<programlisting language="java">query.prefetch(Artist.PAINTINGS.disjoint());
-query.prefetch(Artist.PAINTINGS.dot(Painting.GALLERY).disjoint());</programlisting></para>
- <para>If a query is fetching DataRows, all "disjoint" prefetches are ignored, only "joint"
- prefetches are executed (see prefetching semantics discussion below for what disjoint and
- joint prefetches mean).</para>
-
- <section xml:id="prefetching-semantics">
- <title>Prefetching Semantics</title>
- <para>Prefetching semantics defines a strategy to prefetch relationships. Depending on
- it, Cayenne would generate different types of queries. The end result is the same -
- query root objects with related objects fully resolved. However semantics can affect
- preformance, in some cases significantly. There are 3 types of prefetch semantics,
- all defined as constants in
- <code>org.apache.cayenne.query.PrefetchTreeNode</code>:<programlisting language="java">PrefetchTreeNode.JOINT_PREFETCH_SEMANTICS
-PrefetchTreeNode.DISJOINT_PREFETCH_SEMANTICS
-PrefetchTreeNode.DISJOINT_BY_ID_PREFETCH_SEMANTICS</programlisting></para>
- <para>There's no limitation on mixing different types of semantics in the same query.
- Each prefetch can have its own semantics. <code>SelectQuery</code> uses
- <code>DISJOINT_PREFETCH_SEMANTICS</code> by default. <code>ObjectSelect</code>
- requires explicit semantics as we've seen above. <code>SQLTemplate</code> and
- <code>ProcedureQuery</code> are both using <code>JOINT_PREFETCH_SEMANTICS</code>
- and it can not be changed due to the nature of those two queries.</para>
- </section>
- <section xml:id="disjoint-prefetch-semantics">
- <title>Disjoint Prefetching Semantics</title>
- <para>This semantics results in Cayenne generatiing one SQL statement for the main
- objects, and a separate statement for each prefetch path (hence "disjoint" - related
- objects are not fetched with the main query). Each additional SQL statement uses a
- qualifier of the main query plus a set of joins traversing the preftech path between
- the main and related entity. </para>
- <para>This strategy has an advantage of efficient JVM memory use, and faster overall
- result processing by Cayenne, but it requires (1+N) SQL statements to be executed,
- where N is the number of prefetched relationships.</para>
-
- </section>
- <section xml:id="disjoint-by-id-prefetch-semantics">
- <title>Disjoint-by-ID Prefetching Semantics</title>
- <para>This is a variation of disjoint prefetch where related objects are matched against
- a set of IDs derived from the fetched main objects (or intermediate objects in a
- multi-step prefetch). Cayenne limits the size of the generated WHERE clause, as most
- DBs can't parse arbitrary large SQL. So prefetch queries are broken into smaller
- queries. The size of is controlled by the DI property
- Constants.SERVER_MAX_ID_QUALIFIER_SIZE_PROPERTY (the default number of conditions in
- the generated WHERE clause is 10000). Cayenne will generate (1 + N * M) SQL
- statements for each query using disjoint-by-ID prefetches, where N is the number of
- relationships to prefetch, and M is the number of queries for a given prefetch that
- is dependent on the number of objects in the result (ideally M = 1).</para>
- <para>The advantage of this type of prefetch is that matching database rows by ID may be
- much faster than matching the qualifier of the original query. Moreover this is
- <emphasis role="bold">the only type of prefetch</emphasis> that can handle
- SelectQueries with <emphasis role="bold">fetch limit</emphasis>. Both joint and
- regular disjoint prefetches may produce invalid results or generate inefficient
- fetch-the-entire table SQL when fetch limit is in effect. </para>
- <para>The disadvantage is that query SQL can get unwieldy for large result sets, as each
- object will have to have its own condition in the WHERE clause of the generated
- SQL.</para>
- </section>
- <section xml:id="joint-prefetch-semantics">
- <title>Joint Prefetching Semantics</title>
- <para>Joint semantics results in a single SQL statement for root objects and any number
- of jointly prefetched paths. Cayenne processes in memory a cartesian product of the
- entities involved, converting it to an object tree. It uses OUTER joins to connect
- prefetched entities.</para>
- <para>Joint is the most efficient prefetch type of the three as far as generated SQL
- goes. There's always just 1 SQL query generated. Its downsides are the potentially
- increased amount of data that needs to get across the network between the
- application server and the database, and more data processing that needs to be done
- on the Cayenne side.</para>
- </section>
- <section xml:id="prefetching-with-ejbql">
- <title>Similar Behaviours Using EJBQL</title>
- <para>It is possible to achieve similar behaviours with
- <link linkend="ejbqlquery">EJBQLQuery</link> queries by employing the "FETCH"
- keyword.</para>
-
- <programlisting language="sql">SELECT a FROM Artist a LEFT JOIN FETCH a.paintings</programlisting>
-
- <para>
- In this case, the Paintings that exist for the Artist will be obtained at the same time
- as the Artists are fetched. Refer to third-party query language documentation for further
- detail on this mechanism.
- </para>
-
- </section>
-
- </section>
- <section xml:id="datarows">
- <title>Data Rows</title>
- <para>Converting result set data to Persistent objects and registering these objects in the
- ObjectContext can be an expensive operation compareable to the time spent running the
- query (and frequently exceeding it). Internally Cayenne builds the result as a list of
- DataRows, that are later converted to objects. Skipping the last step and using data in
- the form of DataRows can significantly increase performance. </para>
- <para>DataRow is a simply a map of values keyed by their DB column name. It is a ubiqutous
- representation of DB data used internally by Cayenne. And it can be quite usable as is
- in the application in many cases. So performance sensitive selects should consider
- DataRows - it saves memory and CPU cycles. All selecting queries support DataRows
- option,
- e.g.:<programlisting language="java">ObjectSelect<DataRow> query = ObjectSelect.dataRowQuery(Artist.class);
-
-List<DataRow> rows = query.select(context);</programlisting><programlisting language="java">SQLSelect<DataRow> query = SQLSelect.dataRowQuery("SELECT * FROM ARTIST");
-List<DataRow> rows = query.select(context);</programlisting></para>
- <para>Individual DataRows may be converted to Persistent objects as needed. So e.g. you may
- implement some in-memory filtering, only converting a subset of fetched
- objects:<programlisting language="java">// you need to cast ObjectContext to DataContext to get access to 'objectFromDataRow'
-DataContext dataContext = (DataContext) context;
-
-for(DataRow row : rows) {
- if(row.get("DATE_OF_BIRTH") != null) {
- Artist artist = dataContext.objectFromDataRow(Artist.class, row);
- // do something with Artist...
- ...
- }
-}</programlisting></para>
- </section>
-
- <section xml:id="specific-attributes-with-ejbql">
- <title>Specific Attributes and Relationships with EJBQL</title>
- <para>
- It is possible to fetch specific attributes and relationships from a model
- using <link linkend="ejbqlquery">EJBQLQuery</link>.
- The following example would return a java.util.List of String objects;
- </para>
-
- <programlisting language="sql">SELECT a.name FROM Artist a</programlisting>
-
- <para>The following will yield a java.util.List containing Object[] instances, each of which
- would contain the name followed by the dateOfBirth value.</para>
-
- <programlisting language="sql">SELECT a.name, a.dateOfBirth FROM Artist a</programlisting>
-
- <para>Refer to third-party query language documentation for further
- detail on this mechanism.</para>
- </section>
-
- <section xml:id="iterated-queries">
- <title>Iterated Queries</title>
- <para>While contemporary hardware may easily allow applications to fetch hundreds of
- thousands or even millions of objects into memory, it doesn't mean this is always a good
- idea to do so. You can optimize processing of very large result sets with two techniques
- discussed in this and the following chapter - iterated and paginated queries. </para>
- <para>Iterated query is not actually a special query. Any selecting query can be executed in
- iterated mode by an ObjectContext. ObjectContext creates an object called
- <code>ResultIterator</code> that is backed by an open ResultSet. Iterator provides
- constant memory performance for arbitrarily large ResultSets. This is true at least on
- the Cayenne end, as JDBC driver may still decide to bring the entire ResultSet into the
- JVM memory. </para>
- <para>Data is read from ResultIterator one row/object at a time until it is exhausted. There
- are two styles of accessing ResultIterator - direct access which requires explicit
- closing to avoid JDBC resources leak, or a callback that lets Cayenne handle resource
- management. In both cases iteration can be performed using "for" loop, as ResultIterator
- is "Iterable".</para>
- <para>Direct access. Here common sense tells us that ResultIterators instances should be
- processed and closed as soon as possible to release the DB connection. E.g. storing open
- iterators between HTTP requests for unpredictable length of time would quickly exhaust
- the connection
- pool.<programlisting language="java">try(ResultIterator<Artist> it = ObjectSelect.query(Artist.class).iterator(context)) {
- for(Artist a : it) {
- // do something with the object...
- ...
- }
-}</programlisting></para>
- <para>Same thing with a
- callback:<programlisting language="java">ObjectSelect.query(Artist.class).iterate(context, (Artist a) -> {
- // do something with the object...
- ...
-});</programlisting></para>
- <para>Another example is a batch iterator that allows to process more than one object in
- each iteration. This is a common scenario in various data processing jobs - read a batch
- of objects, process them, commit the results, and then repeat. This allows to further
- optimize processing (e.g. by avoiding frequent
- commits).<programlisting language="java">try(ResultBatchIterator<Artist> it = ObjectSelect.query(Artist.class).batchIterator(context, 100)) {
- for(List<Artist> list : it) {
- // do something with each list
- ...
- // possibly commit your changes
- context.commitChanges();
- }
-}</programlisting></para>
- </section>
- <section xml:id="paginated-queries">
- <title>Paginated Queries</title>
- <para>Enabling query pagination allows to load very large result sets in a Java app with
- very little memory overhead (much smaller than even the DataRows option discussed
- above). Moreover it is completely transparent to the application - a user gets what
- appears to be a list of Persistent objects - there's no iterator to close or DataRows to
- convert to objects:</para>
- <para>
- <programlisting language="java">// the fact that result is paginated is transparent
-List<Artist> artists =
- ObjectSelect.query(Artist.class).pageSize(50).select(context);</programlisting>
- </para>
- <para>Having said that, DataRows option can be combined with pagination, providing the best
- of both
- worlds:<programlisting language="java">List<DataRow> rows =
- ObjectSelect.dataRowQuery(Artist.class).pageSize(50).select(context);</programlisting></para>
- <para>The way pagination works internally, it first fetches a list of IDs for the root
- entity of the query. This is very fast and initially takes very little memory. Then when
- an object is requested at an arbitrary index in the list, this object and adjacent
- objects (a "page" of objects that is determined by the query pageSize parameter) are
- fetched together by ID. Subsequent requests to the objects of this "page" are served
- from memory.</para>
- <para>An obvious limitation of pagination is that if you eventually access all objects in
- the list, the memory use will end up being the same as with no pagination. However it is
- still a very useful approach. With some lists (e.g. multi-page search results) only a
- few top objects are normally accessed. At the same time pagination allows to estimate
- the full list size without fetching all the objects. And again - it is completely
- transparent and looks like a normal query.</para>
- </section>
- <section xml:id="caching-and-fresh-data">
- <title>Caching and Fresh Data</title>
- <section xml:id="object-caching">
- <title>Object Caching</title>
- </section>
- <section xml:id="query-result-caching">
- <title>Query Result Caching</title>
- <para>Cayenne supports mostly transparent caching of the query results. There are two
- levels of the cache: local (i.e. results cached by the ObjectContext) and shared
- (i.e. the results cached at the stack level and shared between all contexts). Local
- cache is much faster then the shared one, but is limited to a single context. It is
- often used with a shared read-only ObjectContext. </para>
- <para>To take advantage of query result caching, the first step is to mark your queries
- appropriately. Here is an example for ObjectSelect query. Other types of queries
- have similar
- API:<programlisting language="java">ObjectSelect.query(Artist.class).localCache("artists");</programlisting></para>
- <para>This tells Cayenne that the query created here would like to use local cache of
- the context it is executed against. A vararg parameter to <code>localCache()</code>
- (or <code>sharedCache()</code>) method contains so called "cache groups". Those are
- arbitrary names that allow to categorize queries for the purpose of setting cache
- policies or explicit invalidation of the cache. More on that below.</para>
- <para>The above API is enough for the caching to work, but by default your cache is an
- unmanaged LRU map. You can't control its size, expiration policies, etc. For the
- managed cache, you will need to explicitly use one of the more advanced cache
- providers. One such provider available in Cayenne is a provider for <link
- xlink:href="http://www.ehcache.org/">EhCache</link>. It can be enabled on
- ServerRuntime startup in a custom
- Module:<programlisting language="java">ServerRuntimeBuilder
- .builder()
- .addModule((binder) ->
- binder.bind(QueryCache.class).to(EhCacheQueryCache.class)
- )
- .build();</programlisting></para>
- <para>By default EhCache reads a file called "ehcache.xml" located on classpath. You can
- put your cache configuration in that file.
- E.g.:<programlisting language="xml"><ehcache xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:noNamespaceSchemaLocation="ehcache.xsd" updateCheck="false"
- monitoring="off" dynamicConfig="false">
-
- <defaultCache maxEntriesLocalHeap="1000" eternal="false"
- overflowToDisk="false" timeToIdleSeconds="3600" timeToLiveSeconds="3600">
- </defaultCache>
-
- <cache name="artists" timeToLiveSeconds="20" maxEntriesLocalHeap="100" />
-</ehcache></programlisting></para>
- <para>The example shows how to configure default cache settings ("defaultCache") as well
- as settings for a named cache group ("artists"). For many other things you can put
- in "ehcache.xml" refer to EhCache docs.</para>
- <para>Often "passive" cache expiration policies similar to shown above are not
- sufficient, and the users want real-time cache invalidation when the data changes.
- So in addition to those policies, the app can invalidate individual cache groups
- explicitly with
- <code>RefreshQuery</code>:<programlisting language="java">RefreshQuery refresh = new RefreshQuery("artist");
-context.performGenericQuery(refresh);</programlisting></para>
- <para>The above can be used e.g. to build UI for manual cache invalidation. It is also
- possible to automate cache refresh when certain entities are committed. This
- requires including <code>cayenne-lifecycle.jar</code> deoendency. From that library
- you will need two things: <code>@CacheGroups</code> annotation to mark entities that
- generate cache invalidation events and <code>CacheInvalidationFilter</code> that
- catches the updates to the annotated objects and generates appropriate invalidation
- events:<programlisting language="java">// configure filter on startup
-ServerRuntimeBuilder
- .builder()
- .addModule((binder) ->
- binder.bindList(Constants.SERVER_DOMAIN_FILTERS_LIST).add(CacheInvalidationFilter.class)
- )
- .build();</programlisting></para>
- <para>Now you can associate entities with cache groups, so that commits to those
- entities would atomatically invalidate the
- groups:<programlisting language="java">@CacheGroups("artists")
-public class Artist extends _Artist {
-}</programlisting></para>
- <para>Finally you may cluster cache group events. They are very small and can be
- efficiently sent over the wire to other JVMs running Cayenne. An example of Cayenne
- setup with event clustering is <link
- xlink:href="https://github.com/andrus/wowodc13/tree/master/services/src/main/java/demo/services/cayenne"
- >available on GitHub</link>.</para>
- </section>
- </section>
- <section xml:id="turning-off-synchronization-of-objectcontexts">
- <title>Turning off Synchronization of ObjectContexts</title>
- <para>By default when a single ObjectContext commits its changes, all other contexts in the
- same runtime receive an event that contains all the committed changes. This allows them
- to update their cached object state to match the latest committed data. There are
- however many problems with this ostensibly helpful feature. In short - it works well in
- environments with few contexts and in unclustered scenarios, such as single user desktop
- applications, or simple webapps with only a few users. More specifically:<itemizedlist>
- <listitem>
- <para>The performance of synchronization is (probably worse than) O(N) where N
- is the number of peer ObjectContexts in the system. In a typical webapp N
- can be quite large. Besides for any given context, due to locking on
- synchronization, context own performance will depend not only on the queries
- that it runs, but also on external events that it does not control. This is
- unacceptable in most situations. </para>
- </listitem>
- <listitem>
- <para>Commit events are untargeted - even contexts that do not hold a given
- updated object will receive the full event that they will have to
- process.</para>
- </listitem>
- <listitem>
- <para>Clustering between JVMs doesn't scale - apps with large volumes of commits
- will quickly saturate the network with events, while most of those will be
- thrown away on the receiving end as mentioned above.</para>
- </listitem>
- <listitem>
- <para>Some contexts may not want to be refreshed. A refresh in the middle of an
- operation may lead to unpredictable results. </para>
- </listitem>
- <listitem>
- <para>Synchronization will interfere with optimistic locking. </para>
- </listitem>
- </itemizedlist>So we've made a good case for disabling synchronization in most webapps.
- To do that, set to "false" the following DI property -
- <code>Constants.SERVER_CONTEXTS_SYNC_PROPERTY</code>, using one of the standard
- Cayenne DI approaches. E.g. from command
- line:<screen><prompt>$</prompt> java -Dcayenne.server.contexts_sync_strategy=false</screen>Or
- by changing the standard properties Map in a custom extensions
- module:<programlisting language="java">public class MyModule implements Module {
-
- @Override
- public void configure(Binder binder) {
- binder.bindMap(Constants.PROPERTIES_MAP).put(Constants.SERVER_CONTEXTS_SYNC_PROPERTY, "false");
- }
-}</programlisting></para>
- </section>
-</chapter>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/cayenne-guide/src/docbkx/persistent-objects-objectcontext.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/cayenne-guide/src/docbkx/persistent-objects-objectcontext.xml b/docs/docbook/cayenne-guide/src/docbkx/persistent-objects-objectcontext.xml
deleted file mode 100644
index 6305c9a..0000000
--- a/docs/docbook/cayenne-guide/src/docbkx/persistent-objects-objectcontext.xml
+++ /dev/null
@@ -1,288 +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.
--->
-<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
- version="5.0" xml:id="persistent-objects-objectcontext">
- <title>Persistent Objects and ObjectContext</title>
- <section xml:id="objectcontext">
- <title>ObjectContext</title>
- <para>ObjectContext is an interface that users normally work with to access the database. It
- provides the API to execute database operations and to manage persistent objects. A
- context is obtained from the
- ServerRuntime:<programlisting language="java">ObjectContext context = runtime.newContext();</programlisting></para>
- <para>The call above creates a new instance of ObjectContext that can access the database via this
- runtime. ObjectContext is a single "work area" in Cayenne, storing persistent objects.
- ObjectContext guarantees that for each database row with a unique ID it will contain at
- most one instance of an object, thus ensuring object graph consistency between multiple
- selects (a feature called "uniquing"). At the same time different ObjectContexts will
- have independent copies of objects for each unique database row. This allows users to
- isolate object changes from one another by using separate ObjectContexts.</para>
- <para>These properties directly affect the strategies for scoping and sharing (or not
- sharing) ObjectContexts. Contexts that are only used to fetch objects from the database
- and whose objects are never modified by the application can be shared between mutliple
- users (and multiple threads). Contexts that store modified objects should be accessed
- only by a single user (e.g. a web application user might reuse a context instance
- between multiple web requests in the same HttpSession, thus carrying uncommitted changes
- to objects from request to request, until he decides to commit or rollback them). Even
- for a single user it might make sense to use mutliple ObjectContexts (e.g.
- request-scoped contexts to allow concurrent requests from the browser that change and
- commit objects independently).</para>
- <para>ObjectContext is serializable and does not permanently hold to any of the application
- resources. So it does not have to be closed. If the context is not used anymore, it
- should simply be allowed to go out of scope and get garbage collected, just like any
- other Java object.</para>
- </section>
- <section xml:id="persistent-lifecycle">
- <title>Persistent Object and its Lifecycle</title>
- <para>Cayenne can persist Java objects that implement <code>org.apache.cayenne.Persistent</code>
- interface. Generally persistent classes are generated from the model as described above,
- so users do not have to worry about superclass and property implementation details. </para>
- <para>Persistent interface provides access to 3 persistence-related properties - objectId,
- persistenceState and objectContext. All 3 are initialized by Cayenne runtime framework.
- Application code should not attempt to change them them. However it is allowed to read
- them, which provides valuable runtime information. E.g. ObjectId can be used for quick
- equality check of 2 objects, knowing persistence state would allow highlighting changed
- objects, etc.</para>
- <para>Each persistent object belongs to a single ObjectContext, and can be in one of the following
- persistence states (as defined in <code>org.apache.cayenne.PersistenceState</code>)
- :<table frame="void">
- <caption>Persistence States</caption>
- <col width="16%"/>
- <col width="84%"/>
- <tbody>
- <tr>
- <td>TRANSIENT</td>
- <td>The object is not registered with an ObjectContext and will not be
- persisted.</td>
- </tr>
- <tr>
- <td>NEW</td>
- <td>The object is freshly registered in an ObjectContext, but has not been
- saved to the database yet and there is no matching database row.</td>
- </tr>
- <tr>
- <td>COMMITTED</td>
- <td>The object is registered in an ObjectContext, there is a row in the
- database corresponding to this object, and the object state corresponds
- to the last known state of the matching database row.</td>
- </tr>
- <tr>
- <td>MODIFIED</td>
- <td>The object is registered in an ObjectContext, there is a row in the
- database corresponding to this object, but the object in-memory state
- has diverged from the last known state of the matching database
- row.</td>
- </tr>
- <tr>
- <td>HOLLOW</td>
- <td>The object is registered in an ObjectContext, there is a row in the
- database corresponding to this object, but the object state is unknown.
- Whenever an application tries to access a property of such object,
- Cayenne attempts reading its values from the database and "inflate" the
- object, turning it to COMMITED.</td>
- </tr>
- <tr>
- <td>DELETED</td>
- <td>The object is registered in an ObjectContext and has been marked for
- deletion in-memory. The corresponding row in the database will get
- deleted upon ObjectContext commit, and the object state will be turned
- into TRANSIENT.</td>
- </tr>
- </tbody>
- </table></para>
- </section>
- <section xml:id="persistent-operations">
- <title>ObjectContext Persistence API</title>
- <para>One of the first things users usually want to do with an ObjectContext is to select
- some objects from a database. This is done by calling "<emphasis role="italic"
- >performQuery</emphasis>"
- method:<programlisting language="java">SelectQuery query = new SelectQuery(Artist.class);
-List<Artist> artists = context.performQuery(query);</programlisting>We'll
- discuss queries in some detail in the following chapters. The example above is
- self-explanatory - we create a SelectQuery that matches all Artist objects present in
- the database, and then call "performQuery", getting a list of Artist objects.</para>
- <para>Some queries can be quite complex, returning multiple result sets or even updating the
- database. For such queries ObjectContext provides "<emphasis role="italic"
- >performGenericQuery</emphasis>"method. While not nearly as commonly-used as
- "performQuery", it is nevertheless important in some situations.
- E.g.:<programlisting language="java">Collection<Query> queries = ... // multiple queries that need to be run together
-QueryChain query = new QueryChain(queries);
-
-QueryResponse response = context.performGenericQuery(query);</programlisting></para>
- <para>An application might modify selected objects. E.g.:</para>
- <programlisting language="java">Artist selectedArtist = artists.get(0);
-selectedArtist.setName("Dali");</programlisting>
- <para>The first time the object property is changed, the object's state is automatically set
- to "MODIFIED" by Cayenne. Cayenne tracks all in-memory changes until a user calls
- "<emphasis role="italic"
- >commitChanges</emphasis>":<programlisting language="java">context.commitChanges();</programlisting>At
- this point all in-memory changes are analyzed and a minimal set of SQL statements is
- issued in a single transaction to synchronize the database with the in-memory state. In
- our example "commitChanges" commits just one object, but generally it can be any number
- of objects. </para>
- <para>If instead of commit, we wanted to reset all changed objects to the previously
- committed state, we'd call <emphasis>rollbackChanges</emphasis>
- instead:<programlisting language="java">context.rollbackChanges();</programlisting></para>
- <para>"<emphasis role="italic">newObject</emphasis>" method call creates a persistent object
- and sets its state to
- "NEW":<programlisting language="java">Artist newArtist = context.newObject(Artist.class);
-newArtist.setName("Picasso");</programlisting></para>
- <para>It will only exist in memory until "commitChanges" is issued. On commit Cayenne might
- generate a new primary key (unless a user set it explicitly, or a PK was inferred from a
- relationship) and issue an INSERT SQL statement to permanently store the object.</para>
- <para><emphasis>deleteObjects</emphasis> method takes one or more Persistent objects and
- marks them as
- "DELETED":<programlisting language="java">context.deleteObjects(artist1);
-context.deleteObjects(artist2, artist3, artist4);</programlisting>Additionally
- "deleteObjects" processes all delete rules modeled for the affected objects. This may
- result in implicitly deleting or modifying extra related objects. Same as insert and
- update, delete operations are sent to the database only when "commitChanges" is called.
- Similarly "rollbackChanges" will undo the effect of "newObject" and
- "deleteObjects".</para>
- <para><emphasis>localObject</emphasis> returns a copy of a given persistent object that is
- "local" to a given ObjectContext:</para>
- <para>Since an application often works with more than one context, "localObject" is a rather
- common operation. E.g. to improve performance a user might utilize a single shared
- context to select and cache data, and then occasionally transfer some selected objects
- to another context to modify and commit
- them:<programlisting language="java">ObjectContext editingContext = runtime.newContext();
-Artist localArtist = editingContext.localObject(artist);</programlisting></para>
- <para>Often an appliction needs to inspect mapping metadata. This information is stored in
- the EntityResolver object, accessible via the
- ObjectContext:<programlisting language="java">EntityResolver resolver = objectContext.getEntityResolver();</programlisting></para>
- <para>Here we discussed the most commonly used subset of the ObjectContext API. There are
- other useful methods, e.g. those allowing to inspect registered objects state en bulk,
- etc. Check the latest JavaDocs for details.</para>
- </section>
- <section xml:id="cayenne-helper-class">
- <title>Cayenne Helper Class</title>
- <para>There is a useful helper class called "Cayenne" (fully-qualified name
- <code>"org.apache.cayenne.Cayenne"</code>) that builds on ObjectContext API to
- provide a number of very common operations. E.g. get a primary key (most entities do not
- model PK as an object property)
- :<programlisting language="java">long pk = Cayenne.longPKForObject(artist);</programlisting></para>
- <para>It also provides the reverse operation - finding an object given a known
- PK:<programlisting language="java">Artist artist = Cayenne.objectForPK(context, Artist.class, 34579);</programlisting></para>
- <para>If a query is expected to return 0 or 1 object, Cayenne helper class can be used to find
- this object. It throws an exception if more than one object matched the
- query:<programlisting language="java">Artist artist = (Artist) Cayenne.objectForQuery(context, new SelectQuery(Artist.class));</programlisting></para>
- <para>Feel free to explore Cayenne class API for other useful methods.</para>
- </section>
- <section xml:id="objectcontext-nesting">
- <title>ObjectContext Nesting</title>
- <para>In all the examples shown so far an ObjectContext would directly connect to a database
- to select data or synchronize its state (either via commit or rollback). However another
- context can be used in all these scenarios instead of a database. This concept is called
- ObjectContext "nesting". Nesting is a parent/child relationship between two contexts,
- where child is a nested context and selects or commits its objects via a parent. </para>
- <para>Nesting is useful to create isolated object editing areas (child contexts) that need
- to all be committed to an intermediate in-memory store (parent context), or rolled back
- without affecting changes already recorded in the parent. Think cascading GUI dialogs,
- or parallel AJAX requests coming to the same session.</para>
- <para>In theory Cayenne supports any number of nesting levels, however applications should
- generally stay with one or two, as deep hierarchies will most certainly degrade the
- performance of the deeply nested child contexts. This is due to the fact that each
- context in a nesting chain has to update its own objects during most operations. </para>
- <para>Cayenne ROP is an extreme case of nesting when a child context is located in a
- separate JVM and communicates with its parent via a web service. ROP is discussed in
- details in the following chapters. Here we concentrate on the same-VM nesting.</para>
- <para>To create a nested context, use an instance of ServerRuntime, passing it the desired
- parent:<programlisting language="java">ObjectContext parent = runtime.newContext();
-ObjectContext nested = runtime.newContext((DataChannel) parent);</programlisting>From
- here a nested context operates just like a regular context (you can perform queries,
- create and delete objects, etc.). The only difference is that commit and rollback
- operations can either be limited to synchronization with the parent, or cascade all the
- way to the
- database:<programlisting language="java">// merges nested context changes into the parent context
-nested.commitChangesToParent();
-
-// regular 'commitChanges' cascades commit through the chain
-// of parent contexts all the way to the database
-nested.commitChanges();</programlisting><programlisting language="java">// unrolls all local changes, getting context in a state identical to parent
-nested.rollbackChangesLocally();
-
-// regular 'rollbackChanges' cascades rollback through the chain of contexts
-// all the way to the topmost parent
-nested.rollbackChanges();</programlisting></para>
- </section>
- <section xml:id="generic-persistent-objects">
- <title>Generic Persistent Objects</title>
- <para>As described in the CayenneModeler chapter, Cayenne supports mapping of completely
- generic classes to specific entities. Although for conveniece most applications should
- stick with entity-specific class mappings, the generic feature offers some interesting
- possibilities, such as creating mappings completely on the fly in a running application,
- etc.</para>
- <para>Generic objects are first class citizens in Cayenne, and all common persistent
- operations apply to them as well. There are some pecularities however, described
- below.</para>
- <para>When creating a new generic object, either cast your ObjectContext to DataContext
- (that provides "newObject(String)" API), or provide your object with an explicit
- ObjectId:<programlisting language="java">DataObject generic = ((DataContext) context).newObject("GenericEntity");</programlisting><programlisting language="java">DataObject generic = new CayenneDataObject();
-generic.setObjectId(new ObjectId("GenericEntity"));
-context.registerNewObject(generic);</programlisting>SelectQuery
- for generic object should be created passing entity name String in constructor, instead
- of a Java
- class:<programlisting language="java">SelectQuery query = new SelectQuery("GenericEntity");</programlisting>Use
- DataObject API to access and modify properties of a generic
- object:<programlisting language="java">String name = (String) generic.readProperty("name");
-generic.writeProperty("name", "New Name");</programlisting>This
- is how an application can obtain entity name of a generic
- object:<programlisting language="java">String entityName = generic.getObjectId().getEntityName();</programlisting></para>
- </section>
- <section xml:id="transactions">
- <title>Transactions</title>
- <para>Considering how much attention is given to managing transactions in most other ORMs,
- transactions have been conspicuously absent from the ObjectContext discussion till now.
- The reason is that transactions are seamless in Cayenne in all but a few special cases.
- ObjectContext is an in-memory container of objects that is disconnected from the
- database, except when it needs to run an operation. So it does not care about any
- surrounding transaction scope. Sure enough all database operations are transactional, so
- when an application does a commit, all SQL execution is wrapped in a database
- transaction. But this is done behind the scenes and is rarely a concern to the
- application code.</para>
- <para>Two cases where transactions need to be taken into consideration are container-managed
- and application-managed transactions. </para>
- <para>If you are using an EJB container (or some other JTA environment), you'll likely need
- to switch Cayenne runtime into "external transactions mode". This is done by setting DI
- configuration property defined in <code>Constants.SERVER_EXTERNAL_TX_PROPERTY</code>
- (see Appendix A). If this property is set to "true", Cayenne assumes that JDBC
- Connections obtained by runtime whenever that might happen are all coming from a
- transactional DataSource managed by the container. In this case Cayenne does not attempt
- to commit or rollback the connections, leaving it up to the container to do that when
- appropriate.</para>
- <para>In the second scenario, an application might need to define its own transaction scope
- that spans more than one Cayenne operation. E.g. two sequential commits that need to be
- rolled back together in case of failure. This can be done via
- <code>ServerRuntime.performInTransaction</code>
- method:<programlisting language="java">Integer result = runtime.performInTransaction(() -> {
- // commit one or more contexts
- context1.commitChanges();
- context2.commitChanges();
- ....
- // after changing some objects in context1, commit again
- context1.commitChanges();
- ....
-
- // return an arbitrary result or null if we don't care about the result
- return 5;
-});</programlisting></para>
- <para>When inside the transaction, current thread Transaction object can be accessed via a
- static method. E.g. here is an example that initializes transaction JDBC connection with
- a custom connection object
- :<programlisting language="java">Transaction tx = BaseTransaction.getThreadTransaction();
-tx.addConnection("mydatanode", myConnection); </programlisting></para>
- </section>
-</chapter>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/cayenne-guide/src/docbkx/queries-custom.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/cayenne-guide/src/docbkx/queries-custom.xml b/docs/docbook/cayenne-guide/src/docbkx/queries-custom.xml
deleted file mode 100644
index a8f00ea..0000000
--- a/docs/docbook/cayenne-guide/src/docbkx/queries-custom.xml
+++ /dev/null
@@ -1,57 +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.
- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~-->
-<section xmlns="http://docbook.org/ns/docbook" xml:id="custom-queries">
- <title>Custom Queries</title>
- <para>If a user needs some extra functionality not addressed by the existing set of Cayenne
- queries, he can write his own. The only requirement is to implement
- <code>org.apache.cayenne.query.Query</code> interface. The easiest way to go about
- it is to subclass some of the base queries in Cayenne. </para>
- <para>E.g. to do something directly in the JDBC layer, you might subclass
- AbstractQuery:<programlisting language="java">public class MyQuery extends AbstractQuery {
-
- @Override
- public SQLAction createSQLAction(SQLActionVisitor visitor) {
- return new SQLAction() {
-
- @Override
- public void performAction(Connection connection, OperationObserver observer) throws SQLException, Exception {
- // 1. do some JDBC work using provided connection...
- // 2. push results back to Cayenne via OperationObserver
- }
- };
- }
-}</programlisting></para>
- <para>To delegate the actual query execution to a standard Cayenne query, you may subclass
- IndirectQuery:<programlisting language="java">public class MyDelegatingQuery extends IndirectQuery {
-
- @Override
- protected Query createReplacementQuery(EntityResolver resolver) {
- SQLTemplate delegate = new SQLTemplate(SomeClass.class, generateRawSQL());
- delegate.setFetchingDataRows(true);
- return delegate;
- }
-
- protected String generateRawSQL() {
- // build some SQL string
- }
-}</programlisting></para>
- <para>In fact many internal Cayenne queries are IndirectQueries, delegating to SelectQuery
- or SQLTemplate after some preprocessing.</para>
- </section>
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/cayenne-guide/src/docbkx/queries-ejbql.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/cayenne-guide/src/docbkx/queries-ejbql.xml b/docs/docbook/cayenne-guide/src/docbkx/queries-ejbql.xml
deleted file mode 100644
index 4c0afff..0000000
--- a/docs/docbook/cayenne-guide/src/docbkx/queries-ejbql.xml
+++ /dev/null
@@ -1,94 +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.
--->
-<section xmlns="http://docbook.org/ns/docbook" xml:id="ejbqlquery">
- <title>EJBQLQuery</title>
- <para>EJBQLQuery was created as a part of an experiment in adopting some of Java Persistence
- API (JPA) approaches in Cayenne. It is a parameterized object query that is created from
- query String. A String used to build EJBQLQuery must conform to JPQL (JPA query
- language):<programlisting language="java">EJBQLQuery query = new EJBQLQuery("select a FROM Artist a");</programlisting></para>
- <para>JPQL details can be found in any JPA manual. Here we'll mention only how this fits
- into Cayenne and what are the differences between EJBQL and other Cayenne
- queries.</para>
- <para>Although most frequently EJBQLQuery is used as an alternative to SelectQuery, there
- are also DELETE and UPDATE varieties available. <note>
- <para>As of this version of Cayenne, DELETE and UPDATE do not change the state of
- objects in the ObjectContext. They are run directly against the database
- instead. </para>
- </note><programlisting language="java">EJBQLQuery select = new EJBQLQuery("select a FROM Artist a WHERE a.name = 'Salvador Dali'");
-List<Artist> artists = context.performQuery(select);</programlisting><programlisting language="java">EJBQLQuery delete = new EJBQLQuery("delete from Painting");
-context.performGenericQuery(delete);</programlisting><programlisting language="java">EJBQLQuery update = new EJBQLQuery("UPDATE Painting AS p SET p.name = 'P2' WHERE p.name = 'P1'");
-context.performGenericQuery(update);</programlisting>In
- most cases SelectQuery is preferred to EJBQLQuery, as it is API-based, and provides you
- with better compile-time checks. However sometimes you may want a completely scriptable
- object query. This is when you might prefer EJBQL. A more practical reason for picking
- EJBQL over SelectQuery though is that the former offers some extra selecting
- capabilities, namely aggregate functions and
- subqueries:<programlisting language="java">EJBQLQuery query = new EJBQLQuery("select a, COUNT(p) FROM Artist a JOIN a.paintings p GROUP BY a");
-List<Object[]> result = context.performQuery(query);
-for(Object[] artistWithCount : result) {
- Artist a = (Artist) artistWithCount[0];
- int hasPaintings = (Integer) artistWithCount[1];
-}</programlisting>This
- also demonstrates a previously unseen type of select result - a List of Object[]
- elements, where each entry in an Object[] is either a DataObject or a scalar, depending
- on the query SELECT clause. A result can also be a list of
- scalars:<programlisting language="java">EJBQLQuery query = new EJBQLQuery("select a.name FROM Artist a");
-List<String> names = context.performQuery(query);</programlisting>
-
- EJBQLQuery supports an "IN" clause with three different usage-patterns. The following
- example would require three individual positional parameters (named
- parameters could also have been used) to be supplied.
-
- <programlisting language="sql">select p from Painting p where p.paintingTitle in (?1,?2,?3)</programlisting>
-
- The following example requires a single positional parameter to be supplied. The
- parameter can be any concrete implementation of the java.util.Collection interface such as
- java.util.List or java.util.Set.
-
- <programlisting language="sql">select p from Painting p where p.paintingTitle in ?1</programlisting>
-
- The following example is functionally identical to the one prior.
-
- <programlisting language="sql">select p from Painting p where p.paintingTitle in (?1)</programlisting>
-
- </para>
- <para>
- It is <link linkend="expressions-to-ejbql">possible to convert</link>
- an <link linkend="expressions">Expression</link>
- object used with a <link linkend="selectquery">SelectQuery</link>
- to EJBQL. Use the Expression#appendAsEJBQL methods for this purpose.
- </para>
- <para>
- While
- Cayenne Expressions discussed previously can be thought of as identical to JPQL WHERE
- clause, and indeed they are very close, there are a few noteable differences:
- <itemizedlist>
- <listitem>
- <para>Null handling: SelectQuery would translate the expressions matching NULL
- values to the corresponding "X IS NULL" or "X IS NOT NULL" SQL syntax.
- EJBQLQuery on the other hand requires explicit "IS NULL" (or "IS NOT NULL")
- syntax to be used, otherwise the generated SQL will look like "X = NULL" (or
- "X <> NULL"), which will evaluate differently.</para>
- </listitem>
- <listitem>
- <para>Expression Parameters: SelectQuery uses "$" to denote named parameters
- (e.g. "$myParam"), while EJBQL uses ":" (e.g. ":myParam"). Also EJBQL
- supports positional parameters denoted by the question mark: "?3".</para>
- </listitem>
- </itemizedlist>
- </para>
- </section>
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/cayenne-guide/src/docbkx/queries-mapped.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/cayenne-guide/src/docbkx/queries-mapped.xml b/docs/docbook/cayenne-guide/src/docbkx/queries-mapped.xml
deleted file mode 100644
index c3d7dd1..0000000
--- a/docs/docbook/cayenne-guide/src/docbkx/queries-mapped.xml
+++ /dev/null
@@ -1,44 +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.
- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~-->
-<section xmlns="http://docbook.org/ns/docbook" xml:id="mappedqueries">
- <title>MappedSelect and MappedExec</title>
- <para>
- <code>MappedSelect</code> and <code>MappedExec</code> is a queries that are just a reference to another queries stored in the DataMap.
- The actual stored query can be SelectQuery, SQLTemplate, EJBQLQuery, etc.
- Difference between <code>MappedSelect</code> and <code>MappedExec</code> is (as reflected in their names)
- whether underlying query intended to select data or just to perform some generic SQL code.
- <note>
- <para>These queries are "fluent" versions of deprecated <code>NamedQuery</code> class.</para>
- </note>
- </para>
- <para>
- Here is example of how to use <code>MappedSelect</code>:
- <programlisting language="java"><![CDATA[List<Artist> results = MappedSelect.query("artistsByName", Artist.class)
- .param("name", "Picasso")
- .select(context);]]></programlisting>
- </para>
- <para>
- And here is example of <code>MappedExec</code>:
- <programlisting language="java"><![CDATA[QueryResult result = MappedExec.query("updateQuery")
- .param("var", "value")
- .execute(context);
-System.out.println("Rows updated: " + result.firstUpdateCount());]]></programlisting>
- </para>
-</section>
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/cayenne-guide/src/docbkx/queries-namedquery.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/cayenne-guide/src/docbkx/queries-namedquery.xml b/docs/docbook/cayenne-guide/src/docbkx/queries-namedquery.xml
deleted file mode 100644
index 2287413..0000000
--- a/docs/docbook/cayenne-guide/src/docbkx/queries-namedquery.xml
+++ /dev/null
@@ -1,35 +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.
- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~-->
-<section xmlns="http://docbook.org/ns/docbook" xml:id="namedquery">
- <title>NamedQuery</title>
- <para>NamedQuery is a query that is a reference to another query stored in the DataMap. The
- actual stored query can be SelectQuery, SQLTemplate, EJBQLQuery, etc. It doesn't matter
- - the API for calling them is the same - via a
- NamedQuery:<programlisting language="java">String[] keys = new String[] {"loginid", "password"};
-Object[] values = new String[] {"joe", "secret"};
-
-NamedQuery query = new NamedQuery("Login", keys, values);
-
-List<User> matchingUsers = context.performQuery(query); </programlisting>
- <warning>
- <para>This query is deprecated in favor of <code>MappedSelect</code> and <code>MappedExec</code></para>
- </warning>
- </para>
- </section>
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/cayenne-guide/src/docbkx/queries-procedure.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/cayenne-guide/src/docbkx/queries-procedure.xml b/docs/docbook/cayenne-guide/src/docbkx/queries-procedure.xml
deleted file mode 100644
index dea2ce8..0000000
--- a/docs/docbook/cayenne-guide/src/docbkx/queries-procedure.xml
+++ /dev/null
@@ -1,67 +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.
- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~-->
-<section xmlns="http://docbook.org/ns/docbook" xml:id="procedurequery">
- <title>ProcedureQuery</title>
- <para>Stored procedures are mapped as separate objects in CayenneModeler. ProcedureQuery
- provides a way to execute them with a certain set of parameters. Just like with
- SQLTemplate, the outcome of a procedure can be anything - a single result set, mutliple
- result sets, some data modification (returned as an update count), or a combination of
- these. So use "performQuery" to get a single result set, and use "performGenericQuery"
- for anything
- else:<programlisting language="java">ProcedureQuery query = new ProcedureQuery("my_procedure", Artist.class);
-
-// Set "IN" parameter values
-query.addParam("p1", "abc");
-query.addParam("p2", 3000);
-
-List<Artist> result = context.performQuery(query);</programlisting><programlisting language="java">// here we do not bother with root class.
-// Procedure name gives us needed routing information
-ProcedureQuery query = new ProcedureQuery("my_procedure");
-
-query.addParam("p1", "abc");
-query.addParam("p2", 3000);
-
-QueryResponse response = context.performGenericQuery(query); </programlisting></para>
- <para>A stored procedure can return data back to the application as result sets or via OUT
- parameters. To simplify the processing of the query output, QueryResponse treats OUT
- parameters as if it was a separate result set. If a stored procedure declares any OUT or
- INOUT parameters, QueryResponse will contain their returned values in the very first
- result
- list:<programlisting language="java">ProcedureQuery query = new ProcedureQuery("my_procedure");
-QueryResponse response = context.performGenericQuery(query);
-
-// read OUT parameters
-List out = response.firstList();
-
-if(!out.isEmpty()) {
- Map outParameterValues = (Map) outList.get(0);
-}</programlisting></para>
- <para>There maybe a situation when a stored procedure handles its own transactions, but an
- application is configured to use Cayenne-managed transactions. This is obviously
- conflicting and undesirable behavior. In this case ProcedureQueries should be executed
- explicitly wrapped in an "external" Transaction. This is one of the few cases when a
- user should worry about transactions at all. See Transactions section for more
- details.</para>
- <para>
- <warning>
- <para>This query is superseded by <code>ProcedureCall</code> and generally shouldn't be used.</para>
- </warning>
- </para>
-</section>
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/cayenne-guide/src/docbkx/queries-procedurecall.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/cayenne-guide/src/docbkx/queries-procedurecall.xml b/docs/docbook/cayenne-guide/src/docbkx/queries-procedurecall.xml
deleted file mode 100644
index 394a21e..0000000
--- a/docs/docbook/cayenne-guide/src/docbkx/queries-procedurecall.xml
+++ /dev/null
@@ -1,61 +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.
- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~-->
-<section xmlns="http://docbook.org/ns/docbook" xml:id="procedurecallquery">
- <title>ProcedureCall</title>
- <para>Stored procedures are mapped as separate objects in CayenneModeler. <code>ProcedureCall</code>
- provides a way to execute them with a certain set of parameters. This query is a "fluent" version of
- older <code>ProcedureQuery</code>.
- Just like with <code>SQLTemplate</code>, the outcome of a procedure can be anything - a single result set, multiple
- result sets, some data modification (returned as an update count), or a combination of these.
- So use root class to get a single result set, and use only procedure name
- for anything else:
- <programlisting language="java"><![CDATA[List<Artist> result = ProcedureCall.query("my_procedure", Artist.class)
- .param("p1", "abc")
- .param("p2", 3000)
- .call(context)
- .firstList();]]></programlisting>
-
- <programlisting language="java"><![CDATA[// here we do not bother with root class.
-// Procedure name gives us needed routing information
-ProcedureResult result = ProcedureCall.query("my_procedure")
- .param("p1", "abc")
- .param("p2", 3000)
- .call();]]></programlisting>
- </para>
- <para>A stored procedure can return data back to the application as result sets or via OUT
- parameters. To simplify the processing of the query output, QueryResponse treats OUT
- parameters as if it was a separate result set. For stored procedures declaref any OUT or
- INOUT parameters, <code>ProcedureResult</code> have convenient utility method to get them:
- <programlisting language="java">ProcedureResult result = ProcedureCall.query("my_procedure")
- .call(context);
-
-// read OUT parameters
-Object out = result.getOutParam("out_param");
-</programlisting>
- </para>
- <para>
- There maybe a situation when a stored procedure handles its own transactions, but an
- application is configured to use Cayenne-managed transactions. This is obviously
- conflicting and undesirable behavior. In this case ProcedureQueries should be executed
- explicitly wrapped in an "external" Transaction. This is one of the few cases when a
- user should worry about transactions at all. See Transactions section for more
- details.
- </para>
-</section>
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/cayenne-guide/src/docbkx/queries-select.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/cayenne-guide/src/docbkx/queries-select.xml b/docs/docbook/cayenne-guide/src/docbkx/queries-select.xml
deleted file mode 100644
index 3e00d85..0000000
--- a/docs/docbook/cayenne-guide/src/docbkx/queries-select.xml
+++ /dev/null
@@ -1,111 +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.
--->
-<section xmlns="http://docbook.org/ns/docbook" xml:id="selectquery">
- <title>ObjectSelect</title>
- <section>
- <title>Selecting objects</title>
- <para>
- <emphasis role="italic">ObjectSelect supersedes older SelectQuery. SelectQuery is still
- available and supported. </emphasis>
- </para>
- <para>ObjectSelect is the most commonly used query in Cayenne applications. This may be the
- only query you will ever need. It returns a list of persistent objects (or data rows) of
- a certain type specified in the
- query:
- <programlisting language="java">List<Artist> objects = ObjectSelect.query(Artist.class).select(context);</programlisting>
- This returned all rows in the "ARTIST" table. If the logs were turned on, you might see the
- following SQL printed:
- <screen>INFO: SELECT t0.DATE_OF_BIRTH, t0.NAME, t0.ID FROM ARTIST t0
-INFO: === returned 5 row. - took 5 ms.</screen>
- </para>
- <para>This SQL was generated by Cayenne from the ObjectSelect above. ObjectSelect can have a
- qualifier to select only the data matching specific criteria. Qualifier is simply an
- Expression (Expressions where discussed in the previous chapter), appended to the query
- using "where" method. If you only want artists whose name begins with 'Pablo', you might
- use the following qualifier expression:
- <programlisting language="java">List<Artist> objects = ObjectSelect.query(Artist.class)
- .where(Artist.NAME.like("Pablo%"))
- .select(context);</programlisting>
- The SQL will look different this time:
- <screen>INFO: SELECT t0.DATE_OF_BIRTH, t0.NAME, t0.ID FROM ARTIST t0 WHERE t0.NAME LIKE ?
-[bind: 1->NAME:'Pablo%']
-INFO: === returned 1 row. - took 6 ms.</screen>
- </para>
- <para>ObjectSelect allows to assemble qualifier from parts, using "and" and "or" method to
- chain then together:
- <programlisting language="java">List<Artist> objects = ObjectSelect.query(Artist.class)
- .where(Artist.NAME.like("A%"))
- .and(Artist.DATE_OF_BIRTH.gt(someDate)
- .select(context);</programlisting>
- </para>
- <para>To order the results of ObjectSelect, one or more orderings can be applied:
- <programlisting language="java">List<Artist> objects = ObjectSelect.query(Artist.class)
- .orderBy(Artist.DATE_OF_BIRTH.desc())
- .orderBy(Artist.NAME.asc())
- .select(context);</programlisting>
- </para>
- <para>There's a number of other useful methods in ObjectSelect that define what to select
- and how to optimize database interaction (prefetching, caching, fetch offset and limit,
- pagination, etc.). Some of them are discussed in separate chapters on caching and
- performance optimization. Others are fairly self-explanatory. Please check the API docs
- for the full extent of the ObjectSelect features.
- </para>
- </section>
- <section>
- <title>Selecting individual columns</title>
- <para>
- <code>ObjectSelect</code> query can be used to fetch individual properties of objects via
- type-safe API:
- <programlisting language="java"><![CDATA[List<String> names = ObjectSelect.columnQuery(Artist.class, Artist.ARTIST_NAME)
- .select(context);]]></programlisting>
- And here is example of selecting several properties, note that result will be <code>Object[]</code>:
- <programlisting language="java"><![CDATA[List<Object[]> nameAndDate = ObjectSelect
- .columnQuery(Artist.class, Artist.ARTIST_NAME, Artist.DATE_OF_BIRTH)
- .select(context);]]></programlisting>
- </para>
- </section>
- <section>
- <title>Selecting aggregate functions</title>
- <para>
- ObjectSelect query supports usage of aggregate functions.
- Most common variant of aggregation is selecting count of records, this can be done really easy:
- <programlisting language="java"><![CDATA[long count = ObjectSelect.query(Artist.class).selectCount(context);]]></programlisting>
- But you can use aggregates in more cases, even combine selecting individual properties and aggregates:
- <programlisting language="java"><![CDATA[// this is artificial property signaling that we want to get full object
-Property<Artist> artistProperty = Property.createSelf(Artist.class);
-
-List<Object[]> artistAndPaintingCount = ObjectSelect.columnQuery(Artist.class, artistProperty, Artist.PAINTING_ARRAY.count())
- .where(Artist.ARTIST_NAME.like("a%"))
- .having(Artist.PAINTING_ARRAY.count().lt(5L))
- .orderBy(Artist.PAINTING_ARRAY.count().desc(), Artist.ARTIST_NAME.asc())
- .select(context);
-
-for(Object[] next : artistAndPaintingCount) {
- Artist artist = (Artist)next[0];
- long paintings = (Long)next[1];
- System.out.println(artist.getArtistName() + " have " + paintings + " paintings");
-}]]></programlisting>
- Here is generated <code>SQL</code> for this query:
- <programlisting language="sql">SELECT DISTINCT t0.ARTIST_NAME, t0.DATE_OF_BIRTH, t0.ARTIST_ID, COUNT(t1.PAINTING_ID)
-FROM ARTIST t0 JOIN PAINTING t1 ON (t0.ARTIST_ID = t1.ARTIST_ID)
-WHERE t0.ARTIST_NAME LIKE ?
-GROUP BY t0.ARTIST_NAME, t0.ARTIST_ID, t0.DATE_OF_BIRTH
-HAVING COUNT(t1.PAINTING_ID) < ?
-ORDER BY COUNT(t1.PAINTING_ID) DESC, t0.ARTIST_NAME</programlisting>
- </para>
- </section>
-</section>
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/cayenne-guide/src/docbkx/queries-selectbyid.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/cayenne-guide/src/docbkx/queries-selectbyid.xml b/docs/docbook/cayenne-guide/src/docbkx/queries-selectbyid.xml
deleted file mode 100644
index 59940f9..0000000
--- a/docs/docbook/cayenne-guide/src/docbkx/queries-selectbyid.xml
+++ /dev/null
@@ -1,33 +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.
- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~-->
-<section xmlns="http://docbook.org/ns/docbook" xml:id="selectbyid">
- <title>SelectById</title>
- <para>
- This query allows to search objects by their ID.
- It's introduced in Cayenne 4.0 and uses new "fluent" API same as <code>ObjectSelect</code> query.
- </para>
- <para>
- Here is example of how to use it:
- <programlisting language="java"><![CDATA[Artist artistWithId1 = SelectById.query(Artist.class, 1)
- .prefetch(Artist.PAINTING_ARRAY.joint())
- .localCache()
- .selectOne(context);]]></programlisting>
- </para>
-</section>
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/cayenne-guide/src/docbkx/queries-sqlselect.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/cayenne-guide/src/docbkx/queries-sqlselect.xml b/docs/docbook/cayenne-guide/src/docbkx/queries-sqlselect.xml
deleted file mode 100644
index e488fab..0000000
--- a/docs/docbook/cayenne-guide/src/docbkx/queries-sqlselect.xml
+++ /dev/null
@@ -1,45 +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.
- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~-->
-<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sqlselect">
- <title>SQLSelect and SQLExec</title>
- <para>
- <code>SQLSelect</code> and <code>SQLExec</code> are essentially a "fluent" versions of older <code>SQLTemplate</code> query.
- <code>SQLSelect</code> can be used (as name suggests) to select custom data in form of entities, separate columns or collection of <code>DataRow</code>.
- <code>SQLExec</code> is designed to just execute any raw SQL code (e.g. updates, deletes, DDLs, etc.)
- These queries support all directives described in <link linkend="sqltemplate">SQLTemplate</link> section.
- </para>
- <para>
- Here is example of how to use <code>SQLSelect</code>:
- <programlisting language="java"><![CDATA[SQLSelect<Painting> q1 = SQLSelect
- .query(Painting.class, "SELECT * FROM PAINTING WHERE PAINTING_TITLE LIKE #bind($title)")
- .params("title", "painting%")
- .upperColumnNames()
- .localCache()
- .limit(100)
- .select(context);]]></programlisting>
- </para>
- <para>
- And here is example of how to use <code>SQLExec</code>:
- <programlisting language="java"><![CDATA[int inserted = SQLExec
- .query("INSERT INTO ARTIST (ARTIST_ID, ARTIST_NAME) VALUES (#bind($id), #bind($name))")
- .paramsArray(55, "Picasso")
- .update(context);]]></programlisting>
- </para>
-</section>
\ No newline at end of file
[06/13] cayenne git commit: CAY-2371 Switch documentation from
Docbook to Asciidoctor format
Posted by nt...@apache.org.
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/cayenne-guide/src/docbkx/including-cayenne-in-project.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/cayenne-guide/src/docbkx/including-cayenne-in-project.xml b/docs/docbook/cayenne-guide/src/docbkx/including-cayenne-in-project.xml
deleted file mode 100644
index 6cc7050..0000000
--- a/docs/docbook/cayenne-guide/src/docbkx/including-cayenne-in-project.xml
+++ /dev/null
@@ -1,893 +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.
--->
-<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
- version="5.0" xml:id="including-cayenne-in-project">
- <title>Including Cayenne in a Project</title>
- <section xml:id="jar-files-and-depdendencies">
- <title>Jar Files</title>
- <para>This is an overview of Cayenne jars that is agnostic of the build tool used. The
- following are the important libraries:</para>
- <para>
- <itemizedlist>
- <listitem>
- <para><emphasis role="italic"
- >cayenne-di-<?eval ${project.version}?>.jar</emphasis> - Cayenne
- dependency injection (DI) container library. All applications will require
- this file.</para>
- </listitem>
- <listitem>
- <para><emphasis role="italic"
- >cayenne-server-<?eval ${project.version}?>.jar</emphasis> - contains
- main Cayenne runtime (adapters, DB access classes, etc.). Most applications
- will require this file.</para>
- </listitem>
- <listitem>
- <para><emphasis>cayenne-client-<?eval ${project.version}?>.jar</emphasis> - a
- client-side runtime for <link linkend="introduction-to-rop">ROP
- applications</link>.</para>
- </listitem>
- <listitem>
- <para>Other cayenne-* jars - various Cayenne tools extensions.</para>
- </listitem>
- </itemizedlist>
- </para>
- </section>
- <section>
- <title>Dependencies</title>
- <para>With modern build tools like Maven and Gradle, you should not worry about tracking
- dependencies. If you have one of those, you can skip this section and go straight to the
- Maven section below. However if your environment requires manual dependency resolution
- (like Ant), the distribution provides all of Cayenne jars plus a minimal set of
- third-party dependencies to get you started in a default configuration. Check
- <code>lib</code> and <code>lib/third-party</code> folders for those.</para>
- <para>Dependencies for non-standard configurations will need to be figured out by the users
- on their own. Check <code>pom.xml</code> files of the corresponding Cayenne modules in
- one of the searchable Maven archives out there to get an idea of those dependencies
- (e.g. <link xlink:href="http://search.maven.org">http://search.maven.org</link>).</para>
- </section>
- <section xml:id="maven-projects">
- <title>Maven Projects</title>
- <para>If you are using Maven, you won't have to deal with figuring out the dependencies. You
- can simply include cayenne-server artifact in your
- POM:<programlisting language="xml"><dependency>
- <groupId>org.apache.cayenne</groupId>
- <artifactId>cayenne-server</artifactId>
- <version><?eval ${project.version}?></version>
-</dependency></programlisting></para>
- <para>Additionally Cayenne provides a Maven plugin with a set of goals to perform various project
- tasks, such as synching generated Java classes with the mapping, described in the
- following subsection. The full plugin name is
- <code>org.apache.cayenne.plugins:cayenne-maven-plugin</code>.</para>
- <section xml:id="mvn-cgen">
- <title>cgen</title>
- <para><code>cgen</code> is a <code>cayenne-maven-plugin</code> goal that generates and maintains
- source (.java) files of persistent objects based on a DataMap. By default, it is
- bound to the generate-sources phase. If "makePairs" is set to "true" (which is the
- recommended default), this task will generate a pair of classes
- (superclass/subclass) for each ObjEntity in the DataMap. Superclasses should not be
- changed manually, since they are always overwritten. Subclasses are never
- overwritten and may be later customized by the user. If "makePairs" is set to
- "false", a single class will be generated for each ObjEntity. </para>
- <para>By creating custom templates, you can use cgen to generate other output (such as
- web pages, reports, specialized code templates) based on DataMap information.</para>
- <para>
- <table frame="void" xml:id="cgen_params_table">
- <caption>cgen required parameters</caption>
- <col width="14%"/>
- <col width="7%"/>
- <col width="79%"/>
- <thead>
- <tr>
- <th>Name</th>
- <th>Type</th>
- <th>Description</th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td><code>map</code>
- </td>
- <td>File</td>
- <td>DataMap XML file which serves as a source of metadata for class
- generation. E.g.
- <code>${project.basedir}/src/main/resources/my.map.xml</code></td>
- </tr>
- </tbody>
- </table>
- <table frame="void">
- <caption>cgen optional parameters</caption>
- <col width="14%"/>
- <col width="7%"/>
- <col width="79%"/>
- <thead>
- <tr>
- <th>Name</th>
- <th>Type</th>
- <th>Description</th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td><code>additionalMaps</code>
- </td>
- <td>File</td>
- <td>A directory that contains additional DataMap XML files that may be
- needed to resolve cross-DataMap relationships for the the main
- DataMap, for which class generation occurs.</td>
- </tr>
- <tr>
- <td><code>client</code></td>
- <td>boolean</td>
- <td>Whether we are generating classes for the client tier in a Remote
- Object Persistence application. "False" by default.</td>
- </tr>
- <tr>
- <td><code>destDir</code></td>
- <td>File</td>
- <td>Root destination directory for Java classes (ignoring their package
- names). The default is "src/main/java".</td>
- </tr>
- <tr>
- <td><code>embeddableTemplate</code></td>
- <td>String</td>
- <td>Location of a custom Velocity template file for Embeddable class
- generation. If omitted, default template is used.</td>
- </tr>
- <tr>
- <td><code>embeddableSuperTemplate</code></td>
- <td>String</td>
- <td>Location of a custom Velocity template file for Embeddable
- superclass generation. Ignored unless "makepairs" set to "true". If
- omitted, default template is used.</td>
- </tr>
- <tr>
- <td><code>encoding</code></td>
- <td>String</td>
- <td>Generated files encoding if different from the default on current
- platform. Target encoding must be supported by the JVM running the
- build. Standard encodings supported by Java on all platforms are
- US-ASCII, ISO-8859-1, UTF-8, UTF-16BE, UTF-16LE, UTF-16. See
- javadocs for java.nio.charset.Charset for more information.</td>
- </tr>
- <tr>
- <td><code>excludeEntities</code></td>
- <td>String</td>
- <td>A comma-separated list of ObjEntity patterns (expressed as a perl5
- regex) to exclude from template generation. By default none of the
- DataMap entities are excluded.</td>
- </tr>
- <tr>
- <td><code>includeEntities</code></td>
- <td>String</td>
- <td>A comma-separated list of ObjEntity patterns (expressed as a perl5
- regex) to include from template generation. By default all DataMap
- entities are included.</td>
- </tr>
- <tr>
- <td><code>makePairs</code></td>
- <td>boolean</td>
- <td>If "true" (a recommended default), will generate subclass/superclass
- pairs, with all generated code placed in superclass.</td>
- </tr>
- <tr>
- <td><code>mode</code></td>
- <td>String</td>
- <td>Specifies class generator iteration target. There are three possible
- values: "entity" (default), "datamap", "all". "entity" performs one
- generator iteration for each included ObjEntity, applying either
- standard to custom entity templates. "datamap" performs a single
- iteration, applying DataMap templates. "All" is a combination of
- entity and datamap.</td>
- </tr>
- <tr>
- <td><code>overwrite</code></td>
- <td>boolean</td>
- <td>Only has effect when "makePairs" is set to "false". If "overwrite"
- is "true", will overwrite older versions of generated classes.</td>
- </tr>
- <tr>
- <td><code>superPkg</code></td>
- <td>String</td>
- <td>Java package name of all generated superclasses. If omitted, each
- superclass will be placed in the subpackage of its subclass called
- "auto". Doesn't have any effect if either "makepairs" or
- "usePkgPath" are false (both are true by default). </td>
- </tr>
- <tr>
- <td><code>superTemplate</code></td>
- <td>String</td>
- <td>Location of a custom Velocity template file for ObjEntity superclass
- generation. Only has effect if "makepairs" set to "true". If
- omitted, default template is used.</td>
- </tr>
- <tr>
- <td><code>template</code></td>
- <td>String</td>
- <td>Location of a custom Velocity template file for ObjEntity class
- generation. If omitted, default template is used.</td>
- </tr>
- <tr>
- <td><code>usePkgPath</code></td>
- <td>boolean</td>
- <td>If set to "true" (default), a directory tree will be generated in
- "destDir" corresponding to the class package structure, if set to
- "false", classes will be generated in "destDir" ignoring their
- package.</td>
- </tr>
- <tr>
- <td><code>createPropertyNames</code></td>
- <td>boolean</td>
- <td>If set to "true", will generate String Property names.
- Default is "false"</td>
- </tr>
- </tbody>
- </table> Example - a typical class generation scenario, where pairs of classes are
- generated with default Maven source destination and superclass
- package:<programlisting language="xml"><plugin>
- <groupId>org.apache.cayenne.plugins</groupId>
- <artifactId>cayenne-maven-plugin</artifactId>
- <version><?eval ${project.version}?></version>
-
- <configuration>
- <map>${project.basedir}/src/main/resources/my.map.xml</map>
- </configuration>
-
- <executions>
- <execution>
- <goals>
- <goal>cgen</goal>
- </goals>
- </execution>
- </executions>
-</plugin></programlisting></para>
- </section>
- <section xml:id="mvn-cdbgen">
- <title>cdbgen</title>
- <para><code>cdbgen</code> is a <code>cayenne-maven-plugin</code> goal that drops and/or generates
- tables in a database on Cayenne DataMap. By default, it is bound to the
- pre-integration-test phase.
- <table frame="void" xml:id="cdbgen_parameters">
- <caption>cdbgen required parameters</caption>
- <col width="14%"/>
- <col width="7%"/>
- <col width="79%"/>
- <thead>
- <tr>
- <th>Name</th>
- <th>Type</th>
- <th>Description</th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td><code>map</code>
- </td>
- <td>File</td>
- <td>DataMap XML file which serves as a source of metadata for DB schema
- generation. E.g.
- <code>${project.basedir}/src/main/resources/my.map.xml</code></td>
- </tr>
- <tr>
- <td><code>dataSource</code>
- </td>
- <td>XML</td>
- <td>An object that contains Data Source parameters</td>
- </tr>
- </tbody>
- </table>
- </para>
- <para>
- <table frame="void">
- <caption><dataSource> parameters</caption>
- <col width="14%"/>
- <col width="7%"/>
- <col width="7%"/>
- <col width="72%"/>
- <thead>
- <tr>
- <th>Name</th>
- <th>Type</th>
- <th>Required</th>
- <th>Description</th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td><code>driver</code></td>
- <td>String</td>
- <td>Yes</td>
- <td>A class of JDBC driver to use for the target database.</td>
- </tr>
- <tr>
- <td><code>url</code></td>
- <td>String</td>
- <td>Yes</td>
- <td>JDBC URL of a target database.</td>
- </tr>
- <tr>
- <td><code>username</code></td>
- <td>String</td>
- <td>No</td>
- <td>Database user name.</td>
- </tr>
- <tr>
- <td><code>password</code></td>
- <td>String</td>
- <td>No</td>
- <td>Database user password.</td>
- </tr>
- </tbody>
- </table>
- </para>
- <para>
- <table frame="void">
- <caption>cdbgen optional parameters</caption>
- <col width="14%"/>
- <col width="7%"/>
- <col width="79%"/>
- <thead>
- <tr>
- <th>Name</th>
- <th>Type</th>
- <th>Description</th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td><code>adapter</code>
- </td>
- <td>String</td>
- <td>Java class name implementing org.apache.cayenne.dba.DbAdapter. While
- this attribute is optional (a generic JdbcAdapter is used if not
- set), it is highly recommended to specify correct target
- adapter.</td>
- </tr>
- <tr>
- <td><code>createFK</code></td>
- <td>boolean</td>
- <td>Indicates whether cdbgen should create foreign key constraints. Default is "true".</td>
- </tr>
- <tr>
- <td><code>createPK</code></td>
- <td>boolean</td>
- <td>Indicates whether cdbgen should create Cayenne-specific auto PK objects. Default is
- "true".</td>
- </tr>
- <tr>
- <td><code>createTables</code></td>
- <td>boolean</td>
- <td>Indicates whether cdbgen should create new tables. Default is "true".</td>
- </tr>
- <tr>
- <td><code>dropPK</code></td>
- <td>boolean</td>
- <td>Indicates whether cdbgen should drop Cayenne primary key support objects. Default is
- "false".</td>
- </tr>
- <tr>
- <td><code>dropTables</code></td>
- <td>boolean</td>
- <td>Indicates whether cdbgen should drop the tables before attempting to create new ones.
- Default is "false".</td>
- </tr>
- </tbody>
- </table>
- </para>
- <para>Example - creating a DB schema on a local HSQLDB
- database:<programlisting language="xml"><plugin>
- <groupId>org.apache.cayenne.plugins</groupId>
- <artifactId>cayenne-maven-plugin</artifactId>
- <version><?eval ${project.version}?></version>
- <executions>
- <execution>
- <configuration>
- <map>${project.basedir}/src/main/resources/my.map.xml</map>
- <adapter>org.apache.cayenne.dba.hsqldb.HSQLDBAdapter</adapter>
- <dataSource>
- <url>jdbc:hsqldb:hsql://localhost/testdb</url>
- <driver>org.hsqldb.jdbcDriver</driver>
- <username>sa</username>
- </dataSource>
- </configuration>
- <goals>
- <goal>cdbgen</goal>
- </goals>
- </execution>
- </executions>
-</plugin></programlisting></para>
- </section>
- <section xml:id="mvn-cdbimport">
- <title>cdbimport</title>
- <para><code>cdbimport</code> is a <code>cayenne-maven-plugin</code> goal that generates a DataMap
- based on an existing database schema. By default, it is bound to the
- generate-sources phase. This allows you to generate your DataMap prior to building
- your project, possibly followed by "cgen" execution to generate the classes.
- CDBImport plugin described in details in chapter <link linkend="re-introduction">"DB-First Flow"</link>
- <table frame="void" xml:id="cdbimport_parameters">
- <caption>cdbimport parameters</caption>
- <col width="14%"/>
- <col width="7%"/>
- <col width="7%"/>
- <col width="72%"/>
- <thead>
- <tr>
- <th>Name</th>
- <th>Type</th>
- <th>Required</th>
- <th>Description</th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td><code>map</code>
- </td>
- <td>File</td>
- <td>Yes</td>
- <td>DataMap XML file which is the destination of the schema import. Can
- be an existing file. If this file does not exist, it is created when
- cdbimport is executed. E.g.
- <code>${project.basedir}/src/main/resources/my.map.xml</code>.
- If "overwrite" is true (the default), an existing DataMap will be
- used as a template for the new imported DataMap, i.e. all its
- entities will be cleared and recreated, but its common settings,
- such as default Java package, will be preserved (unless changed
- explicitly in the plugin configuration).</td>
- </tr>
- <tr>
- <td><code>adapter</code>
- </td>
- <td>String</td>
- <td>No</td>
- <td>A Java class name implementing org.apache.cayenne.dba.DbAdapter. This attribute is
- optional. If not specified, AutoAdapter is used, which will attempt
- to guess the DB type.</td>
- </tr>
- <tr>
- <td><code>dataSource</code>
- </td>
- <td>XML</td>
- <td>Yes</td>
- <td>An object that contains Data Source parameters</td>
- </tr>
- <tr>
- <td><code>dbimport</code>
- </td>
- <td>XML</td>
- <td>No</td>
- <td>An object that contains detailed reverse engineering rules about what DB objects should
- be processed. For full information about this parameter see <link
- linkend="re-introduction">"DB-First Flow"</link> chapter.</td>
- </tr>
- </tbody>
- </table>
- </para>
- <para>
- <table frame="void">
- <caption><dataSource> parameters</caption>
- <col width="14%"/>
- <col width="7%"/>
- <col width="7%"/>
- <col width="72%"/>
- <thead>
- <tr>
- <th>Name</th>
- <th>Type</th>
- <th>Required</th>
- <th>Description</th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td><code>driver</code></td>
- <td>String</td>
- <td>Yes</td>
- <td>A class of JDBC driver to use for the target database.</td>
- </tr>
- <tr>
- <td><code>url</code></td>
- <td>String</td>
- <td>Yes</td>
- <td>JDBC URL of a target database.</td>
- </tr>
- <tr>
- <td><code>username</code></td>
- <td>String</td>
- <td>No</td>
- <td>Database user name.</td>
- </tr>
- <tr>
- <td><code>password</code></td>
- <td>String</td>
- <td>No</td>
- <td>Database user password.</td>
- </tr>
- </tbody>
- </table>
- </para>
- <para>
- <table frame="void">
- <caption><dbimport> parameters</caption>
- <col width="14%"/>
- <col width="7%"/>
- <col width="79%"/>
- <thead>
- <tr>
- <th>Name</th>
- <th>Type</th>
- <th>Description</th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td><code>defaultPackage</code></td>
- <td>String</td>
- <td>A Java package that will be set as the imported DataMap default and
- a package of all the persistent Java classes. This is a required
- attribute if the "map" itself does not already contain a default
- package, as otherwise all the persistent classes will be mapped with
- no package, and will not compile.</td>
- </tr>
- <tr>
- <td><code>forceDataMapCatalog</code></td>
- <td>boolean</td>
- <td> Automatically tagging each DbEntity with the actual DB catalog/schema (default behavior)
- may sometimes be undesirable. If this is the case then setting
- <code>forceDataMapCatalog</code> to <code>true</code> will set
- DbEntity catalog to one in the DataMap. Default value is
- <code>false</code>. </td>
- </tr>
- <tr>
- <td><code>forceDataMapSchema</code></td>
- <td>boolean</td>
- <td> Automatically tagging each DbEntity with the actual DB catalog/schema (default behavior)
- may sometimes be undesirable. If this is the case then setting
- <code>forceDataMapSchema</code> to <code>true</code> will set
- DbEntity schema to one in the DataMap. Default value is
- <code>false</code>. </td>
- </tr>
- <tr>
- <td><code>meaningfulPkTables</code></td>
- <td>String</td>
- <td>A comma-separated list of Perl5 patterns that defines which imported tables should have
- their primary key columns mapped as ObjAttributes. "*" would
- indicate all tables.</td>
- </tr>
- <tr>
- <td><code>namingStrategy</code></td>
- <td>String</td>
- <td>
- The naming strategy used for mapping database names to object entity
- names. Default is <code>org.apache.cayenne.dbsync.naming.DefaultObjectNameGenerator</code>.
- </td>
- </tr>
- <tr>
- <td><code>skipPrimaryKeyLoading</code></td>
- <td>boolean</td>
- <td>Whether to load primary keys. Default "false".</td>
- </tr>
- <tr>
- <td><code>skipRelationshipsLoading</code></td>
- <td>boolean</td>
- <td>Whether to load relationships. Default "false".</td>
- </tr>
- <tr>
- <td><code>stripFromTableNames</code></td>
- <td>String</td>
- <td>Regex that matches the part of the table name that needs to be stripped off when
- generating ObjEntity name. Here are some examples: <programlisting language="xml"><![CDATA[<!-- Strip prefix -->
-<stripFromTableNames>^myt_</stripFromTableNames>
-
-<!-- Strip suffix -->
-<stripFromTableNames>_s$</stripFromTableNames>
-
-<!-- Strip multiple occurrences in the middle -->
-<stripFromTableNames>_abc</stripFromTableNames>]]></programlisting>
- </td>
- </tr>
- <tr>
- <td><code>usePrimitives</code></td>
- <td>boolean</td>
- <td>Whether numeric and boolean data types should be mapped as Java primitives or Java
- classes. Default is "true", i.e. primitives will be used.</td>
- </tr>
- <tr>
- <td><code>useJava7Types</code></td>
- <td>boolean</td>
- <td>Whether <code>DATE</code>, <code>TIME</code> and <code>TIMESTAMP</code> data types should be mapped
- as <code>java.util.Date</code> or <code>java.time.*</code> classes.
- Default is "false", i.e. <code>java.time.*</code> will be used.</td>
- </tr>
- <tr xml:id="cdbimport-rr-parameter">
- <td>filters configuration</td>
- <td>XML</td>
- <td>Detailed reverse engineering rules about what DB objects should be processed.
- For full information about this parameter see <link linkend="re-introduction">"DB-First Flow"</link> chapter.
- Here is some simple example:
- <programlisting language="xml"><dbimport>
- <catalog name="test_catalog">
- <schema name="test_schema">
- <includeTable>.*</includeTable>
- <excludeTable>test_table</excludeTable>
- </schema>
- </catalog>
-
- <includeProcedure pattern=".*"/>
-</dbimport></programlisting>
- </td>
- </tr>
- </tbody>
- </table>
- </para>
- <para>Example - loading a DB schema from a local HSQLDB database (essentially a reverse operation
- compared to the <code>cdbgen</code> example above)
- :<programlisting language="xml"><plugin>
- <groupId>org.apache.cayenne.plugins</groupId>
- <artifactId>cayenne-maven-plugin</artifactId>
- <version><?eval ${project.version}?></version>
-
- <executions>
- <execution>
- <configuration>
- <map>${project.basedir}/src/main/resources/my.map.xml</map>
- <dataSource>
- <url>jdbc:mysql://127.0.0.1/mydb</url>
- <driver>com.mysql.jdbc.Driver</driver>
- <username>sa</username>
- </dataSource>
- <dbimport>
- <defaultPackage>com.example.cayenne</defaultPackage>
- </dbimport>
- </configuration>
- <goals>
- <goal>cdbimport</goal>
- </goals>
- </execution>
- </executions>
-</plugin></programlisting></para>
- </section>
- </section>
- <section xml:id="gradle-projects">
- <title>Gradle Projects</title>
- <para>
- To include Cayenne into your Gradle project you have two options:
- <itemizedlist>
- <listitem><para>
- Simply add Cayenne as a dependency:
- <programlisting language="groovy">compile 'org.apache.cayenne:cayenne-server:<?eval ${project.version}?>'</programlisting>
- </para></listitem>
- <listitem>
- <para>Or you can use Cayenne Gradle plugin</para>
- </listitem>
- </itemizedlist>
- </para>
- <section xml:id="gradle-plugin">
- <title>Gradle Plugin</title>
- <para>
- Cayenne Gradle plugin provides several tasks, such as synching generated Java classes with the mapping
- or synching mapping with the database. Plugin aslo provides <code>cayenne</code> extension that have some
- useful utility methods.
- Here is example of how to include Cayenne plugin into your project:
- <programlisting language="groovy">
-buildscript {
- // add Maven Central repository
- repositories {
- mavenCentral()
- }
- // add Cayenne Gradle Plugin
- dependencies {
- classpath group: 'org.apache.cayenne.plugins', name: 'cayenne-gradle-plugin', version: '<?eval ${project.version}?>'
- }
-}
-
-// apply plugin
-apply plugin: 'org.apache.cayenne'
-
-// set default DataMap
-cayenne.defaultDataMap 'datamap.map.xml'
-
-// add Cayenne dependencies to your project
-dependencies {
- // this is a shortcut for 'org.apache.cayenne:cayenne-server:VERSION_OF_PLUGIN'
- compile cayenne.dependency('server')
- compile cayenne.dependency('java8')
-}</programlisting>
- </para>
- <para>
- <warning>
- Cayenne Gradle plugin is experimental and it's API can change later.
- </warning>
- </para>
- <section>
- <title>cgen</title>
- <para>
- Cgen task generates Java classes based on your DataMap,
- it has same configuration parameters as in Maven Plugin version, described in
- <xref linkend="cgen_params_table"/>.
- If you provided default DataMap via <code>cayenne.defaultDataMap</code>,
- you can skip <code>cgen</code> configuration as default settings will suffice in common case.
- </para>
- <para>
- Here is how you can change settings of the default <code>cgen</code> task:
- <programlisting language="groovy">
-cgen {
- client = false
- mode = 'all'
- overwrite = true
- createPropertiesNames = true
-}</programlisting>
-
- And here is example of how to define additional cgen task (e.g. for client classes if you are using ROP):
- <programlisting language="groovy">
-task clientCgen(type: cayenne.cgen) {
- client = true
-}</programlisting>
- </para>
- </section>
- <section>
- <title>cdbimport</title>
- <para>
- This task is for creating and synchronizing your Cayenne model from database schema.
- Full list of parameters are same as in Maven Plugin version, described in
- <xref linkend="cdbimport_parameters"/>, with exception that Gradle version will use Groovy instead
- of XML.
- </para>
- <para>
- Here is example of configuration for cdbimport task:
- <programlisting language="groovy">
-cdbimport {
- // map can be skipped if it is defined in cayenne.defaultDataMap
- map 'datamap.map.xml'
-
- dataSource {
- driver 'com.mysql.cj.jdbc.Driver'
- url 'jdbc:mysql://127.0.0.1:3306/test?useSSL=false'
- username 'root'
- password ''
- }
-
- dbImport
- // additional settings
- usePrimitives false
- defaultPackage 'org.apache.cayenne.test'
-
- // DB filter configuration
- catalog 'catalog-1'
- schema 'schema-1'
-
- catalog {
- name 'catalog-2'
-
- includeTable 'table0', {
- excludeColumns '_column_'
- }
-
- includeTables 'table1', 'table2', 'table3'
-
- includeTable 'table4', {
- includeColumns 'id', 'type', 'data'
- }
-
- excludeTable '^GENERATED_.*'
- }
-
- catalog {
- name 'catalog-3'
- schema {
- name 'schema-2'
- includeTable 'test_table'
- includeTable 'test_table2', {
- excludeColumn '__excluded'
- }
- }
- }
-
- includeProcedure 'procedure_test_1'
-
- includeColumns 'id', 'version'
-
- tableTypes 'TABLE', 'VIEW'
- }
-}</programlisting>
- </para>
- </section>
- <section>
- <title>cdbgen</title>
- <para>
- Cdbgen task drops and/or generates tables in a database on Cayenne DataMap.
- Full list of parameters are same as in Maven Plugin version, described in
- <xref linkend="cdbgen_parameters"/>
- </para>
- <para>
- Here is example of how to configure default <code>cdbgen</code> task:
- <programlisting language="groovy">
-cdbgen {
-
- adapter 'org.apache.cayenne.dba.derby.DerbyAdapter'
-
- dataSource {
- driver 'org.apache.derby.jdbc.EmbeddedDriver'
- url 'jdbc:derby:build/testdb;create=true'
- username 'sa'
- password ''
- }
-
- dropTables true
- dropPk true
-
- createTables true
- createPk true
- createFk true
-}</programlisting>
- </para>
- </section>
- <section>
- <title>Link tasks to Gradle build lifecycle</title>
- <para>
- With gradle you can easily connect Cayenne tasks to default build lifecycle.
- Here is short example of how to connect defaut <code>cgen</code> and <code>cdbimport</code> tasks
- with <code>compileJava</code> task:
- <programlisting language="groovy">cgen.dependsOn cdbimport
-compileJava.dependsOn cgen</programlisting>
- <note>
- Running <code>cdbimport</code> automatically with build not always a good choice,
- e.g. in case of complex model that you need to alter in the Cayenne Modeler after import.
- </note>
- </para>
- </section>
- </section>
- </section>
- <section xml:id="ant-projects">
- <title>Ant Projects</title>
- <para>Ant tasks are the same as Maven plugin goals described above, namely "cgen", "cdbgen",
- "cdbimport". Configuration parameters are also similar (except Maven can guess many
- defaults that Ant can't). To include Ant tasks in the project, use the following
- Antlib:<programlisting language="xml"><typedef resource="org/apache/cayenne/tools/antlib.xml">
- <classpath>
- <fileset dir="lib" >
- <include name="cayenne-ant-*.jar" />
- <include name="cayenne-cgen-*.jar" />
- <include name="cayenne-dbsync-*.jar" />
- <include name="cayenne-di-*.jar" />
- <include name="cayenne-project-*.jar" />
- <include name="cayenne-server-*.jar" />
- <include name="commons-collections-*.jar" />
- <include name="commons-lang-*.jar" />
- <include name="slf4j-api-*.jar" />
- <include name="velocity-*.jar" />
- <include name="vpp-2.2.1.jar" />
- </fileset>
- </classpath>
-</typedef></programlisting></para>
- <section xml:id="ant-cgen">
- <title>cgen</title>
- </section>
- <section xml:id="ant-cdbgen">
- <title>cdbgen</title>
- </section>
- <section xml:id="ant-cdbimport">
- <title>cdbimport</title>
- <para>This is an Ant counterpart of "cdbimport" goal of cayenne-maven-plugin described
- above. It has exactly the same properties. Here is a usage
- example:<programlisting language="xml"> <cdbimport map="${context.dir}/WEB-INF/my.map.xml"
- driver="com.mysql.jdbc.Driver"
- url="jdbc:mysql://127.0.0.1/mydb"
- username="sa"
- defaultPackage="com.example.cayenne"/> </programlisting>
- </para>
- </section>
- </section>
-</chapter>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/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
deleted file mode 100644
index 8ac6c61..0000000
--- a/docs/docbook/cayenne-guide/src/docbkx/index.xml
+++ /dev/null
@@ -1,49 +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.
--->
-<book xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
- xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="http://docbook.org/xml/5.0/xsd/docbook.xsd" xml:id="cayenne-guide">
- <info>
- <title>Cayenne Guide</title>
- <copyright>
- <year>2011-<?dbtimestamp format="Y"?></year>
- <holder>Apache Software Foundation and individual authors</holder>
- </copyright>
- <legalnotice>
- <title>License</title>
- <para>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</para>
-
- <para>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.</para>
- </legalnotice>
- </info>
- <xi:include href="part1.xml"/>
- <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"/>
-</book>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/cayenne-guide/src/docbkx/lifecycle-events.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/cayenne-guide/src/docbkx/lifecycle-events.xml b/docs/docbook/cayenne-guide/src/docbkx/lifecycle-events.xml
deleted file mode 100644
index 09eefd6..0000000
--- a/docs/docbook/cayenne-guide/src/docbkx/lifecycle-events.xml
+++ /dev/null
@@ -1,314 +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.
--->
-<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
- version="5.0" xml:id="lifecycle-events">
- <title>Lifecycle Events</title>
- <para>An application might be interested in getting notified when a Persistent object moves
- through its lifecycle (i.e. fetched from DB, created, modified, committed). E.g. when a new
- object is created, the application may want to initialize its default properties (this can't
- be done in constructor, as constructor is also called when an object is fetched from DB).
- Before save, the application may perform validation and/or set some properties (e.g.
- "updatedTimestamp"). After save it may want to create an audit record for each saved object,
- etc., etc. </para>
- <para>All this can be achieved by declaring callback methods either in Persistent objects or in
- non-persistent listener classes defined by the application (further simply called
- "listeners"). There are eight types of lifecycle events supported by Cayenne, listed later
- in this chapter. When any such event occurs (e.g. an object is committed), Cayenne would
- invoke all appropriate callbacks. Persistent objects would receive their own events, while
- listeners would receive events from any objects. </para>
- <para>Cayenne allows to build rather powerful and complex "workflows" or "processors" tied to
- objects lifecycle, especially with listeners, as they have full access to the application
- evnironment outside Cayenne. This power comes from such features as filtering which entity
- events are sent to a given listener and the ability to create a common operation context for
- multiple callback invocations. All of these are discussed later in this chapter.</para>
- <section xml:id="types-of-lifecycle-events">
- <title>Types of Lifecycle Events</title>
- <para>Cayenne defines the following 8 types of lifecycle events for which callbacks can be
- regsitered:<table frame="void">
- <caption>Lifecycle Event Types</caption>
- <col width="16%"/>
- <col width="84%"/>
- <thead>
- <tr>
- <th>Event</th>
- <th>Occurs...</th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td>PostAdd</td>
- <td>right after a new object is created inside
- <code>ObjectContext.newObject()</code>. When this event is fired the
- object is already registered with its ObjectContext and has its ObjectId
- and ObjectContext properties set.</td>
- </tr>
- <tr>
- <td>PrePersist</td>
- <td>right before a new object is committed, inside
- <code>ObjectContext.commitChanges()</code> and
- <code>ObjectContext.commitChangesToParent()</code> (and after
- "<code>validateForInsert()</code>").</td>
- </tr>
- <tr>
- <td>PreUpdate</td>
- <td>right before a modified object is committed, inside
- <code>ObjectContext.commitChanges()</code> and
- <code>ObjectContext.commitChangesToParent()</code> (and after
- "<code>validateForUpdate()</code>").</td>
- </tr>
- <tr>
- <td>PreRemove</td>
- <td>right before an object is deleted, inside
- <code>ObjectContext.deleteObjects()</code>. The event is also
- generated for each object indirectly deleted as a result of CASCADE
- delete rule.</td>
- </tr>
- <tr>
- <td>PostPersist</td>
- <td>right after a commit of a new object is done, inside
- <code>ObjectContext.commitChanges()</code>.</td>
- </tr>
- <tr>
- <td>PostUpdate</td>
- <td>right after a commit of a modified object is done, inside
- <code>ObjectContext.commitChanges()</code>.</td>
- </tr>
- <tr>
- <td>PostRemove</td>
- <td>right after a commit of a deleted object is done, inside
- <code>ObjectContext.commitChanges()</code>.</td>
- </tr>
- <tr>
- <td>PostLoad</td>
- <td>
- <itemizedlist>
- <listitem>
- <para>After an object is fetched inside
- <code>ObjectContext.performQuery()</code>.</para>
- </listitem>
- <listitem>
- <para>After an object is reverted inside
- <code>ObjectContext.rollbackChanges()</code>.</para>
- </listitem>
- <listitem>
- <para>Anytime a faulted object is resolved (i.e. if a
- relationship is fetched).</para>
- </listitem>
- </itemizedlist>
- </td>
- </tr>
- </tbody>
- </table></para>
- </section>
- <section xml:id="callback-persistent">
- <title>Callbacks on Persistent Objects</title>
- <para>Callback methods on Persistent classes are mapped in CayenneModeler for each
- ObjEntity. Empty callback methods are automatically created as a part of class
- generation (either with Maven, Ant or the Modeler) and are later filled with appropriate
- logic by the programmer. E.g. assuming we mapped a 'post-add' callback called
- 'onNewOrder' in ObjEntity 'Order', the following code will be
- generated:<programlisting language="java">public abstract class _Order extends CayenneDataObject {
- protected abstract void onNewOrder();
-}
-
-public class Order extends _Order {
-
- @Override
- protected void onNewOrder() {
- //TODO: implement onNewOrder
- }
-}</programlisting></para>
- <para>As <code>onNewOrder()</code> is already declared in the mapping, it does not need to
- be registered explicitly. Implementing the method in subclass to do something meaningful
- is all that is required at this point. </para>
- <para>As a rule callback methods do not have any knowledge of the outside application, and
- can only access the state of the object itself and possibly the state of other
- persistent objects via object's own ObjectContext.</para>
- <para>
- <note>
- <para><emphasis role="italic">Validation and callbacks:</emphasis> There is a clear
- overlap in functionality between object callbacks and
- <code>DataObject.validateForX()</code> methods. In the future validation may
- be completely superceeded by callbacks. It is a good idea to use "validateForX"
- strictly for validation (or not use it at all). Updating the state before commit
- should be done via callbacks.</para>
- </note>
- </para>
- </section>
- <section xml:id="callback-non-persistent">
- <title>Callbacks on Non-Persistent Listeners</title>
- <para>A listener is simply some application class that has one or more annotated
- callback methods. A callback method signature should be <code>void
- someMethod(SomePersistentType object)</code>. It can be public, private, protected
- or use default access:</para>
- <para>
- <programlisting language="java"> public class OrderListener {
-
- @PostAdd(Order.class)
- public void setDefaultsForNewOrder(Order o) {
- o.setCreatedOn(new Date());
- }
-}</programlisting>
- </para>
- <para>Notice that the example above contains an annotation on the callback method that
- defines the type of the event this method should be called for. Before we go into
- annotation details, we'll show how to create and register a listener with Cayenne. It is
- always a user responsibility to register desired application listeners, usually right
- after ServerRuntime is started. Here is an example:</para>
- <para>First let's define 2 simple
- listeners.<programlisting language="java">public class Listener1 {
-
- @PostAdd(MyEntity.class)
- void postAdd(Persistent object) {
- // do something
- }
-}
-
-public class Listener2 {
-
- @PostRemove({ MyEntity1.class, MyEntity2.class })
- void postRemove(Persistent object) {
- // do something
- }
-
- @PostUpdate({ MyEntity1.class, MyEntity2.class })
- void postUpdate(Persistent object) {
- // do something
- }
-}</programlisting></para>
- <para>Ignore the annotations for a minute. The important point here is that the listeners
- are arbitrary classes unmapped and unknown to Cayenne, that contain some callback
- methods. Now let's register them with
- runtime:<programlisting language="java">ServerRuntime runtime = ...
-
-runtime.getDataDomain().addListener(new Listener1());
-runtime.getDataDomain().addListener(new Listener2());</programlisting></para>
- <para>Listeners in this example are very simple. However they don't have to be. Unlike
- Persistent objects, normally listeners initialization is managed by the application
- code, not Cayenne, so listeners may have knowledge of various application services,
- operation transactional context, etc. Besides a single listener can apply to multiple
- entities. As a consequence their callbacks can do more than just access a single
- ObjectContext. </para>
- <para>Now let's discuss the annotations. There are eight annotations exactly matching the
- names of eight lifecycle events. A callback method in a listener should be annotated
- with at least one, but possibly with more than one of them. Annotation itself defines
- what event the callback should react to. Annotation parameters are essentially an entity
- filter, defining a subset of ObjEntities whose events we are interested
- in:<programlisting language="java">// this callback will be invoked on PostRemove event of any object
-// belonging to MyEntity1, MyEntity2 or their subclasses
-@PostRemove({ MyEntity1.class, MyEntity2.class })
-void postRemove(Persistent object) {
- ...
-}</programlisting><programlisting language="java">// similar example with multipe annotations on a single method
-// each matching just one entity
-@PostPersist(MyEntity1.class)
-@PostRemove(MyEntity1.class)
-@PostUpdate(MyEntity1.class)
-void postCommit(MyEntity1 object) {
- ...
-}</programlisting></para>
- <para>As shown above, "value" (the implicit annotation parameter) can contain one or more
- entity classes. Only these entities' events will result in callback invocation. There's
- also another way to match entities - via custom annotations. This allows to match any
- number of entities without even knowing what they are. Here is an example. We'll first
- define a custom
- annotation:<programlisting language="java">@Target(ElementType.TYPE)
-@Retention(RetentionPolicy.RUNTIME)
-public @interface Tag {
-
-}</programlisting></para>
- <para>Now we can define a listener that will react to events from ObjEntities annotated with
- this
- annotation:<programlisting language="java">public class Listener3 {
-
- @PostAdd(entityAnnotations = Tag.class)
- void postAdd(Persistent object) {
- // do something
- }
-}</programlisting></para>
- <para>As you see we don't have any entities yet, still we can define a listener that does
- something useful. Now let's annotate some
- entities:<programlisting language="java">@Tag
-public class MyEntity1 extends _MyEntity1 {
-
-}
-
-@Tag
-public class MyEntity2 extends _MyEntity2 {
-
-}</programlisting></para>
- </section>
-
- <section xml:id="comining-listeners-with-datachannelfilters">
- <title>Combining Listeners with DataChannelFilters</title>
- <para>A final touch in the listeners design is preserving the state of the listener within a
- single select or commit, so that events generated by multiple objects can be collected
- and processed all together. To do that you will need to implement a
- <code>DataChannelFilter</code>, and add some callback methods to it. They will store
- their state in a ThreadLocal variable of the filter. Here is an example filter that does
- something pretty meaningless - counts how many total objects were committed. However it
- demonstrates the important pattern of aggregating multiple events and presenting a
- combined
- result:<programlisting language="java">public class CommittedObjectCounter implements DataChannelFilter {
-
- private ThreadLocal<int[]> counter;
-
- @Override
- public void init(DataChannel channel) {
- counter = new ThreadLocal<int[]>();
- }
-
- @Override
- public QueryResponse onQuery(ObjectContext originatingContext, Query query, DataChannelFilterChain filterChain) {
- return filterChain.onQuery(originatingContext, query);
- }
-
- @Override
- public GraphDiff onSync(ObjectContext originatingContext, GraphDiff changes, int syncType,
- DataChannelFilterChain filterChain) {
-
- // init the counter for the current commit
- counter.set(new int[1]);
-
- try {
- return filterChain.onSync(originatingContext, changes, syncType);
- } finally {
-
- // process aggregated result and release the counter
- System.out.println("Committed " + counter.get()[0] + " object(s)");
- counter.set(null);
- }
- }
-
- @PostPersist(entityAnnotations = Tag.class)
- @PostUpdate(entityAnnotations = Tag.class)
- @PostRemove(entityAnnotations = Tag.class)
- void afterCommit(Persistent object) {
- counter.get()[0]++;
- }
-}</programlisting></para>
- <para>Now since this is both a filter and a listener, it needs to be registered as
- such:<programlisting language="java">CommittedObjectCounter counter = new CommittedObjectCounter();
-
-ServerRuntime runtime = ...
-DataDomain domain = runtime.getDataDomain();
-
-// register filter
-// this will also add it as a listener (since 3.2)
-domain.addFilter(counter);</programlisting></para>
- </section>
-</chapter>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/cayenne-guide/src/docbkx/orderings.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/cayenne-guide/src/docbkx/orderings.xml b/docs/docbook/cayenne-guide/src/docbkx/orderings.xml
deleted file mode 100644
index a3a6bde..0000000
--- a/docs/docbook/cayenne-guide/src/docbkx/orderings.xml
+++ /dev/null
@@ -1,31 +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.
--->
-<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
- version="5.0" xml:id="orderings">
- <title>Orderings</title>
- <para>An Ordering object defines how a list of objects should be ordered. Orderings are
- essentially path expressions combined with a sorting strategy. Creating an Ordering:
- <programlisting language="java">Ordering o = new Ordering(Painting.NAME_PROPERTY, SortOrder.ASCENDING);</programlisting></para>
- <para>Like expressions, orderings are translated into SQL as parts of queries (and the sorting
- occurs in the database). Also like expressions, orderings can be used in memory, naturally -
- to sort
- objects:<programlisting language="java">Ordering o = new Ordering(Painting.NAME_PROPERTY, SortOrder.ASCENDING_INSENSITIVE);
-List<Painting> list = ...
-o.orderList(list);</programlisting>Note
- that unlike filtering with Expressions, ordering is performed in-place. This list object is
- reordered and no new list is created.</para>
-</chapter>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/cayenne-guide/src/docbkx/part1.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/cayenne-guide/src/docbkx/part1.xml b/docs/docbook/cayenne-guide/src/docbkx/part1.xml
deleted file mode 100644
index ac79499..0000000
--- a/docs/docbook/cayenne-guide/src/docbkx/part1.xml
+++ /dev/null
@@ -1,23 +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.
--->
-<part xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
- xml:id="cayenne-guide-part1" xmlns:xi="http://www.w3.org/2001/XInclude">
- <title>Object Relational Mapping with Cayenne</title>
- <xi:include href="setup.xml"/>
- <xi:include href="cayenne-mapping-structure.xml"/>
- <xi:include href="cayennemodeler-application.xml"/>
-</part>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/cayenne-guide/src/docbkx/part2.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/cayenne-guide/src/docbkx/part2.xml b/docs/docbook/cayenne-guide/src/docbkx/part2.xml
deleted file mode 100644
index c5f8201..0000000
--- a/docs/docbook/cayenne-guide/src/docbkx/part2.xml
+++ /dev/null
@@ -1,29 +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.
--->
-<part xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
- xml:id="cayenne-guide-part2" xmlns:xi="http://www.w3.org/2001/XInclude">
- <title>Cayenne Framework</title>
- <xi:include href="including-cayenne-in-project.xml"/>
- <xi:include href="starting-cayenne.xml"/>
- <xi:include href="persistent-objects-objectcontext.xml"/>
- <xi:include href="expressions.xml"/>
- <xi:include href="orderings.xml"/>
- <xi:include href="queries.xml"/>
- <xi:include href="lifecycle-events.xml"/>
- <xi:include href="performance-tuning.xml"/>
- <xi:include href="customizing-cayenne-runtime.xml"/>
-</part>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/cayenne-guide/src/docbkx/part3.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/cayenne-guide/src/docbkx/part3.xml b/docs/docbook/cayenne-guide/src/docbkx/part3.xml
deleted file mode 100644
index 75c60b3..0000000
--- a/docs/docbook/cayenne-guide/src/docbkx/part3.xml
+++ /dev/null
@@ -1,26 +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.
--->
-<part xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
- xml:id="cayenne-guide-part3" xmlns:xi="http://www.w3.org/2001/XInclude">
- <title>Cayenne Framework - Remote Object Persistence </title>
- <xi:include href="rop-introduction.xml"/>
- <xi:include href="rop-setup.xml"/>
- <xi:include href="implementing-rop-server.xml"/>
- <xi:include href="implementing-rop-client.xml"/>
- <xi:include href="rop-deployment.xml"/>
- <xi:include href="current-limitations.xml"/>
-</part>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/cayenne-guide/src/docbkx/part4.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/cayenne-guide/src/docbkx/part4.xml b/docs/docbook/cayenne-guide/src/docbkx/part4.xml
deleted file mode 100644
index 76ea83e..0000000
--- a/docs/docbook/cayenne-guide/src/docbkx/part4.xml
+++ /dev/null
@@ -1,24 +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.
--->
-<part xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
- xml:id="cayenne-guide-part4" xmlns:xi="http://www.w3.org/2001/XInclude">
- <title>DB-First Flow</title>
- <xi:include href="re-introduction.xml"/>
- <xi:include href="re-filtering.xml"/>
- <xi:include href="re-other-settings.xml"/>
- <xi:include href="re-modeler.xml"/>
-</part>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/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
deleted file mode 100644
index 347f6ce..0000000
--- a/docs/docbook/cayenne-guide/src/docbkx/part5.xml
+++ /dev/null
@@ -1,30 +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.
- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~-->
-<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"/>
-</part>
[04/13] cayenne git commit: CAY-2371 Switch documentation from
Docbook to Asciidoctor format
Posted by nt...@apache.org.
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/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
deleted file mode 100644
index 6acc744..0000000
--- a/docs/docbook/cayenne-guide/src/docbkx/queries-sqltemplate.xml
+++ /dev/null
@@ -1,420 +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.
--->
-<section xmlns="http://docbook.org/ns/docbook" xml:id="sqltemplate">
- <title>SQLTemplate</title>
- <para>SQLTemplate is a query that allows to run native SQL from a Cayenne application. It
- comes handy when the standard ORM concepts are not sufficient for a given query or an
- update. SQL is too powerful and allows to manipulate data in ways that are not easily
- described as a graph of related entities. Cayenne acknowledges this fact and provides
- this facility to execute SQL, mapping the result to objects when possible. Here are
- examples of selecting and non-selecting
- SQLTemplates:<programlisting language="java">SQLTemplate select = new SQLTemplate(Artist.class, "select * from ARTIST");
-List<Artist> result = context.performQuery(select);</programlisting><programlisting language="java">SQLTemplate update = new SQLTemplate(Artist.class, "delete from ARTIST");
-QueryResponse response = context.performGenericQuery(update);</programlisting></para>
- <para>Cayenne doesn't make any attempt to make sense of the SQL semantics, so it doesn't
- know whether a given query is performing a select or update, etc. It is the the user's
- decision to run a given query as a selecting or "generic".</para>
- <para>
- <note>
- <para>Any data modifications done to DB as a result of SQLTemplate execution do not
- change the state of objects in the ObjectContext. So some objects in the context
- may become stale as a result.</para>
- </note>
- </para>
- <para>Another point to note is that the first argument to the SQLTemplate constructor - the
- Java class - has the same meaning as in SelectQuery only when the result can be
- converted to objects (e.g. when this is a selecting query and it is selecting all
- columns from one table). In this case it denotes the "root" entity of this query result.
- If the query does not denote a single entity result, this argument is only used for
- query routing, i.e. determining which database it should be run against. You are free to
- use any persistent class or even a DataMap instance in such situation. It will work as
- long as the passed "root" maps to the same database as the current query.</para>
- <para>To achieve interoperability between mutliple RDBMS a user can specify multiple SQL
- statements for the same SQLTemplate, each corresponding to a native SQL dialect. A key
- used to look up the right dialect during execution is a fully qualified class name of
- the corresponding DbAdapter. If no DB-specific statement is present for a given DB, a
- default generic statement is used. E.g. in all the examples above a default statement
- will be used regardless of the runtime database. So in most cases you won't need to
- explicitly "translate" your SQL to all possible dialects. Here is how this works in
- practice:<programlisting language="java">SQLTemplate select = new SQLTemplate(Artist.class, "select * from ARTIST");
-
-// For Postgres it would be nice to trim padding of all CHAR columns.
-// Otherwise those will be returned with whitespace on the right.
-// assuming "NAME" is defined as CHAR...
-String pgSQL = "SELECT ARTIST_ID, RTRIM(NAME), DATE_OF_BIRTH FROM ARTIST";
-query.setTemplate(PostgresAdapter.class.getName(), pgSQL);</programlisting></para>
-
- <section xml:id="sqltemplate-scripting">
- <title>Scripting SQLTemplate with Velocity</title>
- <para>The most interesting aspect of SQLTemplate (and the reason why it is called a
- "template") is that a SQL string is treated by Cayenne as an Apache Velocity
- template. Before sending it to DB as a PreparedStatement, the String is evaluated in
- the Velocity context, that does variable substitutions, and performs special
- callbacks in response to various directives, thus controlling query interaction with
- the JDBC layer. </para>
- <para>Check Velocity docs for the syntax details. Here we'll just mention the two main
- scripting elements - "variables" (that look like <code>$var</code>) and "directives"
- (that look like <code>#directive(p1 p2 p3)</code>). All built-in Velocity directives
- are supported. Additionally Cayenne defines a number of its own directives to bind
- parameters to PreparedStatements and to control the structure of the ResultSet.
- These directives are described in the following sections.</para>
- </section>
- <section xml:id="sqltemplate-parameters">
- <title>Variable Substitution</title>
- <para>All variables in the template string are replaced from query
- parameters:<programlisting language="java">SQLTemplate query = new SQLTemplate(Artist.class, "delete from $tableName");
-query.setParameters(Collections.singletonMap("tableName", "mydb.PAINTING"));
-
-// this will generate SQL like this: "delete from mydb.PAINTING"</programlisting>The
- example above demonstrates the point made earlier in this chapter - even if we don't
- know upfront which table the query will run against, we can still use a fixed "root"
- in constructor (<code>Artist.class</code> in this case) , as we are not planning on
- converting the result to objects.</para>
- <para>Variable substitution within the text uses "<code>object.toString()</code>" method to replace the
- variable value. Keep in mind that this may not be appropriate in all situations.
- E.g. passing a date object in a WHERE clause expression may be converted to a String
- not understood by the target RDBMS SQL parser. In such cases variable should be wrapped in <code>#bind</code>
- directive as described below.</para>
- </section>
- <section xml:id="sqltemplate-bind-directive">
- <title>Directives</title>
- <para>These are the Cayenne directives used to customize SQLTemplate parsing and
- integrate it with the JDBC layer: </para>
- <section>
- <title>#bind</title>
- <para>Creates a PreparedStatement positional parameter in place of the directive,
- binding the value to it before statement execution. <code>#bind</code> is
- allowed in places where a "?" would be allowed in a PreparedStatement. And in
- such places it almost always makes sense to pass objects to the template via
- this or other forms of <code>#bind</code> instead of inserting them
- inline.</para>
- <para><emphasis role="italic">Semantics:</emphasis></para>
- <programlisting language="java">#bind(value)
-#bind(value jdbcType)
-#bind(value jdbcType scale)</programlisting>
- <para><emphasis role="italic">Arguments:</emphasis>
- <itemizedlist>
- <listitem>
- <para><code>value</code> - can either be a char constant or a variable
- that is resolved from the query parameters. Note that the variable
- can be a collection, that will be automatically expanded into a list
- of individual value bindings. This is useful for instance to build
- IN conditions. </para>
- </listitem>
- <listitem>
- <para><code>jdbcType</code> - is a JDBC data type of the parameter as
- defined in <code>java.sql.Types</code>.</para>
- </listitem>
- <listitem>
- <para><code>scale</code> - An optional scale of the numeric value. Same
- as "scale" in PreparedStatement.</para>
- </listitem>
- </itemizedlist></para>
- <para>
- <emphasis role="italic"
- >Usage</emphasis>:<programlisting language="java">#bind($xyz)
-#bind('str')
-#bind($xyz 'VARCHAR')
-#bind($xyz 'DECIMAL' 2)</programlisting></para>
- <para><emphasis role="italic">Full
- example:</emphasis><programlisting language="sql">update ARTIST set NAME = #bind($name) where ID = #bind($id)</programlisting></para>
- </section>
- <section>
- <title>#bindEqual</title>
- <para>Same as #bind, but also includes the "=" sign in front of the value binding.
- Look at the example below - we took the #bind example and replaced "<code>ID =
- #bind(..)</code>" with "<code>ID #bindEqual(..)</code>". While it looks like
- a clumsy shortcut to eliminate the equal sign, the actual reason why this is
- useful is that it allows the value to be null. If the value is not null,
- "<code>= ?</code>" is generated, but if it is, the resulting chunk of the
- SQL would look like "<code>IS NULL</code>" and will be compilant with what the
- DB expects.</para>
- <para><emphasis role="italic">Semantics:</emphasis></para>
- <programlisting language="java">#bindEqual(value)
-#bindEqual(value jdbcType)
-#bindEqual(value jdbcType scale)</programlisting>
- <para><emphasis role="italic">Arguments: (same as #bind)</emphasis>
- </para>
- <para>
- <emphasis role="italic"
- >Usage</emphasis>:<programlisting language="java">#bindEqual($xyz)
-#bindEqual('str')
-#bindEqual($xyz 'VARCHAR')
-#bindEqual($xyz 'DECIMAL' 2)</programlisting></para>
- <para><emphasis role="italic">Full
- example:</emphasis><programlisting language="sql">update ARTIST set NAME = #bind($name) where ID #bindEqual($id)</programlisting></para>
- </section>
- <section>
- <title>#bindNotEqual</title>
- <para>This directive deals with the same issue as <code>#bindEqual</code> above,
- only it generates "not equal" in front of the value (or IS NOT NULL).</para>
- <para><emphasis role="italic">Semantics:</emphasis></para>
- <programlisting language="java">#bindNotEqual(value)
-#bindNotEqual(value jdbcType)
-#bindNotEqual(value jdbcType scale)</programlisting>
- <para><emphasis role="italic">Arguments: (same as #bind)</emphasis></para>
- <para>
- <emphasis role="italic"
- >Usage</emphasis>:<programlisting language="java">#bindNotEqual($xyz)
-#bindNotEqual('str')
-#bindNotEqual($xyz 'VARCHAR')
-#bindNotEqual($xyz 'DECIMAL' 2)</programlisting></para>
- <para><emphasis role="italic">Full
- example:</emphasis><programlisting language="sql">update ARTIST set NAME = #bind($name) where ID #bindEqual($id)</programlisting></para>
- </section>
- <section>
- <title>#bindObjectEqual</title>
- <para>It can be tricky to use a Persistent object or an ObjectId in a binding,
- especially for tables with compound primary keys. This directive helps to handle
- such binding. It maps columns in the query to the names of Persistent object ID
- columns, extracts ID values from the object, and generates SQL like "COL1 = ?
- AND COL2 = ? ..." , binding positional parameters to ID values. It can also
- correctly handle null object. Also notice how we are specifying a Velocity array
- for multi-column PK.</para>
- <para><emphasis role="italic">Semantics:</emphasis></para>
- <programlisting language="java">#bindObjectEqual(value columns idColumns)</programlisting>
- <para><emphasis role="italic">Arguments:</emphasis>
- <itemizedlist>
- <listitem>
- <para><code>value</code> - must be a variable that is resolved from the
- query parameters to a Persistent or ObjectId.</para>
- </listitem>
- <listitem>
- <para><code>columns</code> - the names of the columns to generate in the
- SQL.</para>
- </listitem>
- <listitem>
- <para><code>idColumn</code> - the names of the ID columns for a given
- entity. Must match the order of "columns" to match against.</para>
- </listitem>
- </itemizedlist></para>
- <para>
- <emphasis role="italic"
- >Usage</emphasis>:<programlisting language="java">#bindObjectEqual($a 't0.ID' 'ID')
-#bindObjectEqual($b ['t0.FK1', 't0.FK2'] ['PK1', 'PK2'])</programlisting></para>
- <para><emphasis role="italic">Full
- example:</emphasis><programlisting language="java">String sql = "SELECT * FROM PAINTING t0 WHERE #bindObjectEqual($a 't0.ARTIST_ID' 'ARTIST_ID' ) ORDER BY PAINTING_ID";
-SQLTemplate select = new SQLTemplate(Artist.class, sql);
-
-Artist a = ....
-select.setParameters(Collections.singletonMap("a", a)); </programlisting></para>
- </section>
- <section>
- <title>#bindObjectNotEqual</title>
- <para>Same as #bindObjectEqual above, only generates "not equal" operator for value
- comparison (or IS NOT NULL).</para>
- <para><emphasis role="italic">Semantics:</emphasis></para>
- <programlisting language="java">#bindObjectNotEqual(value columns idColumns)</programlisting>
- <para><emphasis role="italic">Arguments: (same as #bindObjectEqual)</emphasis>
- </para>
- <para>
- <emphasis role="italic"
- >Usage</emphasis>:<programlisting language="java">#bindObjectNotEqual($a 't0.ID' 'ID')
-#bindObjectNotEqual($b ['t0.FK1', 't0.FK2'] ['PK1', 'PK2'])</programlisting></para>
- <para><emphasis role="italic">Full
- example:</emphasis><programlisting language="java">String sql = "SELECT * FROM PAINTING t0 WHERE #bindObjectNotEqual($a 't0.ARTIST_ID' 'ARTIST_ID' ) ORDER BY PAINTING_ID";
-SQLTemplate select = new SQLTemplate(Artist.class, sql);
-
-Artist a = ....
-select.setParameters(Collections.singletonMap("a", a)); </programlisting></para>
- </section>
- <section>
- <title>#result</title>
- <para>Renders a column in SELECT clause of a query and maps it to a key in the
- result DataRow. Also ensures the value read is of the correct type. This allows
- to create a DataRow (and ultimately - a persistent object) from an arbitrary
- ResultSet.</para>
- <para><emphasis role="italic">Semantics:</emphasis></para>
- <programlisting language="java">#result(column)
-#result(column javaType)
-#result(column javaType alias)
-#result(column javaType alias dataRowKey)</programlisting>
- <para><emphasis role="italic">Arguments:</emphasis>
- <itemizedlist>
- <listitem>
- <para><code>column</code> - the name of the column to render in SQL
- SELECT clause.</para>
- </listitem>
- <listitem>
- <para><code>javaType</code> - a fully-qualified Java class name for a
- given result column. For simplicity most common Java types used in
- JDBC can be specified without a package. These include all numeric
- types, primitives, String, SQL dates, BigDecimal and BigInteger. So
- "<code>#result('A' 'String')</code>", "<code>#result('B'
- 'java.lang.String')</code>" and "<code>#result('C'
- 'int')</code>" are all valid</para>
- </listitem>
- <listitem>
- <para><code>alias</code> - specifies both the SQL alias of the column
- and the value key in the DataRow. If omitted, "column" value is
- used.</para>
- </listitem>
- <listitem>
- <para><code>dataRowKey</code> - needed if SQL 'alias' is not appropriate
- as a DataRow key on the Cayenne side. One common case when this
- happens is when a DataRow retrieved from a query is mapped using
- joint prefetch keys (see below). In this case DataRow must use
- database path expressions for joint column keys, and their format is
- incompatible with most databases alias format. </para>
- </listitem>
- </itemizedlist></para>
- <para>
- <emphasis role="italic"
- >Usage</emphasis>:<programlisting language="java">#result('NAME')
-#result('DATE_OF_BIRTH' 'java.util.Date')
-#result('DOB' 'java.util.Date' 'DATE_OF_BIRTH')
-#result('DOB' 'java.util.Date' '' 'artist.DATE_OF_BIRTH')
-#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>
-
- </section>
- </section>
- <section>
- <title>Mapping SQLTemplate Results</title>
- <para>Here we'll discuss how to convert the data selected via SQLTemplate to some
- useable format, compatible with other query results. It can either be very simple or
- very complex, depending on the structure of the SQL, JDBC driver nature and the
- desired result structure. This section presents various tips and tricks dealing with
- result mapping. </para>
- <para>By default SQLTemplate is expected to return a List of Persistent objects of its
- root type. This is the simple
- case:<programlisting language="java">SQLTemplate query = new SQLTemplate(Artist.class, "SELECT * FROM ARTIST");
-
-// List of Artists
-List<Artist> artists = context.performQuery(query);</programlisting>Just
- like SelectQuery, SQLTemplate can fetch DataRows. In fact DataRows option is very
- useful with SQLTemplate, as the result type most often than not does not represent a
- Cayenne entity, but instead may be some aggregated report or any other data whose
- object structure is opaque to
- Cayenne:<programlisting language="java">String sql = "SELECT t0.NAME, COUNT(1) FROM ARTIST t0 JOIN PAINTING t1 ON (t0.ID = t1.ARTIST_ID) "
- + "GROUP BY t0.NAME ORDER BY COUNT(1)";
-SQLTemplate query = new SQLTemplate(Artist.class, sql);
-
-// ensure we are fetching DataRows
-query.setFetchingDataRows(true);
-
-// List of DataRow
-List<DataRow> rows = context.performQuery(query);</programlisting>In
- the example above, even though the query root is Artist. the result is a list of
- artist names with painting counts (as mentioned before in such case "root" is only
- used to find the DB to fetch against, but has no bearning on the result). The
- DataRows here are the most appropriate and desired result type.</para>
- <para>In a more advanced case you may decide to fetch a list of scalars or a list of
- Object[] with each array entry being either an entity or a scalar. You probably
- won't be doing this too often and it requires quite a lot of work to setup, but if
- you want your SQLTemplate to return results similar to EJBQLQuery, it is doable
- using SQLResult as described
- below:<programlisting language="java">SQLTemplate query = new SQLTemplate(Painting.class, "SELECT ESTIMATED_PRICE P FROM PAINTING");
-
-// let Cayenne know that result is a scalar
-SQLResult resultDescriptor = new SQLResult();
-resultDescriptor.addColumnResult("P");
-query.setResult(resultDescriptor);
-
-// List of BigDecimals
-List<BigDecimal> prices = context.performQuery(query); </programlisting><programlisting language="java">SQLTemplate query = new SQLTemplate(Artist.class, "SELECT t0.ID, t0.NAME, t0.DATE_OF_BIRTH, COUNT(t1.PAINTING_ID) C " +
- "FROM ARTIST t0 LEFT JOIN PAINTING t1 ON (t0.ID = t1.ARTIST_ID) " +
- "GROUP BY t0.ID, t0.NAME, t0.DATE_OF_BIRTH");
-
-// let Cayenne know that result is a mix of Artist objects and the count of their paintings
-EntityResult artistResult = new EntityResult(Artist.class);
-artistResult.addDbField(Artist.ID_PK_COLUMN, "ARTIST_ID");
-artistResult.addObjectField(Artist.NAME_PROPERTY, "NAME");
-artistResult.addObjectField(Artist.DATE_OF_BIRTH_PROPERTY, "DATE_OF_BIRTH");
-
-SQLResult resultDescriptor = new SQLResult();
-resultDescriptor.addEntityResult(artistResult);
-resultDescriptor.addColumnResult("C");
-query.setResult(resultDescriptor);
-
-// List of Object[]
-List<Object[]> data = context.performQuery(query);</programlisting></para>
- <para>Another trick related to mapping result sets is making Cayenne recognize
- prefetched entities in the result set. This emulates "joint" prefetching of
- SelectQuery, and is achieved by special column naming. Columns belonging to the
- "root" entity of the query should use unqualified names corresponding to the root
- DbEntity columns. For each related entity column names must be prefixed with
- relationship name and a dot (e.g. "toArtist.ID"). Column naming can be controlled
- with "#result"
- directive:<programlisting language="java">String sql = "SELECT distinct "
- + "#result('t1.ESTIMATED_PRICE' 'BigDecimal' '' 'paintings.ESTIMATED_PRICE'), "
- + "#result('t1.PAINTING_TITLE' 'String' '' 'paintings.PAINTING_TITLE'), "
- + "#result('t1.GALLERY_ID' 'int' '' 'paintings.GALLERY_ID'), "
- + "#result('t1.ID' 'int' '' 'paintings.ID'), "
- + "#result('NAME' 'String'), "
- + "#result('DATE_OF_BIRTH' 'java.util.Date'), "
- + "#result('t0.ID' 'int' '' 'ID') "
- + "FROM ARTIST t0, PAINTING t1 "
- + "WHERE t0.ID = t1.ARTIST_ID";
-
-SQLTemplate q = new SQLTemplate(Artist.class, sql);
-q.addPrefetch(Artist.PAINTINGS_PROPERTY)
-List<Artist> objects = context.performQuery(query);</programlisting></para>
- <para>And the final tip deals with capitalization of the DataRow keys. Queries like
- "<code>SELECT * FROM...</code>" and even "<code>SELECT COLUMN1, COLUMN2, ...
- FROM ...</code>" can sometimes result in Cayenne exceptions on attempts to
- convert fetched DataRows to objects. Essentially any query that is not using a
- <code>#result</code> directive to describe the result set is prone to this
- problem, as different databases may produce different capitalization of the
- java.sql.ResultSet columns. </para>
- <para>The most universal way to address this issue is to describe each column explicitly
- in the SQLTemplate via <code>#result</code>, e.g.: "<code>SELECT #result('column1'),
- #result('column2'), ..</code>". However this quickly becomes impractical for
- tables with lots of columns. For such cases Cayenne provides a shortcut based on the
- fact that an ORM mapping usually follows some naming convention for the column
- names. Simply put, for case-insensitive databases developers normally use either all
- lowercase or all uppercase column names. Here is the API that takes advantage of
- that user knowledge and forces Cayenne to follow a given naming convention for the
- DataRow keys (this is also available as a dropdown in the
- Modeler):<programlisting language="java">SQLTemplate query = new SQLTemplate("SELECT * FROM ARTIST");
-query.setColumnNamesCapitalization(CapsStrategy.LOWER);
-List objects = context.performQuery(query);</programlisting></para>
- <para>or<programlisting language="java">SQLTemplate query = new SQLTemplate("SELECT * FROM ARTIST");
-query.setColumnNamesCapitalization(CapsStrategy.UPPER);
-List objects = context.performQuery(query); </programlisting></para>
- <para>None of this affects the generated SQL, but the resulting DataRows are using
- correct capitalization. Note that you probably shouldn't bother with this unless you
- are getting CayenneRuntimeExceptions when fetching with SQLTemplate.</para>
- </section>
- </section>
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/cayenne-guide/src/docbkx/queries.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/cayenne-guide/src/docbkx/queries.xml b/docs/docbook/cayenne-guide/src/docbkx/queries.xml
deleted file mode 100644
index 28b2993..0000000
--- a/docs/docbook/cayenne-guide/src/docbkx/queries.xml
+++ /dev/null
@@ -1,55 +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.
--->
-<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude"
- version="5.0" xml:id="queries">
- <title>Queries</title>
- <para>Queries are Java objects used by the application to communicate with the database. Cayenne
- knows how to translate queries into SQL statements appropriate for a particular database
- engine. Most often queries are used to find objects matching certain criteria, but there are
- other types of queries too. E.g. those allowing to run native SQL, call DB stored
- procedures, etc. When committing objects, Cayenne itself creates special queries to
- insert/update/delete rows in the database. </para>
- <para>There is a number of built-in queries in Cayenne, described later in this chapter. Most of
- the newer queries use fluent API and can be created and executed as easy-to-read one-liners.
- Users can define their own query types to abstract certain DB interactions that for whatever
- reason can not be adequately described by the built-in set.</para>
- <para>Queries can be roughly categorized as "object" and "native". Object queries (most notably
- ObjectSelect, SelectById, and EJBQLQuery) are built with abstractions originating in the
- object model (the "object" side in the "object-relational" divide). E.g. ObjectSelect is
- assembled from a Java class of the objects to fetch, a qualifier expression, orderings, etc.
- - all of this expressed in terms of the object model.</para>
- <para>Native queries describe a desired DB operation as SQL code (SQLSelect, SQLTemplate query)
- or a reference to a stored procedure (ProcedureQuery), etc. The results of native queries
- are usually presented as Lists of Maps, with each map representing a row in the DB (a term
- "data row" is often used to describe such a map). They can potentially be converted to
- objects, however it may take a considerable effort to do so. Native queries are also less
- (if at all) portable across databases than object queries. </para>
-
- <xi:include href="queries-select.xml"/>
- <xi:include href="queries-ejbql.xml"/>
- <xi:include href="queries-selectbyid.xml"/>
- <xi:include href="queries-sqlselect.xml"/>
- <xi:include href="queries-mapped.xml"/>
- <xi:include href="queries-procedurecall.xml"/>
- <xi:include href="queries-custom.xml"/>
- <xi:include href="queries-sqltemplate.xml"/>
-
- <!-- ProcedureQuery is not deprecated as of 4.0 but newer ProcedureCall is preferred -->
- <!--<xi:include href="queries-procedure.xml"/>-->
- <!-- NamedQuery deprecated since 4.0 -->
- <!--<xi:include href="queries-namedquery.xml"/>-->
-</chapter>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/cayenne-guide/src/docbkx/re-filtering.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/cayenne-guide/src/docbkx/re-filtering.xml b/docs/docbook/cayenne-guide/src/docbkx/re-filtering.xml
deleted file mode 100644
index a54ac2f..0000000
--- a/docs/docbook/cayenne-guide/src/docbkx/re-filtering.xml
+++ /dev/null
@@ -1,356 +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.
--->
-<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
- version="5.0" xml:id="re-filtering">
- <title>Filtering</title>
- <para>
- The first thing you usually want to control during reverse engineering is what exactly should be loaded from database and
- what not. One of the most common cases is excluding system tables, as you usually don't want to map them.
- </para>
- <para>
- Briefly, you are able to include/exclude tables, columns and procedures and do it at several levels: default, catalog, schema.
- Although everything defined at the top level (default rules) will be applied for the nested elements, all rules from the most specific
- areas will override general rules (i.e. rules from schemas override rules from catalogs and even more override default rules).
- </para>
- <para>
- The following use-cases will provide you a better understanding of how filtering works and how you could use it.
- </para>
- <section xml:id="everything-schema-catalog">
- <title>Process everything from schema/catalog</title>
- <para>
- The simplest example of reverse engineering is processing tables from one schema of catalog and there are several options to do this.
- Basic syntax is described below:
- </para>
- <programlisting language="xml"><dbimport>
- <!-- Ant/Maven in case you only want to specify the schema to import -->
- <schema>SCHEMA_NAME</schema>
-
- <!-- Maven way in case you have nested elements in the schema -->
- <schema>
- <name>SCHEMA_NAME</name>
- ...
- </schema>
-
- <!-- Ant way in case you have nested elements in the schema -->
- <schema name="SCHEMA_NAME">
- ...
- </schema>
-</dbimport> </programlisting>
- <para>
- The same options are available for catalogs:
- </para>
- <programlisting language="xml"> <dbimport>
- <!-- Ant/Maven in case you only want to specify the catalog to import -->
- <catalog>CATALOG_NAME</catalog>
-
- <!-- Maven way in case you have nested elements in the catalog -->
- <catalog>
- <name>CATALOG_NAME</name>
- ...
- </catalog>
-
- <!-- Ant way in case you have nested elements in the catalog -->
- <catalog name="CATALOG_NAME">
- ...
- </catalog>
-</dbimport></programlisting>
- <note>
- <para>Current version of reverse engineering doesn't support catalog filtering for Postgres database.</para>
- </note>
- </section>
- <section xml:id="combine-schema-catalog">
- <title>Combine Schema and Catalog filters</title>
- <para>
- Cayenne supports combination of different schemas and catalogs, and it filters data according to your requirements.
- You could achieve this by the following example of reverse engineering configuration:
- </para>
- <programlisting language="xml"><dbimport>
-
- <catalog>
- <name>shop_01</name>
- <schema>schema-name-01</schema>
- <schema>schema-name-02</schema>
- <schema>schema-name-03</schema>
- </catalog>
-
- <catalog>
- <name>shop_02</name>
- <schema>schema-name-01</schema>
- </catalog>
-
- <catalog>
- <name>shop_03</name>
- <schema>schema-name-01</schema>
- <schema>schema-name-02</schema>
- <schema>schema-name-03</schema>
- </catalog>
-
-</dbimport></programlisting>
- <para>
- In the example above, Cayenne reverse engineering process contains three catalogs named as shop_01, shop_02 and shop_03,
- each of wich has their own schemas. Cayenne will load all data only from the declared catalogs and schemas.
- </para>
- <para>
- If you want to load everything from database, you could simply declare catalog specification alone.
- </para>
- <programlisting language="xml"><dbimport>
-
- <catalog>shop_01</catalog>
- <catalog>shop_02</catalog>
- <catalog>shop_03</catalog>
-
-</dbimport></programlisting>
- <para>
- If you want to do reverse engineering for specific schemas, just remove unwanted schemas from the catalog section.
- For example, if you want to process schema-name-01 and schema-name-03 schemas only, then you should change reverse engineering section like this.
- </para>
- <programlisting language="xml"><dbimport>
-
- <catalog>
- <name>shop_01</name>
- <schema>schema-name-01</schema>
- <schema>schema-name-03</schema>
- </catalog>
-
- <catalog>
- <name>shop_02</name>
- <schema>schema-name-01</schema>
- </catalog>
-
- <catalog>
- <name>shop_03</name>
- <schema>schema-name-01</schema>
- <schema>schema-name-03</schema>
- </catalog>
-
-</dbimport></programlisting>
- </section>
- <section xml:id="including-excluding-tables-columns-procedures">
- <title>Including and Excluding tables, columns and procedures</title>
- <para>
- Cayenne reverse engineering let you fine tune table, columns and stored procedures names that you need to import
- to your model file. In every filter you can use regexp syntax. Here is some examples of configuration
- for common tasks.
- </para>
- <para>
- <orderedlist numeration="arabic">
- <listitem>
- <para>Include tables with ‘CRM_’ prefix if you are working in that domain of application:</para>
- <programlisting language="xml"><includeTable>CRM_.*</includeTable></programlisting>
- </listitem>
- <listitem>
- <para>Include tables with ‘_LOOKUP’ suffix</para>
- <programlisting language="xml"><includeTable>
- <pattern>.*_LOOKUP</pattern>
-</includeTable></programlisting>
- </listitem>
- <listitem>
- <para>Exclude tables with ‘CRM_’ prefix if you are not working only in that domain of application:</para>
- <programlisting language="xml"><excludeTable>CRM_.*</excludeTable></programlisting>
- </listitem>
- <listitem>
- <para>Include only specific columns that follows specific naming convention:</para>
- <programlisting language="xml"><includeColumn>includeColumn01</includeColumn>
-<includeColumn>includeColumn03</includeColumn></programlisting>
- </listitem>
- <listitem>
- <para>Exclude system or obsolete columns:</para>
- <programlisting language="xml"><excludeColumn>excludeColumn01</excludeColumn>
-<excludeColumn>excludeColumn03</excludeColumn></programlisting>
- </listitem>
- <listitem>
- <para>Include/Exclude columns for particular table or group of tables:</para>
- <programlisting language="xml"><includeTable>
- <pattern>table pattern</pattern>
- <includeColumn>includeColumn01</includeColumn>
- <excludeColumn>excludeColumn01</excludeColumn>
-</includeTable></programlisting>
- </listitem>
- <listitem>
- <para>Include stored procedures:</para>
- <programlisting language="xml"><includeProcedure>includeProcedure01</includeProcedure>
-<includeProcedure>
- <pattern>includeProcedure03</pattern>
-</includeProcedure></programlisting>
- </listitem>
- <listitem>
- <para>Exclude stored procedures by pattern:</para>
- <programlisting language="xml"><excludeProcedure>excludeProcedure01</excludeProcedure>
-<excludeProcedure>
- <pattern>excludeProcedure03</pattern>
-</excludeProcedure></programlisting>
- </listitem>
- </orderedlist>
- </para>
- <para> All filtering tags <code><includeTable></code>,
- <code><excludeTable></code>, <code><includeColumn></code>,
- <code><excludeColumn></code>, <code><includeProcedure></code> and
- <code><excludeProcedure></code> have 2 ways to pass filtering RegExp.
- <orderedlist numeration="arabic">
- <listitem>
- <para>text inside tag</para>
- <programlisting language="xml">
- <includeTable>CRM_.*</includeTable></programlisting>
- </listitem>
- <listitem>
- <para>pattern inner tag</para>
- <programlisting language="xml">
- <includeTable>
- <pattern>.*_LOOKUP</pattern>
- </includeTable></programlisting>
- </listitem>
- </orderedlist>
- </para>
- <para>
- All filtering tags can be placed inside schema and catalog tags, but also inside <code><dbimport></code> tag. It means that filtering rules
- will be applied for all schemas and catalogs.
- </para>
- </section>
- <section xml:id="complete-filtering-example">
- <title>Complete filtering example</title>
- <para>
- Initially, let’s make a small sample. Consider the following reverse engineering configuration.
- </para>
- <programlisting language="xml"><dbimport>
- <catalog>shop-01</catalog>
-</dbimport> </programlisting>
- <para>
- In this case reverse engineering will not filter anything from the shop-01 catalog. If you really want to filter database columns, tables,
- stored procedures and relationships, you could do it in the following way.
- </para>
- <programlisting language="xml"><dbimport>
- <catalog>shop-01</catalog>
- <catalog>
- <name>shop-02</name>
- <includeTable>includeTable-01</includeTable>
- </catalog>
-</dbimport></programlisting>
- <para>
- Then Cayenne will do reverse engineering for both shop-01 and shop-02 catalogs. First catalog will not be processed for filtering,
- but the second catalog will be processed with “includeTable-01” filter.
- </para>
- <para>
- Let’s assume you have a lot of table prefixes with the same names. Cayenne allows you to mention a pattern as regular expression.
- Using regular expressions is easier way to handle a big amount of database entities than writing filter config for each use-case.
- They make your configuration more readable, understandable and straightforward. There is not complex.
- Let’s see how to use patterns in reverse engineering configuration with complete example.
- </para>
- <programlisting language="xml"><dbimport>
-
- <catalog>shop-01</catalog>
-
- <catalog>
- <name>shop-02</name>
- </catalog>
-
- <catalog>
- <name>shop-03</name>
- <includeTable>includeTable-01</includeTable>
-
- <includeTable>
- <pattern>includeTable-02</pattern>
- </includeTable>
-
- <includeTable>
- <pattern>includeTable-03</pattern>
- <includeColumn>includeColumn-01</includeColumn>
- <excludeColumn>excludeColumn-01</excludeColumn>
- </includeTable>
-
- <excludeTable>excludeTable-01</excludeTable>
-
- <excludeTable>
- <pattern>excludeTable-02</pattern>
- </excludeTable>
-
- <includeColumn>includeColumn-01</includeColumn>
-
- <includeColumn>
- <pattern>includeColumn-02</pattern>
- </includeColumn>
-
- <excludeColumn>excludeColumn-01</excludeColumn>
-
- <excludeColumn>
- <pattern>excludeColumn-02</pattern>
- </excludeColumn>
-
- <includeProcedure>includeProcedure-01</includeProcedure>
-
- <includeProcedure>
- <pattern>includeProcedure-02</pattern>
- </includeProcedure>
-
- <excludeProcedure>excludeProcedure-01</excludeProcedure>
-
- <excludeProcedure>
- <pattern>excludeProcedure-02</pattern>
- </excludeProcedure>
-
- </catalog>
-</dbimport></programlisting>
- <para>The example above should provide you more idea about how to use filtering and patterns
- in Cayenne reverse engineering. You could notice that this example demonstrates you the
- "name" and "pattern" configurations. Yes, you could use these as separates xml element
- and xml attributes. </para>
- <para>
- The cdbimport will execute reverse engineering task for all entities from “shop-01” and “shop-02”, including tables, views, stored procedures
- and table columns. As “shop-03” has variety filter tags, entities from this catalog will be filtered by cdbimport.
- </para>
- </section>
- <section>
- <title>Ant configuration example</title>
- <para> Here is config sample for <code>Ant</code> task:
- <programlisting language="xml"><!-- inside <cdbimport> tag -->
-<catalog>shop-01</catalog>
-
-<catalog name="shop-02"/>
-
-<catalog name="shop-03">
-
- <includeTable>includeTable-01</includeTable>
- <includeTable pattern="includeTable-02"/>
-
- <includeTable pattern="includeTable-03">
- <includeColumn>includeColumn-01</includeColumn>
- <excludeColumn>excludeColumn-01</excludeColumn>
- </includeTable>
-
- <excludeTable>excludeTable-01</excludeTable>
- <excludeTable pattern="excludeTable-02"/>
-
- <includeColumn>includeColumn-01</includeColumn>
- <includeColumn pattern="includeColumn-02"/>
-
- <excludeColumn>excludeColumn-01</excludeColumn>
- <excludeColumn pattern="excludeColumn-02"/>
-
- <includeProcedure>includeProcedure-01</includeProcedure>
- <includeProcedure pattern="includeProcedure-02"/>
-
- <excludeProcedure>excludeProcedure-01</excludeProcedure>
- <excludeProcedure pattern="excludeProcedure-02"/>
-
-</catalog></programlisting>
- </para>
- <note>
- <para>
- In Ant task configuration all filter tags located inside root tag <code><cdbimport></code> as there is no <code><dbimport></code> tag.
- </para>
- </note>
- </section>
-</chapter>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/cayenne-guide/src/docbkx/re-introduction.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/cayenne-guide/src/docbkx/re-introduction.xml b/docs/docbook/cayenne-guide/src/docbkx/re-introduction.xml
deleted file mode 100644
index 37609ac..0000000
--- a/docs/docbook/cayenne-guide/src/docbkx/re-introduction.xml
+++ /dev/null
@@ -1,88 +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.
--->
-<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
- version="5.0" xml:id="re-introduction">
- <title>Introduction</title>
- <section xml:id="what-is-cdbimport">
- <title>"DB-first" Flow</title>
- <para>An ORM system consists of three parts: database, OR mapping and persistent Java classes.
- These parts always need to be kept in sync with each other for the application to work.
- "DB-first" flow is a common and practical approach to synchronization that assumes the
- database to be the master source of the metadata, with other two parts synchronized from
- the DB as the schema evolves. Cayenne provides a number of tools to automate and control
- it. Here is how "DB-first" flow is typically implemented:<itemizedlist>
- <listitem>
- <para> A SQL migrations framework is used to bring a local DB to a certain
- version. This is outside of the scope of Cayenne and is done with a
- third-party tool, such as Liquibase or Flyway.</para>
- </listitem>
- <listitem>
- <para>OR mapping model (Cayenne XML files) are synchronized with the state of the database
- using <code>"cdbimport"</code> tool provdied by Cayenne.</para>
- </listitem>
- <listitem>
- <para>Object layer of the OR mapping model is customized to the developer liking, usually via
- CayenneModeler. Subsequent runs of <code>"cdbimport"</code> will not
- override any customizations that you make.</para>
- </listitem>
- <listitem>
- <para>Java classes are generated using <code>"cgen"</code> tool provided by Cayenne.</para>
- </listitem>
- </itemizedlist></para>
- <para>"cgen" and "cdbimport" tools can be invoked from Maven or Ant as discussed in the
- "Including Cayenne in a Project" chapter or run from CayenneModeler. This chapter will
- mostly focus on "cdbimport". </para>
- <para>
- Here is simple maven configuration to start with:
-
-
- </para>
- </section>
- <section xml:id="re-configuration-file">
- <title>Introduction to "cdbimport"</title>
- <para>Here is a simple Maven configuration of "cdbimport" (for details see <link linkend="mvn-cdbimport">cayenne-maven-plugin</link> documentation)</para>
- <para>
- <programlisting language="xml">
- <plugin>
- <groupId>org.apache.cayenne.plugins</groupId>
- <artifactId>cayenne-maven-plugin</artifactId>
- <version><?eval ${project.version}?></version>
-
- <configuration>
- <map>${project.basedir}/src/main/resources/datamap.map.xml</map>
- <dataSource>
- <url><!-- jdbc url --></url>
- <driver><!-- jdbc driver class --></driver>
- <username>username</username>
- <password>password</password>
- </dataSource>
- <dbimport>
- <defaultPackage>com.example.package</defaultPackage>
- <includeTable>.*</includeTable>
- </dbimport>
- </configuration>
- <dependencies>
- <!-- jdbc driver dependency -->
- </dependencies>
- </plugin>
- </programlisting>
- </para>
-
- <para>In the next chapters we will discuss various filtering and other reverse-engineering
- options.</para>
- </section>
-</chapter>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/cayenne-guide/src/docbkx/re-modeler.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/cayenne-guide/src/docbkx/re-modeler.xml b/docs/docbook/cayenne-guide/src/docbkx/re-modeler.xml
deleted file mode 100644
index 1347658..0000000
--- a/docs/docbook/cayenne-guide/src/docbkx/re-modeler.xml
+++ /dev/null
@@ -1,122 +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.
--->
-<chapter version="5.0" xml:id="re-modeler" xmlns="http://docbook.org/ns/docbook"
- xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:ns="http://docbook.org/ns/docbook">
- <title>Reverse Engineering in Cayenne Modeler</title>
-
- <para>Alternative aproach to using <link linkend="what-is-cdbimport">cdbimport </link> is doing
- reverse engineering from <link linkend="running-cayennemodeler">Cayenne Modeler</link>.
- Currently modeler GUI doesn't support all features of ant/maven tasks but it suffice for
- general DB import. Especially it's a good place to quickly start working on your data model. </para>
-
- <para>
- You can find reverse engineering tool in main modeler menu
- <emphasis role="strong">
- <guimenu>Tools</guimenu> > <guimenuitem>Reengineer Database Schema</guimenuitem>
- </emphasis>
- </para>
-
- <section xml:id="modeler-re-datasource">
- <title>DataSource selection</title>
- <para>First you should select DataSource. If you don't have any DataSource
- yet you can create one from this menu.
- <mediaobject>
- <imageobject condition="web">
- <imagedata fileref="images/re-modeler-datasource-select.png"
- format="PNG" scale="70"/>
- </imageobject>
-
- <textobject>
- <phrase>Datasource selection dialog</phrase>
- </textobject>
-
- <caption>
- <para>Datasource selection dialog.</para>
- </caption>
- </mediaobject>
- </para>
- </section>
-
- <section xml:id="modeler-re-options">
- <title>Reverse engineering options</title>
- <para>Once DataSource is selected you can proceed to reverse engineering
- options.
- <mediaobject>
- <imageobject condition="web">
- <imagedata fileref="images/re-modeler-reverseengineering-dialog.png"
- format="PNG" scale="70"/>
- </imageobject>
-
- <textobject>
- <phrase>Reverse Engineering dialog</phrase>
- </textobject>
-
- <caption>
- <para>Reverse Engineering dialog.</para>
- </caption>
- </mediaobject>
- </para>
-
- <para>
- Here is a list of options to tune what will be processed by reverse engineering:
- <itemizedlist>
- <listitem>
- <para><emphasis role="strong">Select Catalog</emphasis>:
- catalog to process
- <note>
- <para>You can only select one catalog. If you need to import multiple catalogs you need to run process several times.</para>
- </note>
- </para>
- </listitem>
-
- <listitem>
- <para><emphasis role="strong">Table Name Pattern</emphasis>:
- RegExp to filter tables. Default pattern <code>.*</code> includes all tables.
- </para>
- </listitem>
- <listitem>
- <para><emphasis role="strong">Procedure Name Pattern</emphasis>:
- RegExp to filter procedures. Default pattern <code>.*</code> includes all stored procedures.
- </para>
- </listitem>
- <listitem>
- <para><emphasis role="strong">Naming Strategy</emphasis>:
- Currently there is only one naming strategy available.
- See ant/maven tools <link linkend="re-name-generator">documentation</link> for details about naming strategy.
- </para>
- </listitem>
- <listitem>
- <para><emphasis role="strong">Tables with Meaningful PK Pattern</emphasis>:
- Comma separated list of RegExp's for tables that you want to have meaningful primary keys.
- By default no meaningful PKs are created.
- </para>
- </listitem>
- <listitem>
- <para><emphasis role="strong">Use Java primitive types</emphasis>:
- Use primitive types (e.g. <code>int</code>) or Object types (e.g. <code>java.lang.Integer</code>).
- </para>
- </listitem>
- <listitem>
- <para><emphasis role="strong">Use old java.util.Date type</emphasis>:
- Use <code>java.util.Date</code> for all columns with <code>DATE/TIME/TIMESTAMP</code> types.
- By default <code>java.time.*</code> types will be used.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </section>
-</chapter>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/cayenne-guide/src/docbkx/re-other-settings.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/cayenne-guide/src/docbkx/re-other-settings.xml b/docs/docbook/cayenne-guide/src/docbkx/re-other-settings.xml
deleted file mode 100644
index 29d0c22..0000000
--- a/docs/docbook/cayenne-guide/src/docbkx/re-other-settings.xml
+++ /dev/null
@@ -1,65 +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.
--->
-<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
- version="5.0" xml:id="re-relationships-loading-control">
- <title>Other Settings</title>
- <para>
- In databases relations are defined via foreign keys and there are a lot of different politics according to the level of relationships and
- ways how those relationships could be modeled in database. Anyway, cdbimport is able to recognize basic patterns of relationships, such as
- OneToMany, OneToOne and ManyToMany.
- </para>
- <section xml:id="skip-relationships-loading">
- <title>Skip Relationships Loading</title>
- <para>
- You are able to skip relationships loading by the <code language="xml"><skipRelationshipsLoading></code> element.
- </para>
- <programlisting language="xml">
- <dbimport>
- <skipRelationshipsLoading>true</skipRelationshipsLoading>
- </dbimport></programlisting>
- </section>
- <section xml:id="skip-pk-loading">
- <title>Skip Primary Keys Loading</title>
- <para>
- Another useful Cayenne reverse engineering property is <code language="xml"><skipPrimaryKeyLoading></code>. If you decide to support all relationships at the application layer
- and avoid their management in database, you’ll find useful to turn off primary keys synchronization at all.
- </para>
- <programlisting language="xml">
- <dbimport>
- <skipPrimaryKeyLoading>true</skipPrimaryKeyLoading>
- </dbimport></programlisting>
- </section>
- <section>
- <title>Table Types</title>
- <para>By default, cdbimport imports tables and views. Some databases may support other
- table-like objects, e.g. <code>SYSTEM TABLE, GLOBAL TEMPORARY, LOCAL TEMPORARY, ALIAS,
- SYNONYM</code>, etc. To control which types should be included <code language="xml"
- ><tableType></tableType></code> element is used. Some examples:</para>
- <para> Import tables only (skip views and others and other
- types):<programlisting language="xml">
- <dbimport>
- <tableType>TABLE</tableType>
- </dbimport></programlisting>
- </para>
- <para> Tables and views (<emphasis>the default
- option</emphasis>):<programlisting language="xml">
- <dbimport>
- <tableType>TABLE</tableType>
- <tableType>VIEWS</tableType>
- </dbimport></programlisting></para>
- </section>
-</chapter>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/cayenne-guide/src/docbkx/rop-deployment.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/cayenne-guide/src/docbkx/rop-deployment.xml b/docs/docbook/cayenne-guide/src/docbkx/rop-deployment.xml
deleted file mode 100644
index b15a8b9..0000000
--- a/docs/docbook/cayenne-guide/src/docbkx/rop-deployment.xml
+++ /dev/null
@@ -1,47 +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.
--->
-<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
- version="5.0" xml:id="rop-deployment">
- <title>ROP Deployment</title>
- <section xml:id="deploying-rop-server">
- <title>Deploying ROP Server</title>
-
- <note><para>Recent versions of Tomcat and Jetty containers (e.g. Tomcat 6 and 7, Jetty 8) contain code
- addressing a security concern related to "session fixation problem" by resetting the
- existing session ID of any request that requires BASIC authentcaition. If ROP
- service is protected with declarative security (see the ROP tutorial and the
- following chapters on security), this feature prevents the ROP client from attaching
- to its session, resulting in MissingSessionExceptions. To solve that you will need
- to either switch to an alternative security mechanism, or disable "session fixation
- problem" protections of the container. E.g. the later can be achieved in Tomcat 7 by
- adding the following <emphasis>context.xml</emphasis> file to the webapp's META-INF/
- directory:
- <programlisting language="xml"><Context>
- <Valve className="org.apache.catalina.authenticator.BasicAuthenticator"
- changeSessionIdOnAuthentication="false" />
-</Context></programlisting>(The
- <Valve> tag can also be placed within the <Context> in any other locations
- used by Tomcat to load context configurations)</para></note>
-
- </section>
- <section xml:id="deploying-rop-client">
- <title>Deploying ROP Client</title>
- </section>
- <section xml:id="rop-security">
- <title>Security</title>
- </section>
-</chapter>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/cayenne-guide/src/docbkx/rop-introduction.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/cayenne-guide/src/docbkx/rop-introduction.xml b/docs/docbook/cayenne-guide/src/docbkx/rop-introduction.xml
deleted file mode 100644
index fb32ca4..0000000
--- a/docs/docbook/cayenne-guide/src/docbkx/rop-introduction.xml
+++ /dev/null
@@ -1,98 +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.
--->
-<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
- version="5.0" xml:id="introduction-to-rop">
- <title>Introduction to ROP</title>
- <section xml:id="what-is-rop">
- <title>What is ROP</title>
- <para>"Remote Object Persistence" is a low-overhead web services-based technology that
- provides lightweight object persistence and query functionality to 'remote'
- applications. In other words it provides familiar Cayenne API to applications that do
- not have direct access to the database. Instead such applications would access Cayenne
- Web Service (CWS). A single abstract data model (expressed as Cayenne XML DataMap) is
- used on the server and on the client, while execution logic can be partitioned between
- the tiers.The following picture compares a regular Cayenne web application and a rich
- client application that uses remote object persistence technology:</para>
- <para><inlinemediaobject>
- <imageobject>
- <imagedata fileref="images/remote-object-persistence.jpg" scalefit="1" width="100%"/>
- </imageobject>
- </inlinemediaobject></para>
- <para>Persistence stack above consists of the following parts:<itemizedlist>
- <listitem>
- <para>ORM Tier: a server-side Cayenne Java application that directly connects to
- the database via JDBC.</para>
- </listitem>
- <listitem>
- <para>CWS (Cayenne Web Service): A wrapper around an ORM tier that makes it
- accessible to remote CWS clients.</para>
- </listitem>
- <listitem>
- <para>Remote Tier (aka Client Tier): A Java application that has no direct DB
- connection and persists its objects by connecting to remote Cayenne Web
- Service (CWS). Note that CWS Client doesn't have to be a desktop
- application. It can be another server-side application. The word "client"
- means a client of Cayenne Web Service.</para>
- </listitem>
- </itemizedlist></para>
- </section>
- <section xml:id="main-features">
- <title>Main Features</title>
- <itemizedlist>
-
- <listitem>
- <para>Unified approach to lightweight object persistence across multiple
- tiers of a distributed system.</para>
- </listitem>
- <listitem>
- <para>Same abstract object model on the server and on the client.</para>
- </listitem>
- <listitem>
- <para>Client can "bootstrap" from the server by dynamically loading
- persistence metadata.</para>
- </listitem>
- <listitem>
- <para>An ability to define client objects differently than the server ones,
- and still have seamless persistence.</para>
- </listitem>
- <listitem>
- <para>Generic web service interface that doesn't change when object model
- changes.</para>
- </listitem>
- <listitem>
- <para>An ability to work in two modes: dedicated session mode or shared
- ("chat") mode when multiple remote clients collaboratively work on the
- same data.</para>
- </listitem>
- <listitem>
- <para>Lazy object and collection faulting.</para>
- </listitem>
- <listitem>
- <para>Full context lifecycle</para>
- </listitem>
- <listitem>
- <para>Queries, expressions, local query caching, paginated queries.</para>
- </listitem>
- <listitem>
- <para>Validation</para>
- </listitem>
- <listitem>
- <para>Delete Rules</para>
- </listitem>
- </itemizedlist>
- </section>
-</chapter>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/cayenne-guide/src/docbkx/rop-setup.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/cayenne-guide/src/docbkx/rop-setup.xml b/docs/docbook/cayenne-guide/src/docbkx/rop-setup.xml
deleted file mode 100644
index dde1922..0000000
--- a/docs/docbook/cayenne-guide/src/docbkx/rop-setup.xml
+++ /dev/null
@@ -1,26 +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.
--->
-<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
- version="5.0" xml:id="rop-setup">
- <title>ROP Setup</title>
- <section xml:id="rop-system-requirements">
- <title>System Requirements</title>
- </section>
- <section xml:id="rop-jar-files-dependencies">
- <title>Jar Files and Dependencies</title>
- </section>
-</chapter>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/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
deleted file mode 100644
index ba804a6..0000000
--- a/docs/docbook/cayenne-guide/src/docbkx/setup.xml
+++ /dev/null
@@ -1,176 +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.
--->
-<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
- version="5.0" xml:id="setup">
- <title>Setup</title>
- <section xml:id="system-requirements">
- <title>System Requirements</title>
- <para>
- <itemizedlist>
- <listitem>
- <para><emphasis role="italic">Java</emphasis>: Cayenne runtime framework and
- CayenneModeler GUI tool are written in 100% Java, and run on any
- Java-compatible platform. Minimal required JDK version depends on the
- version of Cayenne you are using, as shown in the following table:
- <table frame="void">
- <caption>Cayenne Version History</caption>
- <col width="28%"/>
- <col width="36%"/>
- <col width="36%"/>
- <tbody>
- <tr>
- <th>Cayenne Version</th>
- <th>Java Version</th>
- <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>
- </tr>
- <tr>
- <td>3.1</td>
- <td>Java 1.5 or newer</td>
- <td>Stable</td>
- </tr>
- <tr>
- <td>3.0</td>
- <td>Java 1.5</td>
- <td>Aging</td>
- </tr>
- <tr>
- <td>1.2 / 2.0</td>
- <td>Java 1.4</td>
- <td>Legacy</td>
- </tr>
- <tr>
- <td>1.1</td>
- <td>Java 1.3</td>
- <td>Legacy</td>
- </tr>
- </tbody>
- </table></para>
- </listitem>
- </itemizedlist>
- <itemizedlist>
- <listitem>
- <para><emphasis role="italic">JDBC Driver:</emphasis> An appropriate DB-specific
- JDBC driver is needed to access the database. It can be included in the
- application or used in web container DataSource configuration.</para>
- </listitem>
- </itemizedlist>
- <itemizedlist>
- <listitem>
- <para><emphasis role="italic">Third-party Libraries:</emphasis> Cayenne runtime
- framework has a minimal set of required and a few more optional dependencies
- on third-party open source packages. See
- <link linkend="including-cayenne-in-project">"Including Cayenne in a Project"</link>
- chapter for details.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </section>
- <section xml:id="running-cayennemodeler">
- <title>Running CayenneModeler</title>
- <para>CayenneModeler GUI tool is intended to work with object relational mapping projects. While
- you can edit your XML by hand, it is rarely needed, as the Modeler is a pretty advanced
- tool included in Cayenne distribution. To obtain CayenneModeler, download Cayenne
- distribution archive from
- <link xlink:href="http://cayenne.apache.org/download.html">http://cayenne.apache.org/download.html</link>
- matching the OS you are using. Of course Java needs to be installed on the machine where
- you are going to run the Modeler.
- </para>
- <itemizedlist>
- <listitem>
- <para>OS X distribution contains CayenneModeler.app at the root of the distribution disk
- image.
- </para>
- </listitem>
- <listitem>
- <para>Windows distribution contains CayenneModeler.exe file in the
- <code>bin</code>
- directory.
- </para>
- </listitem>
- <listitem>
- <para>Cross-platform distribution (targeting Linux, but as the name implies, compatible with any
- OS) contains a runnable CayenneModeler.jar in the <code>bin</code> directory. It can be
- executed either by double-clicking, or if the environment is not configured to execute
- jars, by running from command-line:
- </para>
- <screen><prompt>$</prompt> java -jar CayenneModeler.jar</screen>
- </listitem>
- </itemizedlist>
-
- <para>The Modeler can also be started from Maven. While it may look like an exotic way to start a
- GUI application, it has its benefits - no need to download Cayenne distribution, the
- version of the Modeler always matches the version of the framework, the plugin can find
- mapping files in the project automatically. So it is an attractive option to some
- developers. Maven option requires a declaration in the
- POM:
- <programlisting language="xml"><build>
- <plugins>
- <plugin>
- <groupId>org.apache.cayenne.plugins</groupId>
- <artifactId>cayenne-modeler-maven-plugin</artifactId>
- <version><?eval ${project.version}?></version>
- </plugin>
- </plugins>
-</build></programlisting>
- </para>
- <para>And then can be run as
- <screen><prompt>$</prompt> mvn cayenne-modeler:run</screen>
- </para>
- <para>
- <table frame="void">
- <caption>modeler plugin parameters</caption>
- <col width="14%"/>
- <col width="7%"/>
- <col width="79%"/>
- <thead>
- <tr>
- <th>Name</th>
- <th>Type</th>
- <th>Description</th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td><code>modelFile</code>
- </td>
- <td>File</td>
- <td>Name of the model file to open. Here is some simple example:
- <programlisting language="xml"><plugin>
- <groupId>org.apache.cayenne.plugins</groupId>
- <artifactId>cayenne-modeler-maven-plugin</artifactId>
- <version>${cayenne.version}</version>
- <configuration>
- <modelFile>src/main/resources/cayenne.xml</modelFile>
- </configuration>
-</plugin></programlisting>
- </td>
- </tr>
- </tbody>
- </table></para>
- </section>
-</chapter>
[07/13] cayenne git commit: CAY-2371 Switch documentation from
Docbook to Asciidoctor format
Posted by nt...@apache.org.
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/cayenne-guide/src/docbkx/customizing-cayenne-runtime.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/cayenne-guide/src/docbkx/customizing-cayenne-runtime.xml b/docs/docbook/cayenne-guide/src/docbkx/customizing-cayenne-runtime.xml
deleted file mode 100644
index 3383e01..0000000
--- a/docs/docbook/cayenne-guide/src/docbkx/customizing-cayenne-runtime.xml
+++ /dev/null
@@ -1,473 +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.
--->
-<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="customizing-cayenne-runtime">
- <title>Customizing Cayenne Runtime</title>
- <section xml:id="depdendency-injection-container">
- <title>Dependency Injection Container</title>
- <para>Cayenne runtime is built around a small powerful dependency injection (DI) container. Just
- like other popular DI technologies, such as Spring or Guice, Cayenne DI container
- manages sets of interdependent objects and allows users to configure them. These
- objects are regular Java objects. We are calling them "services" in this document to
- distinguish from all other objects that are not configured in the container and are not
- managed. DI container is responsible for service instantiation, injecting correct
- dependencies, maintaining service instances scope, and dispatching scope events to
- services. </para>
- <para>The services are configured in special Java classes called "modules". Each module
- defines binding of service interfaces to implementation instances, implementation types
- or providers of implementation instances. There are no XML configuration files, and all
- the bindings are type-safe. The container supports injection into instance variables and
- constructor parameters based on the <code>@Inject</code> annotation. This mechanism is
- very close to Google Guice.</para>
- <para>The discussion later in this chapter demonstrates a standalone DI container. But keep in
- mind that Cayenne already has a built-in Injector, and a set of default modules. A
- Cayenne user would normally only use the API below to write custom extension modules
- that will be loaded in that existing container when creating ServerRuntime. See
- "Starting and Stopping ServerRuntime" chapter for an example of passing an extension
- module to Cayenne.</para>
- <para>Cayenne DI probably has ~80% of the features expected in a DI container and has no
- dependency on the rest of Cayenne, so in theory can be used as an application-wide DI
- engine. But it's primary purpose is still to serve Cayenne. Hence there are no plans to
- expand it beyond Cayenne needs. It is an ideal "embedded" DI that does not interfere
- with Spring, Guice or any other such framework present elsewhere in the
- application.</para>
- <section xml:id="di-bindings-api">
- <title>DI Bindings API</title>
- <para>To have a working DI container, we need three things: service interfaces and
- classes, a module that describes service bindings, a container that loads the
- module, and resolves the depedencies. Let's start with service interfaces and
- classes:<programlisting language="java">public interface Service1 {
- public String getString();
-}</programlisting><programlisting language="java">public interface Service2 {
- public int getInt();
-}</programlisting></para>
- <para>A service implementation using instance variable
- injection:<programlisting language="java">public class Service1Impl implements Service1 {
- @Inject
- private Service2 service2;
-
- public String getString() {
- return service2.getInt() + "_Service1Impl";
- }
-}</programlisting>Same
- thing, but using constructor
- injection:<programlisting language="java">public class Service1Impl implements Service1 {
-
- private Service2 service2;
-
- public Service1Impl(@Inject Service2 service2) {
- this.service2 = service2;
- }
-
- public String getString() {
- return service2.getInt() + "_Service1Impl";
- }
-}
-</programlisting><programlisting language="java">public class Service2Impl implements Service2 {
- private int i;
-
- public int getInt() {
- return i++;
- }
-}</programlisting></para>
- <para>Now let's create a module implementing
- <code>org.apache.cayenne.tutorial.di.Module</code> interface that will contain
- DI configuration. A module binds service objects to keys that are reference. Binder
- provided by container implements fluent API to connect the key to implementation,
- and to configure various binding options (the options, such as scope, are
- demonstrated later in this chapter). The simplest form of a key is a Java Class
- object representing service interface. Here is a module that binds Service1 and
- Service2 to corresponding default implementations:</para>
- <para>
- <programlisting language="java">public class Module1 implements Module {
-
- public void configure(Binder binder) {
- binder.bind(Service1.class).to(Service1Impl.class);
- binder.bind(Service2.class).to(Service2Impl.class);
- }
-}</programlisting>
- </para>
- <para>Once we have at least one module, we can create a DI container.
- <code>org.apache.cayenne.di.Injector</code> is the container class in
- Cayenne:<programlisting language="java">Injector injector = DIBootstrap.createInjector(new Module1());</programlisting></para>
- <para>Now that we have created the container, we can obtain services from it and call
- their
- methods:<programlisting language="java">Service1 s1 = injector.getInstance(Service1.class);
-for (int i = 0; i < 5; i++) {
- System.out.println("S1 String: " + s1.getString());
-}</programlisting></para>
- <para>This outputs the following lines, demonstrating that s1 was Service1Impl and
- Service2 injected into it was
- Service2Impl:<programlisting language="java">0_Service1Impl
-1_Service1Impl
-2_Service1Impl
-3_Service1Impl
-4_Service1Impl</programlisting></para>
- <para>There are more flavors of bindings:
- <programlisting language="java">// binding to instance - allowing user to create and configure instance
-// inside the module class
-binder.bind(Service2.class).toInstance(new Service2Impl());
-
-// binding to provider - delegating instance creation to a special
-// provider class
-binder.bind(Service1.class).toProvider(Service1Provider.class);
-
-// binding to provider instance
-binder.bind(Service1.class).toProviderInstance(new Service1Provider());
-
-// multiple bindings of the same type using Key
-// injection can reference the key name in annotation:
-// @Inject("i1")
-// private Service2 service2;
-binder.bind(Key.get(Service2.class, "i1")).to(Service2Impl.class);
-binder.bind(Key.get(Service2.class, "i2")).to(Service2Impl.class);</programlisting></para>
- <para>Another types of confiuguration that can be bound in the container are lists and
- maps. They will be discussed in the following chapters. </para>
- </section>
- <section xml:id="managing-services-lifecycle">
- <title>Service Lifecycle</title>
- <para>An important feature of the Cayenne DI container is instance <emphasis role="italic"
- >scope</emphasis>. The default scope (implicitly used in all examples above) is
- "singleton", meaning that a binding would result in creation of only one service
- instance, that will be repeatedly returned from
- <code>Injector.getInstance(..)</code>, as well as injected into classes that
- declare it as a dependency. </para>
- <para>Singleton scope dispatches a "BeforeScopeEnd" event to interested services. This
- event occurs before the scope is shutdown, i.e. when
- <code>Injector.shutdown()</code> is called. Note that the built-in Cayenne
- injector is shutdown behind the scenes when <code>ServerRuntime.shutdown()</code>
- is invoked. Services may register as listeners for this event by annotating a
- no-argument method with <code>@BeforeScopeEnd</code> annotation. Such method should
- be implemented if a service needs to clean up some resources, stop threads,
- etc.</para>
- <para>Another useful scope is "no scope", meaning that every time a container is asked to provide
- a service instance for a given key, a new instance will be created and
- returned:<programlisting language="java">binder.bind(Service2.class).to(Service2Impl.class).withoutScope();</programlisting>Users
- can also create their own scopes, e.g. a web application request scope or a session
- scope. Most often than not custom scopes can be created as instances of
- <code>org.apache.cayenne.di.spi.DefaultScope</code> with startup and shutdown
- managed by the application (e.g. singleton scope is a DefaultScope managed by the
- Injector) . </para>
- </section>
- <section xml:id="overriding-services">
- <title>Overriding Services</title>
- <para>Cayenne DI allows to override services already definied in the current module, or
- more commonly - some other module in the the same container. Actually there's no
- special API to override a service, you'd just bind the service key again with a new
- implementation or provider. The last binding for a key takes precedence. This means
- that the order of modules is important when configuring a container. The built-in
- Cayenne injector ensures that Cayenne standard modules are loaded first, followed by
- optional user extension modules. This way the application can override the standard
- services in Cayenne.</para>
- </section>
- </section>
- <section xml:id="ways-to-customize-runtime">
- <title> Customization Strategies</title>
- <para>The previous section discussed how Cayenne DI works in general terms. Since Cayenne users
- will mostly be dealing with an existing Injector provided by ServerRuntime, it is
- important to understand how to build custom extensions to a preconfigured container. As
- shown in "Starting and Stopping ServerRuntime" chapter, custom extensions are done by
- writing an aplication DI module (or multiple modules) that configures service overrides.
- This section shows all the configuration possibilities in detail, including changing
- properties of the existing services, contributing services to standard service lists and
- maps, and overriding service implementations. All the code examples later in this
- section are assumed to be placed in an application module "configure" method:</para><programlisting language="java">public class MyExtensionsModule implements Module {
- public void configure(Binder binder) {
- // customizations go here...
- }
-}</programlisting><programlisting language="java">Module extensions = new MyExtensionsModule();
-ServerRuntime runtime = ServerRuntime.builder()
- .addConfig("com/example/cayenne-mydomain.xml")
- .addModule(extensions)
- .build();</programlisting>
- <section xml:id="changing-properties-of-existing-services">
- <title>Changing Properties of Existing Services</title>
- <para>Many built-in Cayenne services change their behavior based on a value of some
- environment property. A user may change Cayenne behavior without even knowing which
- services are responsible for it, but setting a specific value of a known property.
- Supported property names are listed in "Appendix A".</para>
- <para>There are two ways to set service properties. The most obvious one is to pass it
- to the JVM with -D flag on startup.
- E.g.<screen><prompt>$</prompt> java -Dcayenne.server.contexts_sync_strategy=false ...</screen></para>
- <para>A second one is to contribute a property to
- <code>org.apache.cayenne.configuration.DefaultRuntimeProperties.properties
- </code>map (see the next section on how to do that). This map contains the default
- property values and can accept application-specific values, overrding the defaults. </para>
- <para>Note that if a property value is a name of a Java class, when this Java class is
- instantiated by Cayenne, the container performs injection of instance variables. So
- even the dynamically specified Java classes can use @Inject annotation to get a hold
- of other Cayenne services.</para>
- <para>If the same property is specified both in the command line and in the properties
- map, the command-line value takes precedence. The map value will be ignored. This
- way Cayenne runtime can be reconfigured during deployment.</para>
- </section>
- <section xml:id="contributing-to-service-lists-maps">
- <title>Contributing to Service Collections</title>
- <para>Cayenne can be extended by adding custom objects to named maps or lists bound in
- DI. We are calling these lists/maps "service collections". A service collection
- allows things like appending a custom strategy to a list of built-in strategies.
- E.g. an application that needs to install a custom DbAdapter for some database type
- may contribute an instance of custom DbAdapterDetector to a
- <code>org.apache.cayenne.configuration.server.DefaultDbAdapterFactory.detectors</code>
- list:</para>
- <programlisting language="java">public class MyDbAdapterDetector implements DbAdapterDetector {
- public DbAdapter createAdapter(DatabaseMetaData md) throws SQLException {
- // check if we support this database and retun custom adapter
- ...
- }
-}</programlisting>
- <programlisting language="java">// since build-in list for this key is a singleton, repeated
-// calls to 'bindList' will return the same instance
-binder.bindList(DefaultDbAdapterFactory.DETECTORS_LIST)
- .add(MyDbAdapterDetector.class);</programlisting>
- <para>Maps are customized using a similar "<code>bindMap</code>" method.</para>
- <para>The names of built-in collections are listed in "Appendix B".</para>
- </section>
- <section xml:id="alternative-service-implementations">
- <title>Alternative Service Implementations</title>
- <para>As mentioned above, custom modules are loaded by ServerRuntime after the built-in
- modules. So it is easy to redefine a built-in service in Cayenne by rebinding
- desired implementations or providers. To do that, first we need to know what those
- services to redefine are. While we describe some of them in the following sections,
- the best way to get a full list is to check the source code of the Cayenne version
- you are using and namely look in
- <code>org.apache.cayenne.configuration.server.ServerModule</code> - the main
- built-in module in Cayenne. </para>
- <para>Now an example of overriding <code>QueryCache</code> service. The default
- implementation of this service is provided by <code>MapQueryCacheProvider</code>.
- But if we want to use <code>EhCacheQueryCache</code> (a Cayenne wrapper for the
- EhCache framework), we can define it like
- this:<programlisting language="java">binder.bind(QueryCache.class).to(EhCacheQueryCache.class);</programlisting></para>
- </section>
- </section>
- <section>
- <title>Using custom data types</title>
- <section>
- <title>Value object type</title>
- <para>
- <code>ValueObjectType</code> is a new and lightweight alternative to the Extended Types API described in the following section.
- In most cases is should be preferred as is it easier to understand and use. Currently only one case is known when <code>ExtendedType</code> should be used:
- when your value object can be mapped on different JDBC types.
- </para>
- <para>
- In order to use your custom data type you should implement <code>ValueObjectType</code> describing it in terms of some type already known to Cayenne
- (e.g. backed by system or user ExtendedType).
- </para>
- <para>
- Let's assume we want to support some data type called <code>Money</code>:
- <programlisting language="java"><![CDATA[public class Money {
- private BigDecimal value;
-
- public Money(BigDecimal value) {
- this.value = value;
- }
-
- public BigDecimal getValue() {
- return value;
- }
-
- // .. some other business logic ..
-}]]></programlisting>
- Here is how <code>ValueObjectType</code> that will allow to store our <code>Money</code> class as <code>BigDecimal</code>
- can be implemented:
- <programlisting language="java"><![CDATA[public class MoneyValueObjectType implements ValueObjectType<Money, BigDecimal> {
-
- @Override
- public Class<BigDecimal> getTargetType() {
- return BigDecimal.class;
- }
-
- @Override
- public Class<Money> getValueType() {
- return Money.class;
- }
-
- @Override
- public Money toJavaObject(BigDecimal value) {
- return new Money(value);
- }
-
- @Override
- public BigDecimal fromJavaObject(Money object) {
- return object.getValue();
- }
-
- @Override
- public String toCacheKey(Money object) {
- return object.getValue().toString();
- }
-}]]></programlisting>
- </para>
- <para>
- Last step is to register this new type in <code>ServerRuntime</code>:
- <programlisting language="java"><![CDATA[ServerRuntime runtime = ServerRuntime.builder()
- .addConfig("cayenne-project.xml")
- .addModule(binder -> ServerModule.contributeValueObjectTypes(binder).add(MoneyValueObjectType.class))
- .build();]]></programlisting>
- </para>
- <para>More examples of implementation you can find in
- <link xlink:href="https://github.com/apache/cayenne/tree/STABLE-4.0/cayenne-java8/src/main/java/org/apache/cayenne/java8/access/types">cayenne-java8 module</link>
- </para>
- </section>
- <section xml:id="extendedtypes">
- <title>Extended Types</title>
- <para>JDBC specification defines a set of "standard" database column types (defined in java.sql.Types class)
- and a very specific mapping of these types to Java Object Types, such as java.lang.String,
- java.math.BigDecimal, etc. Sometimes there is a need to use a custom Java type not known to JDBC driver and
- Cayenne allows to configure it. For this Cayenne needs to know how to instantiate this type from
- a database "primitive" value, and conversely, how to transform an object of the custom type to
- a JDBC-compatible object.</para>
- <section xml:id="supporting-non-standard-types">
- <title>Supporting Non-Standard Types</title>
- <para>For supporting non-standard type you should define it via an interface <code>org.apache.cayenne.access.types.ExtendedType</code>.
- An implementation must provide <code>ExtendedType.getClassName()</code> method that returns
- a fully qualified Java class name for the supported custom type, and a number of methods
- that convert data between JDBC and custom type.
- The following example demonstrates how to add a custom DoubleArrayType
- to store <code>java.lang.Double[]</code> as a custom string in a database:</para>
- <programlisting language="java">
-/**
-* Defines methods to read Java objects from JDBC ResultSets and write as parameters of
-* PreparedStatements.
-*/
-public class DoubleArrayType implements ExtendedType {
-
- private final String SEPARATOR = ",";
-
- /**
- * Returns a full name of Java class that this ExtendedType supports.
- */
- @Override
- public String getClassName() {
- return Double[].class.getCanonicalName();
- }
-
- /**
- * Initializes a single parameter of a PreparedStatement with object value.
- */
- @Override
- public void setJdbcObject(PreparedStatement statement, Object value,
- int pos, int type, int scale) throws Exception {
-
- String str = StringUtils.join((Double[]) value, SEPARATOR);
- statement.setString(pos, str);
- }
-
-
- /**
- * Reads an object from JDBC ResultSet column, converting it to class returned by
- * 'getClassName' method.
- *
- * @throws Exception if read error occurred, or an object can't be converted to a
- * target Java class.
- */
- @Override
- public Object materializeObject(ResultSet rs, int index, int type) throws Exception {
- String[] str = rs.getString(index).split(SEPARATOR);
- Double[] res = new Double[str.length];
-
- for (int i = 0; i < str.length; i++) {
- res[i] = Double.valueOf(str[i]);
- }
-
- return res;
- }
-
- /**
- * Reads an object from a stored procedure OUT parameter, converting it to class
- * returned by 'getClassName' method.
- *
- * @throws Exception if read error ocurred, or an object can't be converted to a
- * target Java class.
- */
- @Override
- public Object materializeObject(CallableStatement rs, int index, int type) throws Exception {
- String[] str = rs.getString(index).split(SEPARATOR);
- Double[] res = new Double[str.length];
-
- for (int i = 0; i < str.length; i++) {
- res[i] = Double.valueOf(str[i]);
- }
-
- return res;
- }
-}
- </programlisting>
- <para>For Java7</para>
- <programlisting language="java">
-// add DoubleArrayType to list of user types
-ServerRuntime runtime = ServerRuntime.builder()
- .addConfig("cayenne-project.xml")
- .addModule(new Module() {
- @Override
- public void configure(Binder binder) {
- ServerModule.contributeUserTypes(binder).add(new DoubleArrayType());
- }
- })
- .build();
- </programlisting>
- <para>For Java8</para>
- <programlisting language="java">
-// add DoubleArrayType to list of user types
-ServerRuntime runtime = ServerRuntime.builder()
- .addConfig("cayenne-project.xml")
- .addModule(binder -> ServerModule.contributeUserTypes(binder).add(new DoubleArrayType()))
- .build();
- </programlisting>
- </section>
- <section xml:id="dbadapters-and-extended-types">
- <title>DbAdapters and Extended Types</title>
- <para>As shown in the example above, ExtendedTypes are stored by DbAdapter. In fact DbAdapters often install
- their own extended types to address incompatibilities, incompleteness and differences between
- JDBC drivers in handling "standard" JDBC types. For instance some drivers support reading large
- character columns (CLOB) as java.sql.Clob, but some other - as "character stream", etc.
- Adapters provided with Cayenne override <code>configureExtendedTypes()</code> method to install their own types,
- possibly substituting Cayenne defaults. Custom DbAdapters can use the same technique.</para>
- </section>
- </section>
- </section>
- <section xml:id="noteworthy-runtime-components">
- <title>Noteworthy Built-in Services</title>
- <section xml:id="jdbceventlogger">
- <title>JdbcEventLogger</title>
- <para><code>org.apache.cayenne.log.JdbcEventLogger</code> is the service that defines
- logging API for Cayenne internals. It provides facilities for logging queries,
- commits, transactions, etc. The default implementation is
- <code>org.apache.cayenne.log.Slf4jJdbcEventLogger</code> that performs logging
- via slf4j-api library. Cayenne library includes another potentially useful
- logger - <code>org.apache.cayenne.log.FormattedSlf4jJdbcEventLogger</code> that
- produces formatted multiline SQL output that can be easier to read.</para>
- </section>
- <section xml:id="datasourcefactory">
- <title>DataSourceFactory</title>
- <para>Factory that returns <code>javax.sql.DataSource</code> object based on the configuration provided in the
- "nodeDescriptor".
- </para>
- </section>
- <section xml:id="datachannelfilter">
- <title>DataChannelFilter</title>
- <para> An interface of a filter that allows to intercept DataChannel operations. Filters allow
- to implement chains of custom processors around a DataChannel, that can be used for
- security, monitoring, business logic, providing context to lifecycle event listeners,
- etc.
- </para>
- </section>
- <section xml:id="querycache">
- <title>QueryCache</title>
- <para>Defines API of a cache that stores query results.</para>
- </section>
- </section>
-</chapter>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/cayenne-guide/src/docbkx/expressions.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/cayenne-guide/src/docbkx/expressions.xml b/docs/docbook/cayenne-guide/src/docbkx/expressions.xml
deleted file mode 100644
index 48e7462..0000000
--- a/docs/docbook/cayenne-guide/src/docbkx/expressions.xml
+++ /dev/null
@@ -1,303 +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.
--->
-<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
- version="5.0" xml:id="expressions">
- <title>Expressions</title>
- <section xml:id="expressions-overview">
- <title>Expressions Overview</title>
- <para>Cayenne provides a simple yet powerful object-based expression language. The most common
- usese of expressions are to build qualifiers and orderings of queries that are later
- converted to SQL by Cayenne and to evaluate in-memory against specific objects (to
- access certain values in the object graph or to perform in-memory object filtering and
- sorting). Cayenne provides API to build expressions in the code and a parser to create
- expressions from strings.</para>
- </section>
- <section xml:id="path-expressions">
- <title>Path Expressions</title>
- <para>Before discussing how to build expressions, it is important to understand one group of
- expressions widely used in Cayenne - path expressions. There are two types of path
- expressions - object and database, used for navigating graphs of connected objects or
- joined DB tables respectively. Object paths are much more commonly used, as after all
- Cayenne is supposed to provide a degree of isolation of the object model from the
- database. However database paths are helpful in certain situations. General structure of
- path expressions is the following:<programlisting> [db:]segment[+][.segment[+]...]</programlisting><itemizedlist>
- <listitem>
- <para>"db:" is an optional prefix indicating that the following path is a DB
- path. Otherwise it is an object path.</para>
- </listitem>
- <listitem>
- <para>"segment" is a name of a property (relationship or attribute in Cayenne
- terms) in the path. Path must have at least one segment; segments are
- separated by dot (".").</para>
- </listitem>
- <listitem>
- <para>"+" An "OUTER JOIN" path component. Currently "+" only has effect when
- translated to SQL as OUTER JOIN. When evaluating expressions in memory, it
- is ignored.</para>
- </listitem>
- </itemizedlist></para>
- <para>An object path expression represents a chain of property names rooted in a certain
- (unspecified during expression creation) object and "navigating" to its related value.
- E.g. a path expression "artist.name" might be a property path starting from a Painting
- object, pointing to the related Artist object, and then to its name attribute. A few
- more examples:</para>
- <para>
- <itemizedlist>
- <listitem>
- <para>"name" - can be used to navigate (read) the "name" property of a Person
- (or any other type of object that has a "name" property).</para>
- </listitem>
- <listitem>
- <para>"artist.exhibits.closingDate" - can be used to navigate to a closing date
- of any of the exhibits of a Painting's Artist object.</para>
- </listitem>
- <listitem>
- <para>"artist.exhibits+.closingDate" - same as the previous example, but when
- translated into SQL, an OUTER JOIN will be used for "exhibits".</para>
- </listitem>
- </itemizedlist>
- </para>
- <para>Similarly a database path expression is a dot-separated path through DB table joins
- and columns. In Cayenne joins are mapped as DbRelationships with some symbolic names
- (the closest concept to DbRelationship name in the DB world is a named foreign key
- constraint. But DbRelationship names are usually chosen arbitrarily, without regard to
- constraints naming or even constraints presence). A database path therefore might look
- like this - "db:dbrelationshipX.dbrelationshipY.COLUMN_Z". More specific examples:<itemizedlist>
- <listitem>
- <para>"db:NAME" - can be used to navigate to the value of "NAME" column of some
- unspecified table.</para>
- </listitem>
- <listitem>
- <para>"db:artist.artistExhibits.exhibit.CLOSING_DATE" - can be used to match a
- closing date of any of the exhibits of a related artist record.</para>
- </listitem>
- </itemizedlist></para>
- <para>Cayenne supports "aliases" in path Expressions. E.g. the same expression can be
- written using explicit path or an alias:<itemizedlist>
- <listitem>
- <para>"artist.exhibits.closingDate" - full path</para>
- </listitem>
- <listitem>
- <para>"e.closingDate" - alias "e" is used for "artist.exhibits".</para>
- </listitem>
- </itemizedlist>SelectQuery using the second form of the path expression must be made
- aware of the alias via <emphasis role="italic">
- "SelectQuery.aliasPathSplits(..)"</emphasis>, otherwise an Exception will be
- thrown. The main use of aliases is to allow users to control how SQL joins are generated
- if the same path is encountered more than once in any given Expression. Each alias for
- any given path would result in a separate join. Without aliases, a single join will be
- used for a group of matching paths.</para>
- </section>
- <section xml:id="expressions-from-strings">
- <title>Creating Expressions from Strings </title>
- <para>While in most cases users are likely to rely on API from the following section for
- expression creation, we'll start by showing String expressions, as this will help
- to understand the semantics. A Cayenne expression can be represented as a String, which
- can be converted to an expression object using <code>ExpressionFactory.exp</code> static
- method. Here is an
- example:<programlisting language="java">String expString = "name like 'A%' and price < 1000";
-Expression exp = ExpressionFactory.exp(expString);</programlisting>This
- particular expression may be used to match Paintings whose names that start with
- "A" and whose price is less than $1000. While this example is pretty
- self-explanatory, there are a few points worth mentioning. "name" and
- "price" here are object paths discussed earlier. As always, paths themselves
- are not attached to a specific root entity and can be applied to any entity that has
- similarly named attributes or relationships. So when we are saying that this expression
- "may be used to match Paintings", we are implying that there may be other
- entities, for which this expression is valid. Now the expression details... </para>
- <para><emphasis role="italic">Character constants</emphasis> that are not paths or numeric values
- should be enclosed in single or double quotes. Two of the expressions below are
- equivalent:<programlisting language="SQL">name = 'ABC'
-
-// double quotes are escaped inside Java Strings of course
-name = \"ABC\"</programlisting></para>
- <para><emphasis role="italic">Case sensitivity.</emphasis> Expression operators are case
- sensitive and are usually lowercase. Complex words follow the Java camel-case
- style:<programlisting language="SQL">// valid
-name likeIgnoreCase 'A%'
-
-// invalid - will throw a parse exception
-name LIKEIGNORECASE 'A%'</programlisting></para>
- <para><emphasis role="italic">Grouping with parenthesis:</emphasis>
- <programlisting>value = (price + 250.00) * 3</programlisting>
- </para>
- <para><emphasis role="italic">Path prefixes.</emphasis> Object expressions are unquoted strings,
- optionally prefixed by "obj:" (usually they are not prefixed at all actually). Database
- expressions are always prefixed with "db:". A special kind of prefix, not discussed yet
- is "enum:" that prefixes an enumeration
- constant:<programlisting language="SQL">// object path
-name = 'Salvador Dali'
-
-// same object path - a rarely used form
-obj:name = 'Salvador Dali'
-
-// multi-segment object path
-artist.name = 'Salvador Dali'
-
-// db path
-db:NAME = 'Salvador Dali'
-
-// enumeration constant
-name = enum:org.foo.EnumClass.VALUE1</programlisting></para>
- <para>
- <emphasis role="italic">Binary conditions</emphasis> are expressions that contain a path
- on the left, a value on the right, and some operation between them, such as equals,
- like, etc. They can be used as qualifiers in SelectQueries:<programlisting language="SQL">name like 'A%'</programlisting>
- <emphasis role="italic">Parameters.</emphasis> Expressions can contain named parameters
- (names that start with "$") that can be substituted with values either by name
- or by position. Parameterized expressions allow to create reusable expression templates.
- Also if an Expression contains a complex object that doesn't have a simple String
- representation (e.g. a Date, a DataObject, an ObjectId), parameterizing such expression
- is the only way to represent it as String. Here are the examples of both positional and
- named parameter
- bindings:<programlisting language="java">Expression template = ExpressionFactory.exp("name = $name");
-...
-// name binding
-Map p1 = Collections.singletonMap("name", "Salvador Dali");
-Expression qualifier1 = template.params(p1);
-...
-// positional binding
-Expression qualifier2 = template.paramsArray("Monet");</programlisting></para>
- <para>Positional binding is usually shorter. You can pass positional bindings to the
- <code>"exp(..)"</code> factory method (its second argument is a params
- vararg):<programlisting>Expression qualifier = ExpressionFactory.exp("name = $name", "Monet");</programlisting></para>
- <para>In parameterized expressions with LIKE clause, SQL wildcards must be part of the
- values in the Map and not the expression string
- itself:<programlisting language="java">Expression qualifier = ExpressionFactory.exp("name like $name", "Salvador%");</programlisting>When
- matching on a relationship, the value parameter must be either a Persistent object, an
- <code>org.apache.cayenne.ObjectId</code>, or a numeric ID value (for single column
- IDs).
- E.g.:<programlisting language="java">Artist dali = ... // asume we fetched this one already
-Expression qualifier = ExpressionFactory.exp("artist = $artist", dali);</programlisting>When
- using positional binding, Cayenne would expect values for <emphasis role="bold"
- >all</emphasis> parameters to be present. Binding by name offers extra flexibility:
- subexpressions with uninitialized parameters are automatically pruned from the
- expression. So e.g. if certain parts of the expression criteria are not provided to the
- application, you can still build a valid
- expression:<programlisting language="java">Expression template = ExpressionFactory.exp("name like $name and dateOfBirth > $date");
-...
-Map p1 = Collections.singletonMap("name", "Salvador%");
-Expression qualifier1 = template.params(p1);
-
-// "qualifier1" is now "name like 'Salvador%'".
-// 'dateOfBirth > $date' condition was pruned, as no value was specified for
-// the $date parameter</programlisting></para>
- <para><emphasis role="italic">Null handling.</emphasis> Handling of Java nulls as operands
- is no different from normal values. Instead of using special conditional operators, like
- SQL does (IS NULL, IS NOT NULL), "=" and "!=" expressions are used
- directly with null values. It is up to Cayenne to translate expressions with nulls to
- the valid SQL.</para>
- <para>
- <note>
- <para>A formal definition of the expression grammar is provided in Appendix C</para>
- </note>
- </para>
- </section>
- <section xml:id="expressions-with-expressionfactory">
- <title>Creating Expressions via API</title>
- <para>Creating expressions from Strings is a powerful and dynamic approach, however a safer
- alternative is to use Java API. It provides compile-time checking of expressions
- validity. The API in question is provided by <code>ExpressionFactory</code> class (that
- we've seen already), <code>Property</code> class and <code>Expression</code> class
- itself. <code>ExpressionFactory</code> contains a number of self-explanatory static
- methods that can be used to build expressions. E.g.:</para>
- <para>
- <programlisting language="java">// String expression: name like 'A%' and price < 1000
-Expression e1 = ExpressionFactory.likeExp("name", "A%");
-Expression e2 = ExpressionFactory.lessExp("price, 1000);
-Expression finalExp = e1.andExp(e2); </programlisting>
- <note>
- <para>The last line in the example above shows how to create a new expression by
- "chaining" two other epxressions. A common error when chaining
- expressions is to assume that "andExp" and "orExp" append
- another expression to the current expression. In fact a new expression is
- created. I.e. Expression API treats existing expressions as immutable.</para>
- </note>
- </para>
- <para>As discussed earlier, Cayenne supports aliases in path Expressions, allowing to
- control how SQL joins are generated if the same path is encountered more than once in
- the same Expression. Two ExpressionFactory methods allow to implicitly generate aliases
- to "split" match paths into individual joins if
- needed:<programlisting language="java">Expression matchAllExp(String path, Collection values)
-Expression matchAllExp(String path, Object... values)</programlisting></para>
- <para>"Path" argument to both of these methods can use a split character (a pipe
- symbol '|') instead of dot to indicate that relationship following a path
- should be split into a separate set of joins, one per collection value. There can only
- be one split at most in any given path. Split must always precede a relationship. E.g.
- <code>"|exhibits.paintings"</code>, <code>"exhibits|paintings"</code>, etc.
- Internally Cayenne would generate distinct aliases for each of the split expressions,
- forcing separate joins.</para>
- <para>While ExpressionFactory is pretty powerful, there's an even easier way to create
- expression using static Property objects generated by Cayenne for each persistent class.
- Some
- examples:<programlisting>// Artist.NAME is generated by Cayenne and has a type of Property<String>
-Expression e1 = Artist.NAME.eq("Pablo");
-
-// Chaining multiple properties into a path..
-// Painting.ARTIST is generated by Cayenne and has a type of Property<Artist>
-Expression e2 = Painting.ARTIST.dot(Artist.NAME).eq("Pablo");</programlisting></para>
- <para>Property objects provide the API mostly analogius to ExpressionFactory, though it is
- significantly shorter and is aware of the value types. It provides compile-time checks
- of both property names and types of arguments in conditions. We will use Property-based
- API in further examples.</para>
- </section>
- <section xml:id="expressions-in-memory">
- <title>Evaluating Expressions in Memory</title>
- <para>When used in a query, an expression is converted to SQL WHERE clause (or ORDER BY
- clause) by Cayenne during query execution. Thus the actual evaluation against the data
- is done by the database engine. However the same expressions can also be used for
- accessing object properties, calculating values, in-memory filtering. </para>
- <para>Checking whether an object satisfies an
- expression:<programlisting language="java">Expression e = Artist.NAME.in("John", "Bob");
-Artist artist = ...
-if(e.match(artist)) {
- ...
-}</programlisting>Reading
- property
- value:<programlisting language="java">String name = Artist.NAME.path().evaluate(artist);</programlisting></para>
- <para>Filtering a list of
- objects:<programlisting language="java">Expression e = Artist.NAME.in("John", "Bob");
-List<Artist> unfiltered = ...
-List<Artist> filtered = e.filterObjects(unfiltered);</programlisting></para>
- <para>
- <note>
- <para>Current limitation of in-memory expressions is that no collections are
- permitted in the property path.</para>
- </note>
- </para>
- </section>
-
- <section xml:id="expressions-to-ejbql">
- <title>Translating Expressions to EJBQL</title>
- <para>
- <link linkend="ejbqlquery">EJBQL</link> is a textual query language that can be used
- with Cayenne. In some situations, it is convenient to be able to convert Expression
- instances into EJBQL. Expressions support this conversion. An example is shown below.
- <programlisting language="java">String serial = ...
-Expression e = Pkg.SERIAL.eq(serial);
-List<Object> params = new ArrayList<Object>();
-EJBQLQuery query = new EJBQLQuery("SELECT p FROM Pkg p WHERE " + e.toEJBQL(params,"p");
-
-for(int i=0;i<params.size();i++) {
- query.setParameter(i+1, params.get(i));
-}</programlisting>
- This would be equivalent to the following purely EJBQL querying logic;
- <programlisting language="java">EJBQLQuery query = new EJBQLQuery("SELECT p FROM Pkg p WHERE p.serial = ?1");
-query.setParameter(1,serial);</programlisting>
- </para>
- </section>
-</chapter>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/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
deleted file mode 100644
index f3e0a0d..0000000
--- a/docs/docbook/cayenne-guide/src/docbkx/ext-cache-invalidation.xml
+++ /dev/null
@@ -1,91 +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.
- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~-->
-<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 an extension that allows to define cache invalidation policy programmatically.</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 enable it.
- Just mark your entities with <code>@CacheGroups</code> annotation and you are ready to use it:
- <programlisting language="java"><![CDATA[
-@CacheGroups("some-group")
-public class MyEntity extends _MyEntity {
- // ...
-}]]></programlisting>
- After any modification of <code>MyEntity</code> objects cache group <code>"some-group"</code>
- will be dropped from cache 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 default behaviour and provide your own.
- </para>
- <para>
- To do so you need to implement <code>org.apache.cayenne.cache.invalidation.InvalidationHandler</code> interface and setup Cache Invalidation module to
- use it.
- Let's use implementation class called <code>CustomInvalidationHandler</code> that will simply match
- all entities' types with <code>"custom-group"</code> cache group regardless of any annotations:
- <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/cde78f0b/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
deleted file mode 100644
index 20aec52..0000000
--- a/docs/docbook/cayenne-guide/src/docbkx/ext-commit-log.xml
+++ /dev/null
@@ -1,89 +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.
- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~-->
-<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 steps:
- <orderedlist>
- <listitem>
- <para>Mark all entities which changes you are interested in with <code>@org.apache.cayenne.commitlog.CommitLog</code> annotation</para>
- <programlisting language="java"><![CDATA[
-@CommitLog(ignoredProperties = {"somePrivatePropertyToSkip"})
-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 particular example will 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/cde78f0b/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
deleted file mode 100644
index 8381bab..0000000
--- a/docs/docbook/cayenne-guide/src/docbkx/ext-crypto.xml
+++ /dev/null
@@ -1,135 +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.
- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~-->
-<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 module you must prepare your database to allow <code>byte[]</code> storage and properly name
- columns that will contain encrypted values.
- </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>.
- These 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>
- Default naming strategy that doesn't require additional setup suggests using <code>"CRYPTO_"</code> prefix.
- 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>
- Here is an example of how <code>ObjEntity</code> with two encrypted and two unencrypted properties
- can look like:
- </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>.
- 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 (later 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>
- 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/cde78f0b/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
deleted file mode 100644
index 715ebc6..0000000
--- a/docs/docbook/cayenne-guide/src/docbkx/ext-dbcp2.xml
+++ /dev/null
@@ -1,59 +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.
- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~-->
-<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 need to 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/cde78f0b/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
deleted file mode 100644
index 9ee1e70..0000000
--- a/docs/docbook/cayenne-guide/src/docbkx/ext-java8.xml
+++ /dev/null
@@ -1,53 +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.
- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~-->
-<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/cde78f0b/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
deleted file mode 100644
index 509d538..0000000
--- a/docs/docbook/cayenne-guide/src/docbkx/ext-jcache.xml
+++ /dev/null
@@ -1,61 +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.
- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~-->
-<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 to 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>
- To use JCache provider in your app you need to include this module and caching provider libs (e.g. Ehcache).
- You can provide own implementation of <code>org.apache.cayenne.jcache.JCacheConfigurationFactory</code>
- to customize cache configuration if required.
- </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 else 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/cde78f0b/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
deleted file mode 100644
index d777b68..0000000
--- a/docs/docbook/cayenne-guide/src/docbkx/ext-joda.xml
+++ /dev/null
@@ -1,53 +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.
- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~-->
-<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/cde78f0b/docs/docbook/cayenne-guide/src/docbkx/implementing-rop-client.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/cayenne-guide/src/docbkx/implementing-rop-client.xml b/docs/docbook/cayenne-guide/src/docbkx/implementing-rop-client.xml
deleted file mode 100644
index a95a0fd..0000000
--- a/docs/docbook/cayenne-guide/src/docbkx/implementing-rop-client.xml
+++ /dev/null
@@ -1,20 +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.
--->
-<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
- version="5.0" xml:id="implementing-rop-client">
- <title>Implementing ROP Client</title>
-</chapter>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/cayenne-guide/src/docbkx/implementing-rop-server.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/cayenne-guide/src/docbkx/implementing-rop-server.xml b/docs/docbook/cayenne-guide/src/docbkx/implementing-rop-server.xml
deleted file mode 100644
index 3032fd1..0000000
--- a/docs/docbook/cayenne-guide/src/docbkx/implementing-rop-server.xml
+++ /dev/null
@@ -1,20 +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.
--->
-<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
- version="5.0" xml:id="implementing-rop-server">
- <title>Implementing ROP Server</title>
-</chapter>
[11/13] cayenne git commit: CAY-2371 Switch documentation from
Docbook to Asciidoctor format
Posted by nt...@apache.org.
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/objectContext.adoc
----------------------------------------------------------------------
diff --git a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/objectContext.adoc b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/objectContext.adoc
new file mode 100644
index 0000000..de13e70
--- /dev/null
+++ b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/objectContext.adoc
@@ -0,0 +1,294 @@
+// 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.
+
+=== Persistent Objects and ObjectContext
+
+==== ObjectContext
+
+ObjectContext is an interface that users normally work with to access the database. It provides the API to execute database operations and to manage persistent objects. A context is obtained from the ServerRuntime:
+
+[source, java]
+----
+ObjectContext context = runtime.newContext();
+----
+
+The call above creates a new instance of ObjectContext that can access the database via this runtime. ObjectContext is a single "work area" in Cayenne, storing persistent objects. ObjectContext guarantees that for each database row with a unique ID it will contain at most one instance of an object, thus ensuring object graph consistency between multiple selects (a feature called "uniquing"). At the same time different ObjectContexts will have independent copies of objects for each unique database row. This allows users to isolate object changes from one another by using separate ObjectContexts.
+
+These properties directly affect the strategies for scoping and sharing (or not sharing) ObjectContexts. Contexts that are only used to fetch objects from the database and whose objects are never modified by the application can be shared between mutliple users (and multiple threads). Contexts that store modified objects should be accessed only by a single user (e.g. a web application user might reuse a context instance between multiple web requests in the same HttpSession, thus carrying uncommitted changes to objects from request to request, until he decides to commit or rollback them). Even for a single user it might make sense to use mutliple ObjectContexts (e.g. request-scoped contexts to allow concurrent requests from the browser that change and commit objects independently).
+
+ObjectContext is serializable and does not permanently hold to any of the application resources. So it does not have to be closed. If the context is not used anymore, it should simply be allowed to go out of scope and get garbage collected, just like any other Java object.
+
+
+==== Persistent Object and its Lifecycle
+
+Cayenne can persist Java objects that implement `org.apache.cayenne.Persistent interface`. Generally persistent classes are generated from the model as described above, so users do not have to worry about superclass and property implementation details.
+
+Persistent interface provides access to 3 persistence-related properties - objectId, persistenceState and objectContext. All 3 are initialized by Cayenne runtime framework. Application code should not attempt to change them. However it is allowed to read them, which provides valuable runtime information. E.g. ObjectId can be used for quick equality check of 2 objects, knowing persistence state would allow highlighting changed objects, etc.
+
+Each persistent object belongs to a single ObjectContext, and can be in one of the following persistence states (as defined in `org.apache.cayenne.PersistenceState`) :
+
+[#persistenceStates.table.table-bordered]
+.Persistence States
+// ^.^ is not a funny face it's Asciidoctor alignment syntax (center both vertical and horizontal)
+[cols="^.^1,4"]
+|===
+
+|*TRANSIENT*
+|The object is not registered with an ObjectContext and will not be persisted.
+
+|*NEW*
+|The object is freshly registered in an ObjectContext, but has not been saved to the database yet and there is no matching database row.
+
+|*COMMITED*
+|The object is registered in an ObjectContext, there is a row in the database corresponding to this object, and the object state corresponds to the last known state of the matching database row.
+
+|*MODIFIED*
+|The object is registered in an ObjectContext, there is a row in the database corresponding to this object, but the object in-memory state has diverged from the last known state of the matching database row.
+
+|*HOLLOW*
+|The object is registered in an ObjectContext, there is a row in the database corresponding to this object, but the object state is unknown. Whenever an application tries to access a property of such object, Cayenne attempts reading its values from the database and "inflate" the object, turning it to COMMITED.
+
+|*DELETED*
+|The object is registered in an ObjectContext and has been marked for deletion in-memory. The corresponding row in the database will get deleted upon ObjectContext commit, and the object state will be turned into TRANSIENT.
+|===
+
+==== ObjectContext Persistence API
+
+One of the first things users usually want to do with an ObjectContext is to select some objects from a database. This is done by calling "performQuery" method:
+
+[source, java]
+----
+SelectQuery query = new SelectQuery(Artist.class);
+List<Artist> artists = context.performQuery(query);
+----
+
+We'll discuss queries in some detail in the following chapters. The example above is self-explanatory - we create a SelectQuery that matches all Artist objects present in the database, and then call "performQuery", getting a list of Artist objects.
+
+Some queries can be quite complex, returning multiple result sets or even updating the database. For such queries ObjectContext provides "performGenericQuery"method. While not nearly as commonly-used as "performQuery", it is nevertheless important in some situations. E.g.:
+
+[source, java]
+----
+Collection<Query> queries = ... // multiple queries that need to be run together
+QueryChain query = new QueryChain(queries);
+
+QueryResponse response = context.performGenericQuery(query);
+----
+
+
+An application might modify selected objects. E.g.:
+
+[source, java]
+----
+Artist selectedArtist = artists.get(0);
+selectedArtist.setName("Dali");
+----
+
+The first time the object property is changed, the object's state is automatically set to "MODIFIED" by Cayenne. Cayenne tracks all in-memory changes until a user calls "commitChanges":
+
+[source, java]
+----
+context.commitChanges();
+----
+
+At this point all in-memory changes are analyzed and a minimal set of SQL statements is issued in a single transaction to synchronize the database with the in-memory state. In our example "commitChanges" commits just one object, but generally it can be any number of objects.
+
+If instead of commit, we wanted to reset all changed objects to the previously committed state, we'd call `rollbackChanges` instead:
+
+[source, java]
+----
+context.rollbackChanges();
+----
+
+"newObject" method call creates a persistent object and sets its state to "NEW":
+
+[source, java]
+----
+Artist newArtist = context.newObject(Artist.class);
+newArtist.setName("Picasso");
+----
+
+It will only exist in memory until "commitChanges" is issued. On commit Cayenne might generate a new primary key (unless a user set it explicitly, or a PK was inferred from a relationship) and issue an INSERT SQL statement to permanently store the object.
+
+`deleteObjects` method takes one or more Persistent objects and marks them as "DELETED":
+
+[source, java]
+----
+context.deleteObjects(artist1);
+context.deleteObjects(artist2, artist3, artist4);
+----
+
+Additionally "deleteObjects" processes all delete rules modeled for the affected objects. This may result in implicitly deleting or modifying extra related objects. Same as insert and update, delete operations are sent to the database only when "commitChanges" is called. Similarly "rollbackChanges" will undo the effect of "newObject" and "deleteObjects".
+
+`localObject` returns a copy of a given persistent object that is "local" to a given ObjectContext:
+
+Since an application often works with more than one context, "localObject" is a rather common operation. E.g. to improve performance a user might utilize a single shared context to select and cache data, and then occasionally transfer some selected objects to another context to modify and commit them:
+
+
+[source, java]
+----
+ObjectContext editingContext = runtime.newContext();
+Artist localArtist = editingContext.localObject(artist);
+----
+
+Often an appliction needs to inspect mapping metadata. This information is stored in the EntityResolver object, accessible via the ObjectContext:
+
+[source, java]
+----
+EntityResolver resolver = objectContext.getEntityResolver();
+----
+
+Here we discussed the most commonly used subset of the ObjectContext API. There are other useful methods, e.g. those allowing to inspect registered objects state in bulk, etc. Check the latest JavaDocs for details.
+
+==== Cayenne Helper Class
+
+There is a useful helper class called "Cayenne" (fully-qualified name `"org.apache.cayenne.Cayenne"`) that builds on ObjectContext API to provide a number of very common operations. E.g. get a primary key (most entities do not model PK as an object property) :
+
+[source, java]
+----
+long pk = Cayenne.longPKForObject(artist);
+----
+
+It also provides the reverse operation - finding an object given a known PK:
+
+[source, java]
+----
+Artist artist = Cayenne.objectForPK(context, Artist.class, 34579);
+----
+
+If a query is expected to return 0 or 1 object, Cayenne helper class can be used to find this object. It throws an exception if more than one object matched the query:
+
+[source, java]
+----
+Artist artist = (Artist) Cayenne.objectForQuery(context, new SelectQuery(Artist.class));
+----
+
+Feel free to explore Cayenne class API for other useful methods.
+
+==== ObjectContext Nesting
+In all the examples shown so far an ObjectContext would directly connect to a database to select data or synchronize its state (either via commit or rollback). However another context can be used in all these scenarios instead of a database. This concept is called ObjectContext "nesting". Nesting is a parent/child relationship between two contexts, where child is a nested context and selects or commits its objects via a parent.
+
+Nesting is useful to create isolated object editing areas (child contexts) that need to all be committed to an intermediate in-memory store (parent context), or rolled back without affecting changes already recorded in the parent. Think cascading GUI dialogs, or parallel AJAX requests coming to the same session.
+
+In theory Cayenne supports any number of nesting levels, however applications should generally stay with one or two, as deep hierarchies will most certainly degrade the performance of the deeply nested child contexts. This is due to the fact that each context in a nesting chain has to update its own objects during most operations.
+
+Cayenne ROP is an extreme case of nesting when a child context is located in a separate JVM and communicates with its parent via a web service. ROP is discussed in details in the following chapters. Here we concentrate on the same-VM nesting.
+
+To create a nested context, use an instance of ServerRuntime, passing it the desired parent:
+
+[source, java]
+----
+ObjectContext parent = runtime.newContext();
+ObjectContext nested = runtime.newContext((DataChannel) parent);
+----
+
+From here a nested context operates just like a regular context (you can perform queries, create and delete objects, etc.). The only difference is that commit and rollback operations can either be limited to synchronization with the parent, or cascade all the way to the database:
+
+[source, java]
+----
+// merges nested context changes into the parent context
+nested.commitChangesToParent();
+
+// regular 'commitChanges' cascades commit through the chain
+// of parent contexts all the way to the database
+nested.commitChanges();
+----
+
+[source, java]
+----
+// unrolls all local changes, getting context in a state identical to parent
+nested.rollbackChangesLocally();
+
+// regular 'rollbackChanges' cascades rollback through the chain of contexts
+// all the way to the topmost parent
+nested.rollbackChanges();
+----
+
+==== Generic Persistent Objects
+
+As described in the CayenneModeler chapter, Cayenne supports mapping of completely generic classes to specific entities. Although for conveniece most applications should stick with entity-specific class mappings, the generic feature offers some interesting possibilities, such as creating mappings completely on the fly in a running application, etc.
+
+Generic objects are first class citizens in Cayenne, and all common persistent operations apply to them as well. There are some pecularities however, described below.
+
+When creating a new generic object, either cast your ObjectContext to DataContext (that provides "newObject(String)" API), or provide your object with an explicit ObjectId:
+
+[source, java]
+----
+DataObject generic = ((DataContext) context).newObject("GenericEntity");
+----
+
+[source, java]
+----
+DataObject generic = new CayenneDataObject();
+generic.setObjectId(new ObjectId("GenericEntity"));
+context.registerNewObject(generic);
+----
+
+SelectQuery for generic object should be created passing entity name String in constructor, instead of a Java class:
+
+[source, java]
+----
+SelectQuery query = new SelectQuery("GenericEntity");
+----
+
+Use DataObject API to access and modify properties of a generic object:
+
+[source, java]
+----
+String name = (String) generic.readProperty("name");
+generic.writeProperty("name", "New Name");
+----
+
+This is how an application can obtain entity name of a generic object:
+
+[source, java]
+----
+String entityName = generic.getObjectId().getEntityName();
+----
+
+
+==== Transactions
+
+Considering how much attention is given to managing transactions in most other ORMs, transactions have been conspicuously absent from the ObjectContext discussion till now. The reason is that transactions are seamless in Cayenne in all but a few special cases. ObjectContext is an in-memory container of objects that is disconnected from the database, except when it needs to run an operation. So it does not care about any surrounding transaction scope. Sure enough all database operations are transactional, so when an application does a commit, all SQL execution is wrapped in a database transaction. But this is done behind the scenes and is rarely a concern to the application code.
+
+Two cases where transactions need to be taken into consideration are container-managed and application-managed transactions.
+
+If you are using an EJB container (or some other JTA environment), you'll likely need to switch Cayenne runtime into "external transactions mode". This is done by setting DI configuration property defined in `Constants.SERVER_EXTERNAL_TX_PROPERTY` (see Appendix A). If this property is set to "true", Cayenne assumes that JDBC Connections obtained by runtime whenever that might happen are all coming from a transactional DataSource managed by the container. In this case Cayenne does not attempt to commit or rollback the connections, leaving it up to the container to do that when appropriate.
+
+In the second scenario, an application might need to define its own transaction scope that spans more than one Cayenne operation. E.g. two sequential commits that need to be rolled back together in case of failure. This can be done via `ServerRuntime.performInTransaction` method:
+
+[source, java]
+----
+Integer result = runtime.performInTransaction(() -> {
+ // commit one or more contexts
+ context1.commitChanges();
+ context2.commitChanges();
+ ....
+ // after changing some objects in context1, commit again
+ context1.commitChanges();
+ ....
+
+ // return an arbitrary result or null if we don't care about the result
+ return 5;
+});
+----
+
+When inside the transaction, current thread Transaction object can be accessed via a static method. E.g. here is an example that initializes transaction JDBC connection with a custom connection object :
+
+[source, java]
+----
+Transaction tx = BaseTransaction.getThreadTransaction();
+tx.addConnection("mydatanode", myConnection);
+----
+
+
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/orderings.adoc
----------------------------------------------------------------------
diff --git a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/orderings.adoc b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/orderings.adoc
new file mode 100644
index 0000000..6b9b57a
--- /dev/null
+++ b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/orderings.adoc
@@ -0,0 +1,36 @@
+// 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.
+
+=== Orderings
+
+An Ordering object defines how a list of objects should be ordered. Orderings are essentially path expressions combined with a sorting strategy. Creating an Ordering:
+
+[source, java]
+----
+Ordering o = new Ordering(Painting.NAME_PROPERTY, SortOrder.ASCENDING);
+----
+
+Like expressions, orderings are translated into SQL as parts of queries (and the sorting occurs in the database). Also like expressions, orderings can be used in memory, naturally - to sort objects:
+
+[source, java]
+----
+Ordering o = new Ordering(Painting.NAME_PROPERTY, SortOrder.ASCENDING_INSENSITIVE);
+List<Painting> list = ...
+o.orderList(list);
+----
+
+Note that unlike filtering with Expressions, ordering is performed in-place. This list object is reordered and no new list is created.
+
+
+
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/queries.adoc
----------------------------------------------------------------------
diff --git a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/queries.adoc b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/queries.adoc
new file mode 100644
index 0000000..0fe969a
--- /dev/null
+++ b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/queries.adoc
@@ -0,0 +1,803 @@
+// 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.
+
+=== Queries
+
+Queries are Java objects used by the application to communicate with the database. Cayenne knows how to translate queries into SQL statements appropriate for a particular database engine. Most often queries are used to find objects matching certain criteria, but there are other types of queries too. E.g. those allowing to run native SQL, call DB stored procedures, etc. When committing objects, Cayenne itself creates special queries to insert/update/delete rows in the database.
+
+There is a number of built-in queries in Cayenne, described later in this chapter. Most of the newer queries use fluent API and can be created and executed as easy-to-read one-liners. Users can define their own query types to abstract certain DB interactions that for whatever reason can not be adequately described by the built-in set.
+
+Queries can be roughly categorized as "object" and "native". Object queries (most notably ObjectSelect, SelectById, and EJBQLQuery) are built with abstractions originating in the object model (the "object" side in the "object-relational" divide). E.g. ObjectSelect is assembled from a Java class of the objects to fetch, a qualifier expression, orderings, etc. - all of this expressed in terms of the object model.
+
+Native queries describe a desired DB operation as SQL code (SQLSelect, SQLTemplate query) or a reference to a stored procedure (ProcedureQuery), etc. The results of native queries are usually presented as Lists of Maps, with each map representing a row in the DB (a term "data row" is often used to describe such a map). They can potentially be converted to objects, however it may take a considerable effort to do so. Native queries are also less (if at all) portable across databases than object queries.
+[[select]]
+==== ObjectSelect
+
+===== Selecting objects
+
+ObjectSelect supersedes older SelectQuery. SelectQuery is still available and supported.
+
+ObjectSelect is the most commonly used query in Cayenne applications. This may be the only query you will ever need. It returns a list of persistent objects (or data rows) of a certain type specified in the query:
+
+[source, java]
+----
+List<Artist> objects = ObjectSelect.query(Artist.class).select(context);
+----
+
+This returned all rows in the "ARTIST" table. If the logs were turned on, you might see the following SQL printed:
+
+----
+INFO: SELECT t0.DATE_OF_BIRTH, t0.NAME, t0.ID FROM ARTIST t0
+INFO: === returned 5 row. - took 5 ms.
+----
+
+This SQL was generated by Cayenne from the ObjectSelect above. ObjectSelect can have a qualifier to select only the data matching specific criteria. Qualifier is simply an Expression (Expressions where discussed in the previous chapter), appended to the query using "where" method. If you only want artists whose name begins with 'Pablo', you might use the following qualifier expression:
+
+[source, java]
+----
+List<Artist> objects = ObjectSelect.query(Artist.class)
+ .where(Artist.NAME.like("Pablo%"))
+ .select(context);
+----
+
+The SQL will look different this time:
+
+----
+INFO: SELECT t0.DATE_OF_BIRTH, t0.NAME, t0.ID FROM ARTIST t0 WHERE t0.NAME LIKE ?
+[bind: 1->NAME:'Pablo%']
+INFO: === returned 1 row. - took 6 ms.
+----
+
+ObjectSelect allows to assemble qualifier from parts, using "and" and "or" method to chain then together:
+
+[source, java]
+----
+List<Artist> objects = ObjectSelect.query(Artist.class)
+ .where(Artist.NAME.like("A%"))
+ .and(Artist.DATE_OF_BIRTH.gt(someDate)
+ .select(context);
+----
+
+To order the results of ObjectSelect, one or more orderings can be applied:
+
+[source, java]
+----
+List<Artist> objects = ObjectSelect.query(Artist.class)
+ .orderBy(Artist.DATE_OF_BIRTH.desc())
+ .orderBy(Artist.NAME.asc())
+ .select(context);
+----
+
+There's a number of other useful methods in ObjectSelect that define what to select and how to optimize database interaction (prefetching, caching, fetch offset and limit, pagination, etc.). Some of them are discussed in separate chapters on caching and performance optimization. Others are fairly self-explanatory. Please check the API docs for the full extent of the ObjectSelect features.
+
+===== Selecting individual columns
+
+`ObjectSelect` query can be used to fetch individual properties of objects via type-safe API:
+
+[source, java]
+----
+List<String> names = ObjectSelect.columnQuery(Artist.class, Artist.ARTIST_NAME)
+ .select(context);
+----
+
+And here is example of selecting several properties, note that result will be `Object[]`:
+
+[source, java]
+----
+List<Object[]> nameAndDate = ObjectSelect
+ .columnQuery(Artist.class, Artist.ARTIST_NAME, Artist.DATE_OF_BIRTH)
+ .select(context);
+----
+
+===== Selecting using aggregate functions
+
+ObjectSelect query supports usage of aggregate functions. Most common variant of aggregation is selecting count of records, this can be done really easy:
+
+[source, java]
+----
+long count = ObjectSelect.query(Artist.class).selectCount(context);
+----
+
+But you can use aggregates in more cases, even combine selecting individual properties and aggregates:
+
+[source, java]
+----
+// this is artificial property signaling that we want to get full object
+Property<Artist> artistProperty = Property.createSelf(Artist.class);
+
+List<Object[]> artistAndPaintingCount = ObjectSelect.columnQuery(Artist.class, artistProperty, Artist.PAINTING_ARRAY.count())
+ .where(Artist.ARTIST_NAME.like("a%"))
+ .having(Artist.PAINTING_ARRAY.count().lt(5L))
+ .orderBy(Artist.PAINTING_ARRAY.count().desc(), Artist.ARTIST_NAME.asc())
+ .select(context);
+
+for(Object[] next : artistAndPaintingCount) {
+ Artist artist = (Artist)next[0];
+ long paintings = (Long)next[1];
+ System.out.println(artist.getArtistName() + " have " + paintings + " paintings");
+}
+----
+
+Here is generated `SQL` for this query:
+
+[source, SQL]
+----
+SELECT DISTINCT t0.ARTIST_NAME, t0.DATE_OF_BIRTH, t0.ARTIST_ID, COUNT(t1.PAINTING_ID)
+FROM ARTIST t0 JOIN PAINTING t1 ON (t0.ARTIST_ID = t1.ARTIST_ID)
+WHERE t0.ARTIST_NAME LIKE ?
+GROUP BY t0.ARTIST_NAME, t0.ARTIST_ID, t0.DATE_OF_BIRTH
+HAVING COUNT(t1.PAINTING_ID) < ?
+ORDER BY COUNT(t1.PAINTING_ID) DESC, t0.ARTIST_NAME
+----
+
+[[ejbql]]
+==== EJBQLQuery
+
+EJBQLQuery was created as a part of an experiment in adopting some of Java Persistence API (JPA) approaches in Cayenne. It is a parameterized object query that is created from query String. A String used to build EJBQLQuery must conform to JPQL (JPA query language):
+
+
+[source, java]
+----
+EJBQLQuery query = new EJBQLQuery("select a FROM Artist a");
+----
+
+JPQL details can be found in any JPA manual. Here we'll mention only how this fits into Cayenne and what are the differences between EJBQL and other Cayenne queries.
+
+Although most frequently EJBQLQuery is used as an alternative to SelectQuery, there are also DELETE and UPDATE varieties available.
+
+NOTE: As of this version of Cayenne, DELETE and UPDATE do not change the state of objects in the ObjectContext. They are run directly against the database instead.
+
+
+[source, java]
+----
+EJBQLQuery select = new EJBQLQuery("select a FROM Artist a WHERE a.name = 'Salvador Dali'");
+List<Artist> artists = context.performQuery(select);
+----
+
+[source, java]
+----
+EJBQLQuery delete = new EJBQLQuery("delete from Painting");
+context.performGenericQuery(delete);
+----
+
+[source, java]
+----
+EJBQLQuery update = new EJBQLQuery("UPDATE Painting AS p SET p.name = 'P2' WHERE p.name = 'P1'");
+context.performGenericQuery(update);
+----
+
+
+In most cases SelectQuery is preferred to EJBQLQuery, as it is API-based, and provides you with better compile-time checks. However sometimes you may want a completely scriptable object query. This is when you might prefer EJBQL. A more practical reason for picking EJBQL over SelectQuery though is that the former offers some extra selecting capabilities, namely aggregate functions and subqueries:
+
+[source, java]
+----
+EJBQLQuery query = new EJBQLQuery("select a, COUNT(p) FROM Artist a JOIN a.paintings p GROUP BY a");
+List<Object[]> result = context.performQuery(query);
+for(Object[] artistWithCount : result) {
+ Artist a = (Artist) artistWithCount[0];
+ int hasPaintings = (Integer) artistWithCount[1];
+}
+----
+
+
+This also demonstrates a previously unseen type of select result - a List of Object[] elements, where each entry in an Object[] is either a DataObject or a scalar, depending on the query SELECT clause. A result can also be a list of scalars:
+
+[source, java]
+----
+EJBQLQuery query = new EJBQLQuery("select a.name FROM Artist a");
+List<String> names = context.performQuery(query);
+----
+
+EJBQLQuery supports an "IN" clause with three different usage-patterns. The following example would require three individual positional parameters (named parameters could also have been used) to be supplied.
+
+[source, SQL]
+----
+select p from Painting p where p.paintingTitle in (?1,?2,?3)
+----
+
+The following example requires a single positional parameter to be supplied. The parameter can be any concrete implementation of the java.util.Collection interface such as java.util.List or java.util.Set.
+
+[source, SQL]
+----
+select p from Painting p where p.paintingTitle in ?1
+----
+
+The following example is functionally identical to the one prior.
+
+[source, SQL]
+----
+select p from Painting p where p.paintingTitle in (?1)
+----
+
+It is xref:evaluete[possible to convert] an xref:expressions[Expression] object used with a xref:select[SelectQuery] to EJBQL. Use the Expression#appendAsEJBQL methods for this purpose.
+
+While Cayenne Expressions discussed previously can be thought of as identical to JPQL WHERE clause, and indeed they are very close, there are a few noteable differences:
+
+- Null handling: SelectQuery would translate the expressions matching NULL values to the corresponding "X IS NULL" or "X IS NOT NULL" SQL syntax. EJBQLQuery on the other hand requires explicit "IS NULL" (or "IS NOT NULL") syntax to be used, otherwise the generated SQL will look like "X = NULL" (or "X <> NULL"), which will evaluate differently.
+
+- Expression Parameters: SelectQuery uses "$" to denote named parameters (e.g. "$myParam"), while EJBQL uses ":" (e.g. ":myParam"). Also EJBQL supports positional parameters denoted by the question mark: "?3".
+
+===== SelectById
+
+This query allows to search objects by their ID. It's introduced in Cayenne 4.0 and uses new "fluent" API same as `ObjectSelect` query.
+
+Here is example of how to use it:
+
+[source, java]
+----
+Artist artistWithId1 = SelectById.query(Artist.class, 1)
+ .prefetch(Artist.PAINTING_ARRAY.joint())
+ .localCache()
+ .selectOne(context);
+----
+
+===== SQLSelect and SQLExec
+
+`SQLSelect` and `SQLExec` are essentially a "fluent" versions of older `SQLTemplate` query. `SQLSelect` can be used (as name suggests) to select custom data in form of entities, separate columns or collection of `DataRow. SQLExec` is designed to just execute any raw SQL code (e.g. updates, deletes, DDLs, etc.) This queries support all directives described in xref:sqltemplate[SQLTemplate] section.
+
+Here is example of how to use SQLSelect:
+
+[source, java]
+----
+SQLSelect<Painting> q1 = SQLSelect
+ .query(Painting.class, "SELECT * FROM PAINTING WHERE PAINTING_TITLE LIKE #bind($title)")
+ .params("title", "painting%")
+ .upperColumnNames()
+ .localCache()
+ .limit(100)
+ .select(context);
+----
+
+
+And here is example of how to use `SQLExec`:
+
+[source, java]
+----
+int inserted = SQLExec
+ .query("INSERT INTO ARTIST (ARTIST_ID, ARTIST_NAME) VALUES (#bind($id), #bind($name))")
+ .paramsArray(55, "Picasso")
+ .update(context);
+----
+
+===== MappedSelect and MappedExec
+
+`MappedSelect` and `MappedExec` is a queries that are just a reference to another queries stored in the DataMap. The actual stored query can be SelectQuery, SQLTemplate, EJBQLQuery, etc. Difference between `MappedSelect` and `MappedExec` is (as reflected in their names) whether underlying query intended to select data or just to perform some generic SQL code.
+
+NOTE: These queries are "fluent" versions of deprecated `NamedQuery` class.
+
+Here is example of how to use `MappedSelect`:
+
+[source, java]
+----
+List<Artist> results = MappedSelect.query("artistsByName", Artist.class)
+ .param("name", "Picasso")
+ .select(context);
+----
+
+And here is example of `MappedExec`:
+
+[source, java]
+----
+QueryResult result = MappedExec.query("updateQuery")
+ .param("var", "value")
+ .execute(context);
+System.out.println("Rows updated: " + result.firstUpdateCount());
+----
+
+==== ProcedureCall
+
+Stored procedures are mapped as separate objects in CayenneModeler. `ProcedureCall` provides a way to execute them with a certain set of parameters. This query is a "fluent" version of older `ProcedureQuery`. Just like with `SQLTemplate`, the outcome of a procedure can be anything - a single result set, multiple result sets, some data modification (returned as an update count), or a combination of these. So use root class to get a single result set, and use only procedure name for anything else:
+
+
+[source, java]
+----
+List<Artist> result = ProcedureCall.query("my_procedure", Artist.class)
+ .param("p1", "abc")
+ .param("p2", 3000)
+ .call(context)
+ .firstList();
+----
+
+[source, java]
+----
+// here we do not bother with root class.
+// Procedure name gives us needed routing information
+ProcedureResult result = ProcedureCall.query("my_procedure")
+ .param("p1", "abc")
+ .param("p2", 3000)
+ .call();
+----
+
+A stored procedure can return data back to the application as result sets or via OUT parameters. To simplify the processing of the query output, QueryResponse treats OUT parameters as if it was a separate result set. For stored procedures declaref any OUT or INOUT parameters, `ProcedureResult` have convenient utility method to get them:
+
+[source, java]
+----
+ProcedureResult result = ProcedureCall.query("my_procedure")
+ .call(context);
+
+// read OUT parameters
+Object out = result.getOutParam("out_param");
+----
+
+There maybe a situation when a stored procedure handles its own transactions, but an application is configured to use Cayenne-managed transactions. This is obviously conflicting and undesirable behavior. In this case ProcedureQueries should be executed explicitly wrapped in an "external" Transaction. This is one of the few cases when a user should worry about transactions at all. See Transactions section for more details.
+
+==== Custom Queries
+
+If a user needs some extra functionality not addressed by the existing set of Cayenne queries, he can write his own. The only requirement is to implement `org.apache.cayenne.query.Query` interface. The easiest way to go about it is to subclass some of the base queries in Cayenne.
+
+E.g. to do something directly in the JDBC layer, you might subclass AbstractQuery:
+
+[source, java]
+----
+public class MyQuery extends AbstractQuery {
+
+ @Override
+ public SQLAction createSQLAction(SQLActionVisitor visitor) {
+ return new SQLAction() {
+
+ @Override
+ public void performAction(Connection connection, OperationObserver observer) throws SQLException, Exception {
+ // 1. do some JDBC work using provided connection...
+ // 2. push results back to Cayenne via OperationObserver
+ }
+ };
+ }
+}
+----
+
+To delegate the actual query execution to a standard Cayenne query, you may subclass IndirectQuery:
+
+
+[source, java]
+----
+public class MyDelegatingQuery extends IndirectQuery {
+
+ @Override
+ protected Query createReplacementQuery(EntityResolver resolver) {
+ SQLTemplate delegate = new SQLTemplate(SomeClass.class, generateRawSQL());
+ delegate.setFetchingDataRows(true);
+ return delegate;
+ }
+
+ protected String generateRawSQL() {
+ // build some SQL string
+ }
+}
+----
+
+In fact many internal Cayenne queries are IndirectQueries, delegating to SelectQuery or SQLTemplate after some preprocessing.
+
+[[sqltemplate]]
+==== SQLTemplate
+SQLTemplate is a query that allows to run native SQL from a Cayenne application. It comes handy when the standard ORM concepts are not sufficient for a given query or an update. SQL is too powerful and allows to manipulate data in ways that are not easily described as a graph of related entities. Cayenne acknowledges this fact and provides this facility to execute SQL, mapping the result to objects when possible. Here are examples of selecting and non-selecting SQLTemplates:
+
+
+[source, java]
+----
+SQLTemplate select = new SQLTemplate(Artist.class, "select * from ARTIST");
+List<Artist> result = context.performQuery(select);
+----
+
+[source, java]
+----
+SQLTemplate update = new SQLTemplate(Artist.class, "delete from ARTIST");
+QueryResponse response = context.performGenericQuery(update);
+----
+
+Cayenne doesn't make any attempt to make sense of the SQL semantics, so it doesn't know whether a given query is performing a select or update, etc. It is the the user's decision to run a given query as a selecting or "generic".
+
+NOTE: Any data modifications done to DB as a result of SQLTemplate execution do not change the state of objects in the ObjectContext. So some objects in the context may become stale as a result.
+
+Another point to note is that the first argument to the SQLTemplate constructor - the Java class - has the same meaning as in SelectQuery only when the result can be converted to objects (e.g. when this is a selecting query and it is selecting all columns from one table). In this case it denotes the "root" entity of this query result. If the query does not denote a single entity result, this argument is only used for query routing, i.e. determining which database it should be run against. You are free to use any persistent class or even a DataMap instance in such situation. It will work as long as the passed "root" maps to the same database as the current query.
+
+To achieve interoperability between mutliple RDBMS a user can specify multiple SQL statements for the same SQLTemplate, each corresponding to a native SQL dialect. A key used to look up the right dialect during execution is a fully qualified class name of the corresponding DbAdapter. If no DB-specific statement is present for a given DB, a default generic statement is used. E.g. in all the examples above a default statement will be used regardless of the runtime database. So in most cases you won't need to explicitly "translate" your SQL to all possible dialects. Here is how this works in practice:
+
+[source, java]
+----
+SQLTemplate select = new SQLTemplate(Artist.class, "select * from ARTIST");
+
+// For Postgres it would be nice to trim padding of all CHAR columns.
+// Otherwise those will be returned with whitespace on the right.
+// assuming "NAME" is defined as CHAR...
+String pgSQL = "SELECT ARTIST_ID, RTRIM(NAME), DATE_OF_BIRTH FROM ARTIST";
+query.setTemplate(PostgresAdapter.class.getName(), pgSQL);
+----
+
+===== Scripting SQLTemplate with Velocity
+
+The most interesting aspect of SQLTemplate (and the reason why it is called a "template") is that a SQL string is treated by Cayenne as an Apache Velocity template. Before sending it to DB as a PreparedStatement, the String is evaluated in the Velocity context, that does variable substitutions, and performs special callbacks in response to various directives, thus controlling query interaction with the JDBC layer.
+
+Check Velocity docs for the syntax details. Here we'll just mention the two main scripting elements - "variables" (that look like `$var`) and "directives" (that look like `#directive(p1 p2 p3)`). All built-in Velocity directives are supported. Additionally Cayenne defines a number of its own directives to bind parameters to PreparedStatements and to control the structure of the ResultSet. These directives are described in the following sections.
+
+
+===== Variable Substitution
+
+All variables in the template string are replaced from query parameters:
+
+
+[source, java]
+----
+SQLTemplate query = new SQLTemplate(Artist.class, "delete from $tableName");
+query.setParameters(Collections.singletonMap("tableName", "mydb.PAINTING"));
+
+// this will generate SQL like this: "delete from mydb.PAINTING"
+----
+
+The example above demonstrates the point made earlier in this chapter - even if we don't know upfront which table the query will run against, we can still use a fixed "root" in constructor (`Artist.class` in this case) , as we are not planning on converting the result to objects.
+
+Variable substitution within the text uses `"object.toString()"` method to replace the variable value. Keep in mind that this may not be appropriate in all situations. E.g. passing a date object in a WHERE clause expression may be converted to a String not understood by the target RDBMS SQL parser. In such cases variable should be wrapped in `#bind` directive as described below.
+
+[[directives]]
+===== Directives
+
+These are the Cayenne directives used to customize SQLTemplate parsing and integrate it with the JDBC layer:
+
+====== #bind
+
+Creates a PreparedStatement positional parameter in place of the directive, binding the value to it before statement execution. `#bind` is allowed in places where a "?" would be allowed in a PreparedStatement. And in such places it almost always makes sense to pass objects to the template via this or other forms of #bind instead of inserting them inline.
+
+Semantics:
+
+[source]
+----
+#bind(value)
+#bind(value jdbcType)
+#bind(value jdbcType scale)
+----
+
+Arguments:
+
+- `value` - can either be a char constant or a variable that is resolved from the query parameters. Note that the variable can be a collection, that will be automatically expanded into a list of individual value bindings. This is useful for instance to build IN conditions.
+
+- `jdbcType` - is a JDBC data type of the parameter as defined in `java.sql.Types`.
+
+- `scale` - An optional scale of the numeric value. Same as "scale" in PreparedStatement.
+
+Usage:
+
+[source]
+----
+#bind($xyz)
+#bind('str')
+#bind($xyz 'VARCHAR')
+#bind($xyz 'DECIMAL' 2)
+----
+
+Full example:
+
+[source, SQL]
+----
+update ARTIST set NAME = #bind($name) where ID = #bind($id)
+----
+
+
+====== #bindEqual
+
+Same as #bind, but also includes the "=" sign in front of the value binding. Look at the example below - we took the #bind example and replaced `"ID = #bind(..)"` with `"ID #bindEqual(..)"`. While it looks like a clumsy shortcut to eliminate the equal sign, the actual reason why this is useful is that it allows the value to be null. If the value is not null, `"= ?"` is generated, but if it is, the resulting chunk of the SQL would look like `"IS NULL"` and will be compilant with what the DB expects.
+
+Semantics:
+
+
+[source]
+----
+#bindEqual(value)
+#bindEqual(value jdbcType)
+#bindEqual(value jdbcType scale)
+----
+
+Arguments: (same as #bind)
+
+Usage:
+
+[source]
+----
+#bindEqual($xyz)
+#bindEqual('str')
+#bindEqual($xyz 'VARCHAR')
+#bindEqual($xyz 'DECIMAL' 2)
+----
+
+
+Full example:
+
+
+[source, SQL]
+----
+update ARTIST set NAME = #bind($name) where ID #bindEqual($id)
+----
+
+====== #bindNotEqual
+
+This directive deals with the same issue as `#bindEqual` above, only it generates "not equal" in front of the value (or IS NOT NULL).
+
+Semantics:
+
+[source]
+----
+#bindNotEqual(value)
+#bindNotEqual(value jdbcType)
+#bindNotEqual(value jdbcType scale)
+----
+
+Arguments: (same as #bind)
+
+Usage:
+
+[source]
+----
+#bindNotEqual($xyz)
+#bindNotEqual('str')
+#bindNotEqual($xyz 'VARCHAR')
+#bindNotEqual($xyz 'DECIMAL' 2)
+----
+
+Full example:
+
+
+[source, SQL]
+----
+update ARTIST set NAME = #bind($name) where ID #bindEqual($id)
+----
+
+====== #bindObjectEqual
+
+It can be tricky to use a Persistent object or an ObjectId in a binding, especially for tables with compound primary keys. This directive helps to handle such binding. It maps columns in the query to the names of Persistent object ID columns, extracts ID values from the object, and generates SQL like "COL1 = ? AND COL2 = ? ..." , binding positional parameters to ID values. It can also correctly handle null object. Also notice how we are specifying a Velocity array for multi-column PK.
+
+Semantics:
+
+[source]
+----
+#bindObjectEqual(value columns idColumns)
+----
+
+Arguments:
+
+- `value` - must be a variable that is resolved from the query parameters to a Persistent or ObjectId.
+
+- `columns` - the names of the columns to generate in the SQL.
+
+- `idColumn` - the names of the ID columns for a given entity. Must match the order of "columns" to match against.
+
+Usage:
+
+[source]
+----
+#bindObjectEqual($a 't0.ID' 'ID')
+#bindObjectEqual($b ['t0.FK1', 't0.FK2'] ['PK1', 'PK2'])
+----
+
+Full example:
+
+[source, java]
+----
+String sql = "SELECT * FROM PAINTING t0 WHERE #bindObjectEqual($a 't0.ARTIST_ID' 'ARTIST_ID' ) ORDER BY PAINTING_ID";
+SQLTemplate select = new SQLTemplate(Artist.class, sql);
+
+Artist a = ....
+select.setParameters(Collections.singletonMap("a", a));
+----
+
+====== #bindObjectNotEqual
+
+Same as #bindObjectEqual above, only generates "not equal" operator for value comparison (or IS NOT NULL).
+
+Semantics:
+
+[source]
+----
+#bindObjectNotEqual(value columns idColumns)
+----
+
+Arguments: (same as #bindObjectEqual)
+
+Usage:
+
+[source]
+----
+#bindObjectNotEqual($a 't0.ID' 'ID')
+#bindObjectNotEqual($b ['t0.FK1', 't0.FK2'] ['PK1', 'PK2'])
+----
+
+Full example:
+
+[source, java]
+----
+String sql = "SELECT * FROM PAINTING t0 WHERE #bindObjectNotEqual($a 't0.ARTIST_ID' 'ARTIST_ID' ) ORDER BY PAINTING_ID";
+SQLTemplate select = new SQLTemplate(Artist.class, sql);
+
+Artist a = ....
+select.setParameters(Collections.singletonMap("a", a));
+----
+
+====== #result
+
+Renders a column in SELECT clause of a query and maps it to a key in the result DataRow. Also ensures the value read is of the correct type. This allows to create a DataRow (and ultimately - a persistent object) from an arbitrary ResultSet.
+
+Semantics:
+
+[source]
+----
+#result(column)
+#result(column javaType)
+#result(column javaType alias)
+#result(column javaType alias dataRowKey)
+----
+
+Arguments:
+
+- `column` - the name of the column to render in SQL SELECT clause.
+
+- `javaType` - a fully-qualified Java class name for a given result column. For simplicity most common Java types used in JDBC can be specified without a package. These include all numeric types, primitives, String, SQL dates, BigDecimal and BigInteger. So "_#result('A' 'String')_", "_#result('B' 'java.lang.String')_" and "_#result('C' 'int')_" are all valid
+
+- `alias` - specifies both the SQL alias of the column and the value key in the DataRow. If omitted, "column" value is used.
+
+- `dataRowKey` - needed if SQL 'alias' is not appropriate as a DataRow key on the Cayenne side. One common case when this happens is when a DataRow retrieved from a query is mapped using joint prefetch keys (see below). In this case DataRow must use database path expressions for joint column keys, and their format is incompatible with most databases alias format.
+
+Usage:
+
+[source]
+----
+#result('NAME')
+#result('DATE_OF_BIRTH' 'java.util.Date')
+#result('DOB' 'java.util.Date' 'DATE_OF_BIRTH')
+#result('DOB' 'java.util.Date' '' 'artist.DATE_OF_BIRTH')
+#result('SALARY' 'float')
+----
+
+Full example:
+
+
+[source, SQL]
+----
+SELECT #result('ID' 'int'), #result('NAME' 'String'), #result('DATE_OF_BIRTH' 'java.util.Date') FROM ARTIST
+----
+
+====== Note
+
+For advanced features you may look at the xref:velocity[Apache Velocity extension]
+
+====== Mapping SQLTemplate Results
+
+Here we'll discuss how to convert the data selected via SQLTemplate to some useable format, compatible with other query results. It can either be very simple or very complex, depending on the structure of the SQL, JDBC driver nature and the desired result structure. This section presents various tips and tricks dealing with result mapping.
+
+By default SQLTemplate is expected to return a List of Persistent objects of its root type. This is the simple case:
+
+[source, Java]
+----
+SQLTemplate query = new SQLTemplate(Artist.class, "SELECT * FROM ARTIST");
+
+// List of Artists
+List<Artist> artists = context.performQuery(query);
+----
+
+Just like SelectQuery, SQLTemplate can fetch DataRows. In fact DataRows option is very useful with SQLTemplate, as the result type most often than not does not represent a Cayenne entity, but instead may be some aggregated report or any other data whose object structure is opaque to Cayenne:
+
+[source, Java]
+----
+String sql = "SELECT t0.NAME, COUNT(1) FROM ARTIST t0 JOIN PAINTING t1 ON (t0.ID = t1.ARTIST_ID) "
+ + "GROUP BY t0.NAME ORDER BY COUNT(1)";
+SQLTemplate query = new SQLTemplate(Artist.class, sql);
+
+// ensure we are fetching DataRows
+query.setFetchingDataRows(true);
+
+// List of DataRow
+List<DataRow> rows = context.performQuery(query);
+----
+
+In the example above, even though the query root is Artist. the result is a list of artist names with painting counts (as mentioned before in such case "root" is only used to find the DB to fetch against, but has no bearning on the result). The DataRows here are the most appropriate and desired result type.
+
+In a more advanced case you may decide to fetch a list of scalars or a list of Object[] with each array entry being either an entity or a scalar. You probably won't be doing this too often and it requires quite a lot of work to setup, but if you want your SQLTemplate to return results similar to EJBQLQuery, it is doable using SQLResult as described below:
+
+[source, Java]
+----
+SQLTemplate query = new SQLTemplate(Painting.class, "SELECT ESTIMATED_PRICE P FROM PAINTING");
+
+// let Cayenne know that result is a scalar
+SQLResult resultDescriptor = new SQLResult();
+resultDescriptor.addColumnResult("P");
+query.setResult(resultDescriptor);
+
+// List of BigDecimals
+List<BigDecimal> prices = context.performQuery(query);
+----
+
+[source, Java]
+----
+SQLTemplate query = new SQLTemplate(Artist.class, "SELECT t0.ID, t0.NAME, t0.DATE_OF_BIRTH, COUNT(t1.PAINTING_ID) C " +
+ "FROM ARTIST t0 LEFT JOIN PAINTING t1 ON (t0.ID = t1.ARTIST_ID) " +
+ "GROUP BY t0.ID, t0.NAME, t0.DATE_OF_BIRTH");
+
+// let Cayenne know that result is a mix of Artist objects and the count of their paintings
+EntityResult artistResult = new EntityResult(Artist.class);
+artistResult.addDbField(Artist.ID_PK_COLUMN, "ARTIST_ID");
+artistResult.addObjectField(Artist.NAME_PROPERTY, "NAME");
+artistResult.addObjectField(Artist.DATE_OF_BIRTH_PROPERTY, "DATE_OF_BIRTH");
+
+SQLResult resultDescriptor = new SQLResult();
+resultDescriptor.addEntityResult(artistResult);
+resultDescriptor.addColumnResult("C");
+query.setResult(resultDescriptor);
+
+// List of Object[]
+List<Object[]> data = context.performQuery(query);
+----
+
+Another trick related to mapping result sets is making Cayenne recognize prefetched entities in the result set. This emulates "joint" prefetching of SelectQuery, and is achieved by special column naming. Columns belonging to the "root" entity of the query should use unqualified names corresponding to the root DbEntity columns. For each related entity column names must be prefixed with relationship name and a dot (e.g. "toArtist.ID"). Column naming can be controlled with "#result" directive:
+
+[source, Java]
+----
+String sql = "SELECT distinct "
+ + "#result('t1.ESTIMATED_PRICE' 'BigDecimal' '' 'paintings.ESTIMATED_PRICE'), "
+ + "#result('t1.PAINTING_TITLE' 'String' '' 'paintings.PAINTING_TITLE'), "
+ + "#result('t1.GALLERY_ID' 'int' '' 'paintings.GALLERY_ID'), "
+ + "#result('t1.ID' 'int' '' 'paintings.ID'), "
+ + "#result('NAME' 'String'), "
+ + "#result('DATE_OF_BIRTH' 'java.util.Date'), "
+ + "#result('t0.ID' 'int' '' 'ID') "
+ + "FROM ARTIST t0, PAINTING t1 "
+ + "WHERE t0.ID = t1.ARTIST_ID";
+
+SQLTemplate q = new SQLTemplate(Artist.class, sql);
+q.addPrefetch(Artist.PAINTINGS_PROPERTY)
+List<Artist> objects = context.performQuery(query);
+----
+
+And the final tip deals with capitalization of the DataRow keys. Queries like `"SELECT * FROM..."` and even `"SELECT COLUMN1, COLUMN2, ... FROM ..."` can sometimes result in Cayenne exceptions on attempts to convert fetched DataRows to objects. Essentially any query that is not using a `#result` directive to describe the result set is prone to this problem, as different databases may produce different capitalization of the java.sql.ResultSet columns.
+
+The most universal way to address this issue is to describe each column explicitly in the SQLTemplate via `#result`, e.g.: `"SELECT #result('column1'), #result('column2'), .."`. However this quickly becomes impractical for tables with lots of columns. For such cases Cayenne provides a shortcut based on the fact that an ORM mapping usually follows some naming convention for the column names. Simply put, for case-insensitive databases developers normally use either all lowercase or all uppercase column names. Here is the API that takes advantage of that user knowledge and forces Cayenne to follow a given naming convention for the DataRow keys (this is also available as a dropdown in the Modeler):
+
+[source, Java]
+----
+SQLTemplate query = new SQLTemplate("SELECT * FROM ARTIST");
+query.setColumnNamesCapitalization(CapsStrategy.LOWER);
+List objects = context.performQuery(query);
+----
+
+or
+
+[source, Java]
+----
+SQLTemplate query = new SQLTemplate("SELECT * FROM ARTIST");
+query.setColumnNamesCapitalization(CapsStrategy.UPPER);
+List objects = context.performQuery(query);
+----
+
+None of this affects the generated SQL, but the resulting DataRows are using correct capitalization. Note that you probably shouldn't bother with this unless you are getting CayenneRuntimeExceptions when fetching with SQLTemplate.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/starting.adoc
----------------------------------------------------------------------
diff --git a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/starting.adoc b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/starting.adoc
new file mode 100644
index 0000000..b556536
--- /dev/null
+++ b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/starting.adoc
@@ -0,0 +1,118 @@
+// 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.
+
+=== Starting Cayenne
+
+==== Starting and Stopping ServerRuntime
+
+In runtime Cayenne is accessed via `org.apache.cayenne.configuration.server.ServerRuntime`. ServerRuntime is created by calling a convenient builder:
+
+[source, java]
+----
+ServerRuntime runtime = ServerRuntime.builder()
+ .addConfig("com/example/cayenne-project.xml")
+ .build();
+----
+
+The parameter you pass to the builder is a location of the main project file. Location is a '/'-separated path (same path separator is used on UNIX and Windows) that is resolved relative to the application classpath. The project file can be placed in the root package or in a subpackage (e.g. in the code above it is in "com/example" subpackage).
+
+ServerRuntime encapsulates a single Cayenne stack. Most applications will just have one ServerRuntime using it to create as many ObjectContexts as needed, access the Dependency Injection (DI) container and work with other Cayenne features. Internally ServerRuntime is just a thin wrapper around the DI container. Detailed features of the container are discussed in xref:customize["Customizing Cayenne Runtime"] chapter. Here we'll just show an example of how an application might turn on external transactions:
+
+[source, java]
+----
+Module extensions = binder ->
+ ServerModule.contributeProperties(binder).put(Constants.SERVER_EXTERNAL_TX_PROPERTY, "true");
+ServerRuntime runtime = ServerRuntime.builder()
+ .addConfig("com/example/cayenne-project.xml")
+ .addModule(extensions)
+ .build();
+----
+
+It is a good idea to shut down the runtime when it is no longer needed, usually before the application itself is shutdown:
+
+[source, java]
+----
+runtime.shutdown();
+----
+
+
+When a runtime object has the same scope as the application, this may not be always necessary, however in some cases it is essential, and is generally considered a good practice. E.g. in a web container hot redeploy of a webapp will cause resource leaks and eventual OutOfMemoryError if the application fails to shutdown CayenneRuntime.
+
+==== Merging Multiple Projects
+
+ServerRuntime requires at least one mapping project to run. But it can also take multiple projects and merge them together in a single configuration. This way different parts of a database can be mapped independently from each other (even by different software providers), and combined in runtime when assembling an application. Doing it is as easy as passing multiple project locations to ServerRuntime builder:
+
+[source, java]
+----
+ServerRuntime runtime = ServerRuntime.builder()
+ .addConfig("com/example/cayenne-project.xml")
+ .addConfig("org/foo/cayenne-library1.xml")
+ .addConfig("org/foo/cayenne-library2.xml")
+ .build();
+----
+
+When the projects are merged, the following rules are applied:
+
+
+- The order of projects matters during merge. If there are two conflicting metadata objects belonging to two projects, an object from the last project takes precedence over the object from the first one. This makes possible to override pieces of metadata. This is also similar to how DI modules are merged in Cayenne.
+
+- Runtime DataDomain name is set to the name of the last project in the list.
+
+- Runtime DataDomain properties are the same as the properties of the last project in the list. I.e. properties are not merged to avoid invalid combinations and unexpected runtime behavior.
+
+- If there are two or more DataMaps with the same name, only one DataMap is used in the merged project, the rest are discarded. Same precedence rules apply - DataMap from the project with the highest index in the project list overrides all other DataMaps with the same name.
+
+- If there are two or more DataNodes with the same name, only one DataNodes is used in the merged project, the rest are discarded. DataNode coming from project with the highest index in the project list is chosen per precedence rule above.
+
+- There is a notion of "default" DataNode. After the merge if any DataMaps are not explicitly linked to DataNodes, their queries will be executed via a default DataNode. This makes it possible to build mapping "libraries" that are only associated with a specific database in runtime. If there's only one DataNode in the merged project, it will be automatically chosen as default. A possible way to explicitly designate a specific node as default is to override `DataDomainProvider.createAndInitDataDomain()`.
+
+==== Web Applications
+
+Web applications can use a variety of mechanisms to configure and start the "services" they need, Cayenne being one of such services. Configuration can be done within standard Servlet specification objects like Servlets, Filters, or ServletContextListeners, or can use Spring, JEE CDI, etc. This is a user's architectural choice and Cayenne is agnostic to it and will happily work in any environment. As described above, all that is needed is to create an instance of ServerRuntime somewhere and provide the application code with means to access it. And shut it down when the application ends to avoid container leaks.
+
+Still Cayenne includes a piece of web app configuration code that can assist in quickly setting up simple Cayenne-enabled web applications. We are talking about CayenneFilter. It is declared in web.xml:
+
+[source, XML]
+----
+<web-app>
+ ...
+ <filter>
+ <filter-name>cayenne-project</filter-name>
+ <filter-class>org.apache.cayenne.configuration.web.CayenneFilter</filter-class>
+ </filter>
+ <filter-mapping>
+ <filter-name>cayenne-project</filter-name>
+ <url-pattern>/*</url-pattern>
+ </filter-mapping>
+ ...
+ </web-app>
+----
+
+
+When started by the web container, it creates a instance of ServerRuntime and stores it in the ServletContext. Note that the name of Cayenne XML project file is derived from the "filter-name". In the example above CayenneFilter will look for an XML file "cayenne-project.xml". This can be overridden with "configuration-location" init parameter.
+
+When the application runs, all HTTP requests matching the filter url-pattern will have access to a session-scoped ObjectContext like this:
+
+[source, java]
+----
+ ObjectContext context = BaseContext.getThreadObjectContext();
+----
+
+Of course the ObjectContext scope, and other behavior of the Cayenne runtime can be customized via dependency injection. For this another filter init parameter called "extra-modules" is used. "extra-modules" is a comma or space-separated list of class names, with each class implementing Module interface. These optional custom modules are loaded after the the standard ones, which allows users to override all standard definitions.
+
+For those interested in the DI container contents of the runtime created by CayenneFilter, it is the same ServerRuntime as would've been created by other means, but with an extra `org.apache.cayenne.configuration.web.WebModule` module that provides `org.apache.cayenne.configuration.web.RequestHandler` service. This is the service to override in the custom modules if you need to provide a different ObjectContext scope, etc.
+
+
+NOTE: You should not think of CayenneFilter as the only way to start and use Cayenne in a web application. In fact CayenneFilter is entirely optional. Use it if you don't have any special design for application service management. If you do, simply integrate Cayenne into that design.
+
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/tuning.adoc
----------------------------------------------------------------------
diff --git a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/tuning.adoc b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/tuning.adoc
new file mode 100644
index 0000000..aa90e0e
--- /dev/null
+++ b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/tuning.adoc
@@ -0,0 +1,354 @@
+// 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.
+
+=== Performance Tuning
+
+==== Prefetching
+
+Prefetching is a technique that allows to bring back in one query not only the queried objects, but also objects related to them. In other words it is a controlled eager relationship resolving mechanism. Prefetching is discussed in the "Performance Tuning" chapter, as it is a powerful performance optimization method. However another common application of prefetching is to refresh stale object relationships, so more generally it can be viewed as a technique for managing subsets of the object graph.
+
+Prefetching example:
+
+[source, Java]
+----
+ObjectSelect<Artist> query = ObjectSelect.query(Artist.class);
+
+// instructs Cayenne to prefetch one of Artist's relationships
+query.prefetch(Artist.PAINTINGS.disjoint());
+
+// the above line is equivalent to the following:
+// query.prefetch("paintings", PrefetchTreeNode.DISJOINT_PREFETCH_SEMANTICS);
+
+// query is expecuted as usual, but the resulting Artists will have
+// their paintings "inflated"
+List<Artist> artists = query.select(context);
+----
+
+All types of relationships can be preftetched - to-one, to-many, flattened. A prefetch can span multiple relationships:
+
+[source, Java]
+----
+query.prefetch(Artist.PAINTINGS.dot(Painting.GALLERY).disjoint());
+----
+
+A query can have multiple prefetches:
+
+[source, Java]
+----
+query.prefetch(Artist.PAINTINGS.disjoint());
+query.prefetch(Artist.PAINTINGS.dot(Painting.GALLERY).disjoint());
+----
+
+If a query is fetching DataRows, all "disjoint" prefetches are ignored, only "joint" prefetches are executed (see prefetching semantics discussion below for what disjoint and joint prefetches mean).
+
+===== Prefetching Semantics
+
+Prefetching semantics defines a strategy to prefetch relationships. Depending on it, Cayenne would generate different types of queries. The end result is the same - query root objects with related objects fully resolved. However semantics can affect preformance, in some cases significantly. There are 3 types of prefetch semantics, all defined as constants in `org.apache.cayenne.query.PrefetchTreeNode`:
+
+[source]
+----
+PrefetchTreeNode.JOINT_PREFETCH_SEMANTICS
+PrefetchTreeNode.DISJOINT_PREFETCH_SEMANTICS
+PrefetchTreeNode.DISJOINT_BY_ID_PREFETCH_SEMANTICS
+----
+
+There's no limitation on mixing different types of semantics in the same query. Each prefetch can have its own semantics. `SelectQuery` uses `DISJOINT_PREFETCH_SEMANTICS` by default. `ObjectSelect` requires explicit semantics as we've seen above. `SQLTemplate_ and _ProcedureQuery` are both using `JOINT_PREFETCH_SEMANTICS` and it can not be changed due to the nature of those two queries.
+
+===== Disjoint Prefetching Semantics
+
+This semantics results in Cayenne generatiing one SQL statement for the main objects, and a separate statement for each prefetch path (hence "disjoint" - related objects are not fetched with the main query). Each additional SQL statement uses a qualifier of the main query plus a set of joins traversing the preftech path between the main and related entity.
+
+This strategy has an advantage of efficient JVM memory use, and faster overall result processing by Cayenne, but it requires (1+N) SQL statements to be executed, where N is the number of prefetched relationships.
+
+===== Disjoint-by-ID Prefetching Semantics
+
+This is a variation of disjoint prefetch where related objects are matched against a set of IDs derived from the fetched main objects (or intermediate objects in a multi-step prefetch). Cayenne limits the size of the generated WHERE clause, as most DBs can't parse arbitrary large SQL. So prefetch queries are broken into smaller queries. The size of is controlled by the DI property Constants.SERVER_MAX_ID_QUALIFIER_SIZE_PROPERTY (the default number of conditions in the generated WHERE clause is 10000). Cayenne will generate (1 + N * M) SQL statements for each query using disjoint-by-ID prefetches, where N is the number of relationships to prefetch, and M is the number of queries for a given prefetch that is dependent on the number of objects in the result (ideally M = 1).
+
+The advantage of this type of prefetch is that matching database rows by ID may be much faster than matching the qualifier of the original query. Moreover this is *the only type of prefetch* that can handle SelectQueries with *fetch* limit. Both joint and regular disjoint prefetches may produce invalid results or generate inefficient fetch-the-entire table SQL when fetch limit is in effect.
+
+The disadvantage is that query SQL can get unwieldy for large result sets, as each object will have to have its own condition in the WHERE clause of the generated SQL.
+
+===== Joint Prefetching Semantics
+
+Joint semantics results in a single SQL statement for root objects and any number of jointly prefetched paths. Cayenne processes in memory a cartesian product of the entities involved, converting it to an object tree. It uses OUTER joins to connect prefetched entities.
+
+Joint is the most efficient prefetch type of the three as far as generated SQL goes. There's always just 1 SQL query generated. Its downsides are the potentially increased amount of data that needs to get across the network between the application server and the database, and more data processing that needs to be done on the Cayenne side.
+
+===== Similar Behaviours Using EJBQL
+
+It is possible to achieve similar behaviours with xref:ejbql[EJBQLQuery] queries by employing the "FETCH" keyword.
+
+[source, SQL]
+----
+SELECT a FROM Artist a LEFT JOIN FETCH a.paintings
+----
+
+In this case, the Paintings that exist for the Artist will be obtained at the same time as the Artists are fetched. Refer to third-party query language documentation for further detail on this mechanism.
+
+==== Data Rows
+
+Converting result set data to Persistent objects and registering these objects in the ObjectContext can be an expensive operation compareable to the time spent running the query (and frequently exceeding it). Internally Cayenne builds the result as a list of DataRows, that are later converted to objects. Skipping the last step and using data in the form of DataRows can significantly increase performance.
+
+DataRow is a simply a map of values keyed by their DB column name. It is a ubiqutous representation of DB data used internally by Cayenne. And it can be quite usable as is in the application in many cases. So performance sensitive selects should consider DataRows - it saves memory and CPU cycles. All selecting queries support DataRows option, e.g.:
+
+[source, Java]
+----
+ObjectSelect<DataRow> query = ObjectSelect.dataRowQuery(Artist.class);
+
+List<DataRow> rows = query.select(context);
+----
+
+[source, Java]
+----
+SQLSelect<DataRow> query = SQLSelect.dataRowQuery("SELECT * FROM ARTIST");
+List<DataRow> rows = query.select(context);
+----
+
+Individual DataRows may be converted to Persistent objects as needed. So e.g. you may implement some in-memory filtering, only converting a subset of fetched objects:
+
+
+[source, Java]
+----
+// you need to cast ObjectContext to DataContext to get access to 'objectFromDataRow'
+DataContext dataContext = (DataContext) context;
+
+for(DataRow row : rows) {
+ if(row.get("DATE_OF_BIRTH") != null) {
+ Artist artist = dataContext.objectFromDataRow(Artist.class, row);
+ // do something with Artist...
+ ...
+ }
+}
+----
+
+==== Specific Attributes and Relationships with EJBQL
+
+It is possible to fetch specific attributes and relationships from a model using xref:ejbqlquery[EJBQLQuery]. The following example would return a java.util.List of String objects;
+
+[source, SQL]
+----
+SELECT a.name FROM Artist a
+----
+
+The following will yield a java.util.List containing Object[] instances, each of which would contain the name followed by the dateOfBirth value.
+
+[source, SQL]
+----
+SELECT a.name, a.dateOfBirth FROM Artist a
+----
+
+Refer to third-party query language documentation for further detail on this mechanism.
+
+==== Iterated Queries
+
+While contemporary hardware may easily allow applications to fetch hundreds of thousands or even millions of objects into memory, it doesn't mean this is always a good idea to do so. You can optimize processing of very large result sets with two techniques discussed in this and the following chapter - iterated and paginated queries.
+
+Iterated query is not actually a special query. Any selecting query can be executed in iterated mode by an ObjectContext. ObjectContext creates an object called `ResultIterator` that is backed by an open ResultSet. Iterator provides constant memory performance for arbitrarily large ResultSets. This is true at least on the Cayenne end, as JDBC driver may still decide to bring the entire ResultSet into the JVM memory.
+
+Data is read from ResultIterator one row/object at a time until it is exhausted. There are two styles of accessing ResultIterator - direct access which requires explicit closing to avoid JDBC resources leak, or a callback that lets Cayenne handle resource management. In both cases iteration can be performed using "for" loop, as ResultIterator is "Iterable".
+
+Direct access. Here common sense tells us that ResultIterators instances should be processed and closed as soon as possible to release the DB connection. E.g. storing open iterators between HTTP requests for unpredictable length of time would quickly exhaust the connection pool.
+
+[source, Java]
+----
+try(ResultIterator<Artist> it = ObjectSelect.query(Artist.class).iterator(context)) {
+ for(Artist a : it) {
+ // do something with the object...
+ ...
+ }
+}
+----
+
+Same thing with a callback:
+
+[source, Java]
+----
+ObjectSelect.query(Artist.class).iterate(context, (Artist a) -> {
+ // do something with the object...
+ ...
+});
+----
+
+Another example is a batch iterator that allows to process more than one object in each iteration. This is a common scenario in various data processing jobs - read a batch of objects, process them, commit the results, and then repeat. This allows to further optimize processing (e.g. by avoiding frequent commits).
+
+[source, Java]
+----
+try(ResultBatchIterator<Artist> it = ObjectSelect.query(Artist.class).batchIterator(context, 100)) {
+ for(List<Artist> list : it) {
+ // do something with each list
+ ...
+ // possibly commit your changes
+ context.commitChanges();
+ }
+}
+----
+
+==== Paginated Queries
+
+Enabling query pagination allows to load very large result sets in a Java app with very little memory overhead (much smaller than even the DataRows option discussed above). Moreover it is completely transparent to the application - a user gets what appears to be a list of Persistent objects - there's no iterator to close or DataRows to convert to objects:
+
+[source, Java]
+----
+// the fact that result is paginated is transparent
+List<Artist> artists =
+ ObjectSelect.query(Artist.class).pageSize(50).select(context);
+----
+
+Having said that, DataRows option can be combined with pagination, providing the best of both worlds:
+
+
+[source, Java]
+----
+List<DataRow> rows =
+ ObjectSelect.dataRowQuery(Artist.class).pageSize(50).select(context);
+----
+
+The way pagination works internally, it first fetches a list of IDs for the root entity of the query. This is very fast and initially takes very little memory. Then when an object is requested at an arbitrary index in the list, this object and adjacent objects (a "page" of objects that is determined by the query pageSize parameter) are fetched together by ID. Subsequent requests to the objects of this "page" are served from memory.
+
+An obvious limitation of pagination is that if you eventually access all objects in the list, the memory use will end up being the same as with no pagination. However it is still a very useful approach. With some lists (e.g. multi-page search results) only a few top objects are normally accessed. At the same time pagination allows to estimate the full list size without fetching all the objects. And again - it is completely transparent and looks like a normal query.
+
+[[caching]]
+==== Caching and Fresh Data
+
+===== Object Caching
+
+===== Query Result Caching
+
+Cayenne supports mostly transparent caching of the query results. There are two levels of the cache: local (i.e. results cached by the ObjectContext) and shared (i.e. the results cached at the stack level and shared between all contexts). Local cache is much faster then the shared one, but is limited to a single context. It is often used with a shared read-only ObjectContext.
+
+To take advantage of query result caching, the first step is to mark your queries appropriately. Here is an example for ObjectSelect query. Other types of queries have similar API:
+
+[source, Java]
+----
+ObjectSelect.query(Artist.class).localCache("artists");
+----
+
+This tells Cayenne that the query created here would like to use local cache of the context it is executed against. A vararg parameter to `localCache()` (or `sharedCache()`) method contains so called "cache groups". Those are arbitrary names that allow to categorize queries for the purpose of setting cache policies or explicit invalidation of the cache. More on that below.
+
+The above API is enough for the caching to work, but by default your cache is an unmanaged LRU map. You can't control its size, expiration policies, etc. For the managed cache, you will need to explicitly use one of the more advanced cache providers. One such provider available in Cayenne is a provider for http://www.ehcache.org[EhCache]. It can be enabled on ServerRuntime startup in a custom Module:
+
+[source, Java]
+----
+ServerRuntimeBuilder
+ .builder()
+ .addModule((binder) ->
+ binder.bind(QueryCache.class).to(EhCacheQueryCache.class)
+ )
+ .build();
+----
+
+By default EhCache reads a file called "ehcache.xml" located on classpath. You can put your cache configuration in that file. E.g.:
+
+[source, XML]
+----
+<ehcache xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:noNamespaceSchemaLocation="ehcache.xsd" updateCheck="false"
+ monitoring="off" dynamicConfig="false">
+
+ <defaultCache maxEntriesLocalHeap="1000" eternal="false"
+ overflowToDisk="false" timeToIdleSeconds="3600" timeToLiveSeconds="3600">
+ </defaultCache>
+
+ <cache name="artists" timeToLiveSeconds="20" maxEntriesLocalHeap="100" />
+</ehcache>
+----
+
+The example shows how to configure default cache settings ("defaultCache") as well as settings for a named cache group ("artists"). For many other things you can put in "ehcache.xml" refer to EhCache docs.
+
+Often "passive" cache expiration policies similar to shown above are not sufficient, and the users want real-time cache invalidation when the data changes. So in addition to those policies, the app can invalidate individual cache groups explicitly with `RefreshQuery`:
+
+[source, Java]
+----
+RefreshQuery refresh = new RefreshQuery("artist");
+context.performGenericQuery(refresh);
+----
+
+The above can be used e.g. to build UI for manual cache invalidation. It is also possible to automate cache refresh when certain entities are committed. This requires including `cayenne-lifecycle.jar` deoendency. From that library you will need two things: `@CacheGroups` annotation to mark entities that generate cache invalidation events and `CacheInvalidationFilter` that catches the updates to the annotated objects and generates appropriate invalidation events:
+
+[source, Java]
+----
+// configure filter on startup
+ServerRuntimeBuilder
+ .builder()
+ .addModule((binder) ->
+ binder.bindList(Constants.SERVER_DOMAIN_FILTERS_LIST).add(CacheInvalidationFilter.class)
+ )
+ .build();
+----
+
+
+Now you can associate entities with cache groups, so that commits to those entities would atomatically invalidate the groups:
+
+[source, Java]
+----
+@CacheGroups("artists")
+public class Artist extends _Artist {
+}
+----
+
+Finally you may cluster cache group events. They are very small and can be efficiently sent over the wire to other JVMs running Cayenne. An example of Cayenne setup with event clustering is https://github.com/andrus/wowodc13/tree/master/services/src/main/java/demo/services/cayenne[available on GitHub].
+
+
+==== Turning off Synchronization of ObjectContexts
+
+By default when a single ObjectContext commits its changes, all other contexts in the same runtime receive an event that contains all the committed changes. This allows them to update their cached object state to match the latest committed data. There are however many problems with this ostensibly helpful feature. In short - it works well in environments with few contexts and in unclustered scenarios, such as single user desktop applications, or simple webapps with only a few users. More specifically:
+
+- The performance of synchronization is (probably worse than) O(N) where N is the number of peer ObjectContexts in the system. In a typical webapp N can be quite large. Besides for any given context, due to locking on synchronization, context own performance will depend not only on the queries that it runs, but also on external events that it does not control. This is unacceptable in most situations.
+
+- Commit events are untargeted - even contexts that do not hold a given updated object will receive the full event that they will have to process.
+
+- Clustering between JVMs doesn't scale - apps with large volumes of commits will quickly saturate the network with events, while most of those will be thrown away on the receiving end as mentioned above.
+
+- Some contexts may not want to be refreshed. A refresh in the middle of an operation may lead to unpredictable results.
+
+- Synchronization will interfere with optimistic locking.
+
+So we've made a good case for disabling synchronization in most webapps. To do that, set to "false" the following DI property - `Constants.SERVER_CONTEXTS_SYNC_PROPERTY`, using one of the standard Cayenne DI approaches. E.g. from command line:
+
+----
+$ java -Dcayenne.server.contexts_sync_strategy=false
+----
+
+Or by changing the standard properties Map in a custom extensions module:
+
+[source, Java]
+----
+public class MyModule implements Module {
+
+ @Override
+ public void configure(Binder binder) {
+ binder.bindMap(Constants.PROPERTIES_MAP).put(Constants.SERVER_CONTEXTS_SYNC_PROPERTY, "false");
+ }
+}
+----
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part3.adoc
----------------------------------------------------------------------
diff --git a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part3.adoc b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part3.adoc
new file mode 100644
index 0000000..5e211d1
--- /dev/null
+++ b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part3.adoc
@@ -0,0 +1,28 @@
+// 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.
+
+== Cayenne Framework - Remote Object Persistence
+
+include::part3/rop.adoc[]
+
+include::part3/ropSetup.adoc[]
+
+include::part3/serverImpl.adoc[]
+
+include::part3/clientImpl.adoc[]
+
+include::part3/ropDeployment.adoc[]
+
+include::part3/limitations.adoc[]
+
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part3/clientImpl.adoc
----------------------------------------------------------------------
diff --git a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part3/clientImpl.adoc b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part3/clientImpl.adoc
new file mode 100644
index 0000000..027a22e
--- /dev/null
+++ b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part3/clientImpl.adoc
@@ -0,0 +1,16 @@
+// 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.
+
+=== Implementing ROP Client
+
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part3/limitations.adoc
----------------------------------------------------------------------
diff --git a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part3/limitations.adoc b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part3/limitations.adoc
new file mode 100644
index 0000000..f378cdb
--- /dev/null
+++ b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part3/limitations.adoc
@@ -0,0 +1,18 @@
+// 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.
+
+=== Current Limitations
+
+
+
[12/13] cayenne git commit: CAY-2371 Switch documentation from
Docbook to Asciidoctor format
Posted by nt...@apache.org.
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/customize.adoc
----------------------------------------------------------------------
diff --git a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/customize.adoc b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/customize.adoc
new file mode 100644
index 0000000..42504d2
--- /dev/null
+++ b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/customize.adoc
@@ -0,0 +1,473 @@
+// 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.
+
+[[customize]]
+=== Customizing Cayenne Runtime
+
+==== Dependency Injection Container
+
+Cayenne runtime is built around a small powerful dependency injection (DI) container. Just like other popular DI technologies, such as Spring or Guice, Cayenne DI container manages sets of interdependent objects and allows users to configure them. These objects are regular Java objects. We are calling them "services" in this document to distinguish from all other objects that are not configured in the container and are not managed. DI container is responsible for service instantiation, injecting correct dependencies, maintaining service instances scope, and dispatching scope events to services.
+
+The services are configured in special Java classes called "modules". Each module defines binding of service interfaces to implementation instances, implementation types or providers of implementation instances. There are no XML configuration files, and all the bindings are type-safe. The container supports injection into instance variables and constructor parameters based on the @Inject annotation. This mechanism is very close to Google Guice.
+
+The discussion later in this chapter demonstrates a standalone DI container. But keep in mind that Cayenne already has a built-in Injector, and a set of default modules. A Cayenne user would normally only use the API below to write custom extension modules that will be loaded in that existing container when creating ServerRuntime. See "Starting and Stopping ServerRuntime" chapter for an example of passing an extension module to Cayenne.
+
+Cayenne DI probably has ~80% of the features expected in a DI container and has no dependency on the rest of Cayenne, so in theory can be used as an application-wide DI engine. But it's primary purpose is still to serve Cayenne. Hence there are no plans to expand it beyond Cayenne needs. It is an ideal "embedded" DI that does not interfere with Spring, Guice or any other such framework present elsewhere in the application.
+
+===== DI Bindings API
+
+To have a working DI container, we need three things: service interfaces and classes, a module that describes service bindings, a container that loads the module, and resolves the depedencies. Let's start with service interfaces and classes:
+
+[source, Java]
+----
+public interface Service1 {
+ public String getString();
+}
+----
+
+[source, Java]
+----
+public interface Service2 {
+ public int getInt();
+}
+----
+
+A service implementation using instance variable injection:
+
+[source, Java]
+----
+public class Service1Impl implements Service1 {
+ @Inject
+ private Service2 service2;
+
+ public String getString() {
+ return service2.getInt() + "_Service1Impl";
+ }
+}
+----
+
+Same thing, but using constructor injection:
+
+[source, Java]
+----
+public class Service1Impl implements Service1 {
+
+ private Service2 service2;
+
+ public Service1Impl(@Inject Service2 service2) {
+ this.service2 = service2;
+ }
+
+ public String getString() {
+ return service2.getInt() + "_Service1Impl";
+ }
+}
+----
+
+[source, Java]
+----
+public class Service2Impl implements Service2 {
+ private int i;
+
+ public int getInt() {
+ return i++;
+ }
+}
+----
+
+Now let's create a module implementing `org.apache.cayenne.tutorial.di.Module` interface that will contain DI configuration. A module binds service objects to keys that are reference. Binder provided by container implements fluent API to connect the key to implementation, and to configure various binding options (the options, such as scope, are demonstrated later in this chapter). The simplest form of a key is a Java Class object representing service interface. Here is a module that binds Service1 and Service2 to corresponding default implementations:
+
+[source, Java]
+----
+public class Module1 implements Module {
+
+ public void configure(Binder binder) {
+ binder.bind(Service1.class).to(Service1Impl.class);
+ binder.bind(Service2.class).to(Service2Impl.class);
+ }
+}
+----
+
+Once we have at least one module, we can create a DI container. `org.apache.cayenne.di.Injector` is the container class in Cayenne:
+
+[source, Java]
+----
+Injector injector = DIBootstrap.createInjector(new Module1());
+----
+
+Now that we have created the container, we can obtain services from it and call their methods:
+
+[source, Java]
+----
+Service1 s1 = injector.getInstance(Service1.class);
+for (int i = 0; i < 5; i++) {
+ System.out.println("S1 String: " + s1.getString());
+}
+----
+
+This outputs the following lines, demonstrating that s1 was Service1Impl and Service2 injected into it was Service2Impl:
+
+----
+0_Service1Impl
+1_Service1Impl
+2_Service1Impl
+3_Service1Impl
+4_Service1Impl
+----
+
+There are more flavors of bindings:
+
+[source, Java]
+----
+// binding to instance - allowing user to create and configure instance
+// inside the module class
+binder.bind(Service2.class).toInstance(new Service2Impl());
+
+// binding to provider - delegating instance creation to a special
+// provider class
+binder.bind(Service1.class).toProvider(Service1Provider.class);
+
+// binding to provider instance
+binder.bind(Service1.class).toProviderInstance(new Service1Provider());
+
+// multiple bindings of the same type using Key
+// injection can reference the key name in annotation:
+// @Inject("i1")
+// private Service2 service2;
+binder.bind(Key.get(Service2.class, "i1")).to(Service2Impl.class);
+binder.bind(Key.get(Service2.class, "i2")).to(Service2Impl.class);
+----
+
+
+Another types of confiuguration that can be bound in the container are lists and maps. They will be discussed in the following chapters.
+
+===== Service Lifecycle
+
+An important feature of the Cayenne DI container is instance scope. The default scope (implicitly used in all examples above) is "singleton", meaning that a binding would result in creation of only one service instance, that will be repeatedly returned from `Injector.getInstance(..)`, as well as injected into classes that declare it as a dependency.
+
+Singleton scope dispatches a "BeforeScopeEnd" event to interested services. This event occurs before the scope is shutdown, i.e. when `Injector.shutdown()` is called. Note that the built-in Cayenne injector is shutdown behind the scenes when `ServerRuntime.shutdown()` is invoked. Services may register as listeners for this event by annotating a no-argument method with `@BeforeScopeEnd` annotation. Such method should be implemented if a service needs to clean up some resources, stop threads, etc.
+
+Another useful scope is "no scope", meaning that every time a container is asked to provide a service instance for a given key, a new instance will be created and returned:
+
+[source, Java]
+----
+binder.bind(Service2.class).to(Service2Impl.class).withoutScope();
+----
+
+Users can also create their own scopes, e.g. a web application request scope or a session scope. Most often than not custom scopes can be created as instances of `org.apache.cayenne.di.spi.DefaultScope` with startup and shutdown managed by the application (e.g. singleton scope is a DefaultScope managed by the Injector) .
+
+===== Overriding Services
+
+Cayenne DI allows to override services already definied in the current module, or more commonly - some other module in the the same container. Actually there's no special API to override a service, you'd just bind the service key again with a new implementation or provider. The last binding for a key takes precedence. This means that the order of modules is important when configuring a container. The built-in Cayenne injector ensures that Cayenne standard modules are loaded first, followed by optional user extension modules. This way the application can override the standard services in Cayenne.
+
+==== Customization Strategies
+
+The previous section discussed how Cayenne DI works in general terms. Since Cayenne users will mostly be dealing with an existing Injector provided by ServerRuntime, it is important to understand how to build custom extensions to a preconfigured container. As shown in "Starting and Stopping ServerRuntime" chapter, custom extensions are done by writing an aplication DI module (or multiple modules) that configures service overrides. This section shows all the configuration possibilities in detail, including changing properties of the existing services, contributing services to standard service lists and maps, and overriding service implementations. All the code examples later in this section are assumed to be placed in an application module "configure" method:
+
+[source, Java]
+----
+public class MyExtensionsModule implements Module {
+ public void configure(Binder binder) {
+ // customizations go here...
+ }
+}
+----
+
+[source, Java]
+----
+Module extensions = new MyExtensionsModule();
+ServerRuntime runtime = ServerRuntime.builder()
+ .addConfig("com/example/cayenne-mydomain.xml")
+ .addModule(extensions)
+ .build();
+----
+
+===== Changing Properties of Existing Services
+
+Many built-in Cayenne services change their behavior based on a value of some environment property. A user may change Cayenne behavior without even knowing which services are responsible for it, but setting a specific value of a known property. Supported property names are listed in "Appendix A".
+
+There are two ways to set service properties. The most obvious one is to pass it to the JVM with -D flag on startup. E.g.
+
+----
+$ java -Dcayenne.server.contexts_sync_strategy=false ...
+----
+
+A second one is to contribute a property to `org.apache.cayenne.configuration.DefaultRuntimeProperties.properties` map (see the next section on how to do that). This map contains the default property values and can accept application-specific values, overrding the defaults.
+
+Note that if a property value is a name of a Java class, when this Java class is instantiated by Cayenne, the container performs injection of instance variables. So even the dynamically specified Java classes can use @Inject annotation to get a hold of other Cayenne services.
+
+If the same property is specified both in the command line and in the properties map, the command-line value takes precedence. The map value will be ignored. This way Cayenne runtime can be reconfigured during deployment.
+
+===== Contributing to Service Collections
+
+Cayenne can be extended by adding custom objects to named maps or lists bound in DI. We are calling these lists/maps "service collections". A service collection allows things like appending a custom strategy to a list of built-in strategies. E.g. an application that needs to install a custom DbAdapter for some database type may contribute an instance of custom DbAdapterDetector to a `org.apache.cayenne.configuration.server.DefaultDbAdapterFactory.detectors` list:
+
+[source, Java]
+----
+public class MyDbAdapterDetector implements DbAdapterDetector {
+ public DbAdapter createAdapter(DatabaseMetaData md) throws SQLException {
+ // check if we support this database and retun custom adapter
+ ...
+ }
+}
+----
+
+[source, Java]
+----
+// since build-in list for this key is a singleton, repeated
+// calls to 'bindList' will return the same instance
+binder.bindList(DefaultDbAdapterFactory.DETECTORS_LIST)
+ .add(MyDbAdapterDetector.class);
+----
+
+Maps are customized using a similar `"bindMap"` method.
+
+The names of built-in collections are listed in "Appendix B".
+
+===== Alternative Service Implementations
+
+As mentioned above, custom modules are loaded by ServerRuntime after the built-in modules. So it is easy to redefine a built-in service in Cayenne by rebinding desired implementations or providers. To do that, first we need to know what those services to redefine are. While we describe some of them in the following sections, the best way to get a full list is to check the source code of the Cayenne version you are using and namely look in `org.apache.cayenne.configuration.server.ServerModule` - the main built-in module in Cayenne.
+
+Now an example of overriding `QueryCache` service. The default implementation of this service is provided by `MapQueryCacheProvider`. But if we want to use `EhCacheQueryCache` (a Cayenne wrapper for the EhCache framework), we can define it like this:
+
+[source, Java]
+----
+binder.bind(QueryCache.class).to(EhCacheQueryCache.class);
+----
+
+==== Using custom data types
+
+===== Value object type
+
+`ValueObjectType` is a new and lightweight alternative to the Extended Types API described in the following section. In most cases is should be preferred as is it easier to understand and use. Currently only one case is known when `ExtendedType` should be used: when your value object can be mapped on different JDBC types.
+
+In order to use your custom data type you should implement `ValueObjectType` describing it in terms of some type already known to Cayenne (e.g. backed by system or user ExtendedType). Let's assume we want to support some data type called `Money`:
+
+[source, Java]
+----
+public class Money {
+ private BigDecimal value;
+
+ public Money(BigDecimal value) {
+ this.value = value;
+ }
+
+ public BigDecimal getValue() {
+ return value;
+ }
+
+ // .. some other business logic ..
+}
+----
+
+Here is how `ValueObjectType` that will allow to store our `Money` class as `BigDecimal` can be implemented:
+
+[source, Java]
+----
+public class MoneyValueObjectType implements ValueObjectType<Money, BigDecimal> {
+
+ @Override
+ public Class<BigDecimal> getTargetType() {
+ return BigDecimal.class;
+ }
+
+ @Override
+ public Class<Money> getValueType() {
+ return Money.class;
+ }
+
+ @Override
+ public Money toJavaObject(BigDecimal value) {
+ return new Money(value);
+ }
+
+ @Override
+ public BigDecimal fromJavaObject(Money object) {
+ return object.getValue();
+ }
+
+ @Override
+ public String toCacheKey(Money object) {
+ return object.getValue().toString();
+ }
+}
+----
+
+Last step is to register this new type in `ServerRuntime`:
+
+[source, Java]
+----
+ServerRuntime runtime = ServerRuntime.builder()
+ .addConfig("cayenne-project.xml")
+ .addModule(binder -> ServerModule.contributeValueObjectTypes(binder).add(MoneyValueObjectType.class))
+ .build();
+----
+
+More examples of implementation you can find in https://github.com/apache/cayenne/tree/master/cayenne-joda[cayenne-joda module].
+
+===== Extended Types
+
+JDBC specification defines a set of "standard" database column types (defined in java.sql.Types class) and a very specific mapping of these types to Java Object Types, such as java.lang.String, java.math.BigDecimal, etc. Sometimes there is a need to use a custom Java type not known to JDBC driver and Cayenne allows to configure it. For this Cayenne needs to know how to instantiate this type from a database "primitive" value, and conversely, how to transform an object of the custom type to a JDBC-compatible object.
+
+====== Supporting Non-Standard Types
+
+For supporting non-standard type you should define it via an interface `org.apache.cayenne.access.types.ExtendedType`. An implementation must provide `ExtendedType.getClassName()` method that returns a fully qualified Java class name for the supported custom type, and a number of methods that convert data between JDBC and custom type. The following example demonstrates how to add a custom DoubleArrayType to store `java.lang.Double[]` as a custom string in a database:
+
+[source, Java]
+----
+/**
+* Defines methods to read Java objects from JDBC ResultSets and write as parameters of
+* PreparedStatements.
+*/
+public class DoubleArrayType implements ExtendedType {
+
+ private final String SEPARATOR = ",";
+
+ /**
+ * Returns a full name of Java class that this ExtendedType supports.
+ */
+ @Override
+ public String getClassName() {
+ return Double[].class.getCanonicalName();
+ }
+
+ /**
+ * Initializes a single parameter of a PreparedStatement with object value.
+ */
+ @Override
+ public void setJdbcObject(PreparedStatement statement, Object value,
+ int pos, int type, int scale) throws Exception {
+
+ String str = StringUtils.join((Double[]) value, SEPARATOR);
+ statement.setString(pos, str);
+ }
+
+
+ /**
+ * Reads an object from JDBC ResultSet column, converting it to class returned by
+ * 'getClassName' method.
+ *
+ * @throws Exception if read error occurred, or an object can't be converted to a
+ * target Java class.
+ */
+ @Override
+ public Object materializeObject(ResultSet rs, int index, int type) throws Exception {
+ String[] str = rs.getString(index).split(SEPARATOR);
+ Double[] res = new Double[str.length];
+
+ for (int i = 0; i < str.length; i++) {
+ res[i] = Double.valueOf(str[i]);
+ }
+
+ return res;
+ }
+
+ /**
+ * Reads an object from a stored procedure OUT parameter, converting it to class
+ * returned by 'getClassName' method.
+ *
+ * @throws Exception if read error ocurred, or an object can't be converted to a
+ * target Java class.
+ */
+ @Override
+ public Object materializeObject(CallableStatement rs, int index, int type) throws Exception {
+ String[] str = rs.getString(index).split(SEPARATOR);
+ Double[] res = new Double[str.length];
+
+ for (int i = 0; i < str.length; i++) {
+ res[i] = Double.valueOf(str[i]);
+ }
+
+ return res;
+ }
+}
+----
+
+For Java7
+
+[source, Java]
+----
+// add DoubleArrayType to list of user types
+ServerRuntime runtime = ServerRuntime.builder()
+ .addConfig("cayenne-project.xml")
+ .addModule(new Module() {
+ @Override
+ public void configure(Binder binder) {
+ ServerModule.contributeUserTypes(binder).add(new DoubleArrayType());
+ }
+ })
+ .build();
+----
+
+For Java8
+
+[source, Java]
+----
+// add DoubleArrayType to list of user types
+ServerRuntime runtime = ServerRuntime.builder()
+ .addConfig("cayenne-project.xml")
+ .addModule(binder -> ServerModule.contributeUserTypes(binder).add(new DoubleArrayType()))
+ .build();
+----
+
+====== DbAdapters and Extended Types
+
+As shown in the example above, ExtendedTypes are stored by DbAdapter. In fact DbAdapters often install their own extended types to address incompatibilities, incompleteness and differences between JDBC drivers in handling "standard" JDBC types. For instance some drivers support reading large character columns (CLOB) as java.sql.Clob, but some other - as "character stream", etc. Adapters provided with Cayenne override `configureExtendedTypes()` method to install their own types, possibly substituting Cayenne defaults. Custom DbAdapters can use the same technique.
+
+==== Noteworthy Built-in Services
+
+===== JdbcEventLogger
+
+`org.apache.cayenne.log.JdbcEventLogger` is the service that defines logging API for Cayenne internals. It provides facilities for logging queries, commits, transactions, etc. The default implementation is `org.apache.cayenne.log.Slf4jJdbcEventLogger` that performs logging via slf4j-api library. Cayenne library includes another potentially useful logger - `org.apache.cayenne.log.FormattedSlf4jJdbcEventLogger` that produces formatted multiline SQL output that can be easier to read.
+
+===== DataSourceFactory
+
+Factory that returns `javax.sql.DataSource` object based on the configuration provided in the "nodeDescriptor".
+
+===== DataChannelFilter
+
+An interface of a filter that allows to intercept DataChannel operations. Filters allow to implement chains of custom processors around a DataChannel, that can be used for security, monitoring, business logic, providing context to lifecycle event listeners, etc.
+
+===== QueryCache
+
+Defines API of a cache that stores query results.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/expressions.adoc
----------------------------------------------------------------------
diff --git a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/expressions.adoc b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/expressions.adoc
new file mode 100644
index 0000000..4d41f1d
--- /dev/null
+++ b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/expressions.adoc
@@ -0,0 +1,279 @@
+// 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.
+[[expressions]]
+=== Expressions
+
+==== Expressions Overview
+
+Cayenne provides a simple yet powerful object-based expression language. The most common use of expressions are to build qualifiers and orderings of queries that are later converted to SQL by Cayenne and to evaluate in-memory against specific objects (to access certain values in the object graph or to perform in-memory object filtering and sorting). Cayenne provides API to build expressions in the code and a parser to create expressions from strings.
+
+==== Path Expressions
+
+Before discussing how to build expressions, it is important to understand one group of expressions widely used in Cayenne - path expressions. There are two types of path expressions - object and database, used for navigating graphs of connected objects or joined DB tables respectively. Object paths are much more commonly used, as after all Cayenne is supposed to provide a degree of isolation of the object model from the database. However database paths are helpful in certain situations. General structure of path expressions is the following:
+
+----
+ [db:]segment[+][.segment[+]...]
+----
+
+- `db:` is an optional prefix indicating that the following path is a DB path. Otherwise it is an object path.
+
+- `segment` is a name of a property (relationship or attribute in Cayenne terms) in the path. Path must have at least one segment; segments are separated by dot (".").
+
+- `+` An "OUTER JOIN" path component. Currently "+" only has effect when translated to SQL as OUTER JOIN. When evaluating expressions in memory, it is ignored.
+
+An object path expression represents a chain of property names rooted in a certain (unspecified during expression creation) object and "navigating" to its related value. E.g. a path expression "artist.name" might be a property path starting from a Painting object, pointing to the related Artist object, and then to its name attribute. A few more examples:
+
+- `name` - can be used to navigate (read) the "name" property of a Person (or any other type of object that has a "name" property).
+
+- `artist.exhibits.closingDate` - can be used to navigate to a closing date of any of the exhibits of a Painting's Artist object.
+
+- `artist.exhibits+.closingDate` - same as the previous example, but when translated into SQL, an OUTER JOIN will be used for "exhibits".
+
+Similarly a database path expression is a dot-separated path through DB table joins and columns. In Cayenne joins are mapped as DbRelationships with some symbolic names (the closest concept to DbRelationship name in the DB world is a named foreign key constraint. But DbRelationship names are usually chosen arbitrarily, without regard to constraints naming or even constraints presence). A database path therefore might look like this - `db:dbrelationshipX.dbrelationshipY.COLUMN_Z`. More specific examples:
+
+- `db:NAME` - can be used to navigate to the value of "NAME" column of some unspecified table.
+
+- `db:artist.artistExhibits.exhibit.CLOSING_DATE` - can be used to match a closing date of any of the exhibits of a related artist record.
+
+Cayenne supports "aliases" in path Expressions. E.g. the same expression can be written using explicit path or an alias:
+
+- `artist.exhibits.closingDate` - full path
+
+- `e.closingDate` - alias `e` is used for `artist.exhibits`.
+
+SelectQuery using the second form of the path expression must be made aware of the alias via `SelectQuery.aliasPathSplits(..)`, otherwise an Exception will be thrown. The main use of aliases is to allow users to control how SQL joins are generated if the same path is encountered more than once in any given Expression. Each alias for any given path would result in a separate join. Without aliases, a single join will be used for a group of matching paths.
+
+==== Creating Expressions from Strings
+
+While in most cases users are likely to rely on API from the following section for expression creation, we'll start by showing String expressions, as this will help to understand the semantics. A Cayenne expression can be represented as a String, which can be converted to an expression object using `ExpressionFactory.exp` static method. Here is an example:
+
+
+[source, java]
+----
+String expString = "name like 'A%' and price < 1000";
+Expression exp = ExpressionFactory.exp(expString);
+----
+
+This particular expression may be used to match Paintings whose names that start with "A" and whose price is less than $1000. While this example is pretty self-explanatory, there are a few points worth mentioning. "name" and "price" here are object paths discussed earlier. As always, paths themselves are not attached to a specific root entity and can be applied to any entity that has similarly named attributes or relationships. So when we are saying that this expression "may be used to match Paintings", we are implying that there may be other entities, for which this expression is valid. Now the expression details...
+
+Character constants that are not paths or numeric values should be enclosed in single or double quotes. Two of the expressions below are equivalent:
+
+[source, java]
+----
+name = 'ABC'
+
+// double quotes are escaped inside Java Strings of course
+name = \"ABC\"
+----
+
+Case sensitivity. Expression operators are case sensitive and are usually lowercase. Complex words follow the Java camel-case style:
+
+[source, java]
+----
+// valid
+name likeIgnoreCase 'A%'
+
+// invalid - will throw a parse exception
+name LIKEIGNORECASE 'A%'
+----
+
+Grouping with parenthesis:
+
+
+[source, java]
+----
+value = (price + 250.00) * 3
+----
+
+Path prefixes. Object expressions are unquoted strings, optionally prefixed by "obj:" (usually they are not prefixed at all actually). Database expressions are always prefixed with "db:". A special kind of prefix, not discussed yet is "enum:" that prefixes an enumeration constant:
+
+[source, java]
+----
+// object path
+name = 'Salvador Dali'
+
+// same object path - a rarely used form
+obj:name = 'Salvador Dali'
+
+// multi-segment object path
+artist.name = 'Salvador Dali'
+
+// db path
+db:NAME = 'Salvador Dali'
+
+// enumeration constant
+name = enum:org.foo.EnumClass.VALUE1
+----
+
+Binary conditions are expressions that contain a path on the left, a value on the right, and some operation between them, such as equals, like, etc. They can be used as qualifiers in SelectQueries:
+
+[source, java]
+----
+name like 'A%'
+----
+
+
+Parameters. Expressions can contain named parameters (names that start with "$") that can be substituted with values either by name or by position. Parameterized expressions allow to create reusable expression templates. Also if an Expression contains a complex object that doesn't have a simple String representation (e.g. a Date, a DataObject, an ObjectId), parameterizing such expression is the only way to represent it as String. Here are the examples of both positional and named parameter bindings:
+
+[source, java]
+----
+Expression template = ExpressionFactory.exp("name = $name");
+...
+// name binding
+Map p1 = Collections.singletonMap("name", "Salvador Dali");
+Expression qualifier1 = template.params(p1);
+...
+// positional binding
+Expression qualifier2 = template.paramsArray("Monet");
+----
+
+Positional binding is usually shorter. You can pass positional bindings to the `"exp(..)"` factory method (its second argument is a params vararg):
+
+[source, java]
+----
+Expression qualifier = ExpressionFactory.exp("name = $name", "Monet");
+----
+
+In parameterized expressions with LIKE clause, SQL wildcards must be part of the values in the Map and not the expression string itself:
+
+[source, java]
+----
+Expression qualifier = ExpressionFactory.exp("name like $name", "Salvador%");
+----
+
+When matching on a relationship, the value parameter must be either a Persistent object, an `org.apache.cayenne.ObjectId`, or a numeric ID value (for single column IDs). E.g.:
+
+[source, java]
+----
+Artist dali = ... // asume we fetched this one already
+Expression qualifier = ExpressionFactory.exp("artist = $artist", dali);
+----
+
+When using positional binding, Cayenne would expect values for all parameters to be present. Binding by name offers extra flexibility: subexpressions with uninitialized parameters are automatically pruned from the expression. So e.g. if certain parts of the expression criteria are not provided to the application, you can still build a valid expression:
+
+
+[source, java]
+----
+Expression template = ExpressionFactory.exp("name like $name and dateOfBirth > $date");
+...
+Map p1 = Collections.singletonMap("name", "Salvador%");
+Expression qualifier1 = template.params(p1);
+
+// "qualifier1" is now "name like 'Salvador%'".
+// 'dateOfBirth > $date' condition was pruned, as no value was specified for
+// the $date parameter
+----
+
+Null handling. Handling of Java nulls as operands is no different from normal values. Instead of using special conditional operators, like SQL does (IS NULL, IS NOT NULL), "=" and "!=" expressions are used directly with null values. It is up to Cayenne to translate expressions with nulls to the valid SQL.
+
+NOTE: A formal definition of the expression grammar is provided in Appendix C
+
+==== Creating Expressions via API
+
+Creating expressions from Strings is a powerful and dynamic approach, however a safer alternative is to use Java API. It provides compile-time checking of expressions validity. The API in question is provided by `ExpressionFactory` class (that we've seen already), Property class and Expression class itself. `ExpressionFactory` contains a number of self-explanatory static methods that can be used to build expressions. E.g.:
+
+[source, java]
+----
+// String expression: name like 'A%' and price < 1000
+Expression e1 = ExpressionFactory.likeExp("name", "A%");
+Expression e2 = ExpressionFactory.lessExp("price", 1000);
+Expression finalExp = e1.andExp(e2);
+----
+
+NOTE: The last line in the example above shows how to create a new expression by "chaining" two other epxressions. A common error when chaining expressions is to assume that "andExp" and "orExp" append another expression to the current expression. In fact a new expression is created. I.e. Expression API treats existing expressions as immutable.
+
+As discussed earlier, Cayenne supports aliases in path Expressions, allowing to control how SQL joins are generated if the same path is encountered more than once in the same Expression. Two ExpressionFactory methods allow to implicitly generate aliases to "split" match paths into individual joins if needed:
+
+[source, java]
+----
+Expression matchAllExp(String path, Collection values)
+Expression matchAllExp(String path, Object... values)
+----
+
+"Path" argument to both of these methods can use a split character (a pipe symbol '|') instead of dot to indicate that relationship following a path should be split into a separate set of joins, one per collection value. There can only be one split at most in any given path. Split must always precede a relationship. E.g. `"|exhibits.paintings"`, `"exhibits|paintings"`, etc. Internally Cayenne would generate distinct aliases for each of the split expressions, forcing separate joins.
+
+While ExpressionFactory is pretty powerful, there's an even easier way to create expression using static Property objects generated by Cayenne for each persistent class. Some examples:
+
+[source, java]
+----
+// Artist.NAME is generated by Cayenne and has a type of Property<String>
+Expression e1 = Artist.NAME.eq("Pablo");
+
+// Chaining multiple properties into a path..
+// Painting.ARTIST is generated by Cayenne and has a type of Property<Artist>
+Expression e2 = Painting.ARTIST.dot(Artist.NAME).eq("Pablo");
+----
+
+Property objects provide the API mostly analogius to ExpressionFactory, though it is significantly shorter and is aware of the value types. It provides compile-time checks of both property names and types of arguments in conditions. We will use Property-based API in further examples.
+
+[[evaluate]]
+==== Evaluating Expressions in Memory
+
+When used in a query, an expression is converted to SQL WHERE clause (or ORDER BY clause) by Cayenne during query execution. Thus the actual evaluation against the data is done by the database engine. However the same expressions can also be used for accessing object properties, calculating values, in-memory filtering.
+
+
+Checking whether an object satisfies an expression:
+
+[source, java]
+----
+Expression e = Artist.NAME.in("John", "Bob");
+Artist artist = ...
+if(e.match(artist)) {
+ ...
+}
+----
+
+Reading property value:
+
+
+[source, java]
+----
+String name = Artist.NAME.path().evaluate(artist);
+----
+
+Filtering a list of objects:
+
+[source, java]
+----
+Expression e = Artist.NAME.in("John", "Bob");
+List<Artist> unfiltered = ...
+List<Artist> filtered = e.filterObjects(unfiltered);
+----
+
+NOTE: Current limitation of in-memory expressions is that no collections are permitted in the property path.
+
+==== Translating Expressions to EJBQL
+
+xref:ejbql[EJBQL] is a textual query language that can be used with Cayenne. In some situations, it is convenient to be able to convert Expression instances into EJBQL. Expressions support this conversion. An example is shown below.
+
+[source, java]
+----
+String serial = ...
+Expression e = Pkg.SERIAL.eq(serial);
+List<Object> params = new ArrayList<Object>();
+EJBQLQuery query = new EJBQLQuery("SELECT p FROM Pkg p WHERE " + e.toEJBQL(params,"p");
+
+for(int i=0;i<params.size();i++) {
+ query.setParameter(i+1, params.get(i));
+}
+----
+
+This would be equivalent to the following purely EJBQL querying logic;
+
+[source, java]
+----
+EJBQLQuery query = new EJBQLQuery("SELECT p FROM Pkg p WHERE p.serial = ?1");
+query.setParameter(1,serial);
+----
+
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/including.adoc
----------------------------------------------------------------------
diff --git a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/including.adoc b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/including.adoc
new file mode 100644
index 0000000..b60cc2e
--- /dev/null
+++ b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/including.adoc
@@ -0,0 +1,662 @@
+// 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.
+
+include::../var.adoc[]
+
+[[include]]
+=== Including Cayenne in a Project
+
+==== Jar Files
+
+This is an overview of Cayenne jars that is agnostic of the build tool used. The following are the important libraries:
+
+- `cayenne-di-{version}.jar` - Cayenne dependency injection (DI) container library. All applications will require this file.
+
+- `cayenne-server-{version}.jar` - contains main Cayenne runtime (adapters, DB access classes, etc.). Most applications will require this file.
+
+- `cayenne-client-{version}.jar` - a client-side runtime for xref:rop[ROP applications].
+
+- Other cayenne-* jars - various Cayenne tools extensions.
+
+==== Dependencies
+
+With modern build tools like Maven and Gradle, you should not worry about tracking dependencies. If you have one of those, you can skip this section and go straight to the Maven section below. However if your environment requires manual dependency resolution (like Ant), the distribution provides all of Cayenne jars plus a minimal set of third-party dependencies to get you started in a default configuration. Check lib and `lib/third-party` folders for those.
+
+Dependencies for non-standard configurations will need to be figured out by the users on their own. Check `pom.xml` files of the corresponding Cayenne modules in one of the searchable Maven archives out there to get an idea of those dependencies (e.g. http://search.maven.org).
+
+==== Maven Projects
+
+If you are using Maven, you won't have to deal with figuring out the dependencies. You can simply include cayenne-server artifact in your POM:
+
+[source,xml,subs="verbatim,attributes"]
+----
+<dependency>
+ <groupId>org.apache.cayenne</groupId>
+ <artifactId>cayenne-server</artifactId>
+ <version>{version}</version>
+</dependency>
+----
+
+Additionally Cayenne provides a Maven plugin with a set of goals to perform various project tasks, such as synching generated Java classes with the mapping, described in the following subsection. The full plugin name is `org.apache.cayenne.plugins:cayenne-maven-plugin`.
+
+[[cgen]]
+===== cgen
+
+`cgen` is a `cayenne-maven-plugin` goal that generates and maintains source (.java) files of persistent objects based on a DataMap. By default, it is bound to the generate-sources phase. If "makePairs" is set to "true" (which is the recommended default), this task will generate a pair of classes (superclass/subclass) for each ObjEntity in the DataMap. Superclasses should not be changed manually, since they are always overwritten. Subclasses are never overwritten and may be later customized by the user. If "makePairs" is set to "false", a single class will be generated for each ObjEntity.
+
+By creating custom templates, you can use cgen to generate other output (such as web pages, reports, specialized code templates) based on DataMap information.
+
+[#tablecgen.table.table-bordered]
+.cgen required parameters
+[cols="1,1,4"]
+|===
+|Name |Type|Description
+
+.^|map
+.^|File
+a|DataMap XML file which serves as a source of metadata for class generation. E.g.
+----
+${project.basedir}/src/main/resources/my.map.xml
+----
+|===
+
+
+[#cgenOptional.table.table-bordered]
+.cgen optional parameters
+[cols="2,1,5"]
+|===
+|Name |Type|Description
+
+.^|additionalMaps
+.^|File
+.^|A directory that contains additional DataMap XML files that may be needed to resolve cross-DataMap relationships for the the main DataMap, for which class generation occurs.
+
+.^|client
+.^|boolean
+.^|Whether we are generating classes for the client tier in a Remote Object Persistence application. "False" by default.
+
+.^|destDir
+.^|File
+.^|Root destination directory for Java classes (ignoring their package names). The default is "src/main/java".
+
+.^|embeddableTemplate
+.^|String
+.^|Location of a custom Velocity template file for Embeddable class generation. If omitted, default template is used.
+
+.^|embeddableSuperTemplate
+.^|String
+.^|Location of a custom Velocity template file for Embeddable superclass generation. Ignored unless "makepairs" set to "true". If omitted, default template is used.
+
+.^|encoding
+.^|String
+.^|Generated files encoding if different from the default on current platform. Target encoding must be supported by the JVM running the build. Standard encodings supported by Java on all platforms are US-ASCII, ISO-8859-1, UTF-8, UTF-16BE, UTF-16LE, UTF-16. See javadocs for java.nio.charset.Charset for more information.
+
+.^|excludeEntities
+.^|String
+.^|A comma-separated list of ObjEntity patterns (expressed as a perl5 regex) to exclude from template generation. By default none of the DataMap entities are excluded.
+
+.^|includeEntities
+.^|String
+.^|A comma-separated list of ObjEntity patterns (expressed as a perl5 regex) to include from template generation. By default all DataMap entities are included.
+
+.^|makePairs
+.^|boolean
+.^|If "true" (a recommended default), will generate subclass/superclass pairs, with all generated code placed in superclass.
+
+.^|mode
+.^|String
+.^|Specifies class generator iteration target. There are three possible values: "entity" (default), "datamap", "all". "entity" performs one generator iteration for each included ObjEntity, applying either standard to custom entity templates. "datamap" performs a single iteration, applying DataMap templates. "All" is a combination of entity and datamap.
+
+.^|overwrite
+.^|boolean
+.^|Only has effect when "makePairs" is set to "false". If "overwrite" is "true", will overwrite older versions of generated classes.
+
+.^|superPkg
+.^|String
+.^|Java package name of all generated superclasses. If omitted, each superclass will be placed in the subpackage of its subclass called "auto". Doesn't have any effect if either "makepairs" or "usePkgPath" are false (both are true by default).
+
+.^|superTemplate
+.^|String
+.^|Location of a custom Velocity template file for ObjEntity superclass generation. Only has effect if "makepairs" set to "true". If omitted, default template is used.
+
+.^|template
+.^|String
+.^|Location of a custom Velocity template file for ObjEntity class generation. If omitted, default template is used.
+
+.^|usePkgPath
+.^|boolean
+.^|If set to "true" (default), a directory tree will be generated in "destDir" corresponding to the class package structure, if set to "false", classes will be generated in "destDir" ignoring their package.
+
+.^|createPropertyNames
+.^|boolean
+.^|If set to "true", will generate String Property names. Default is "false"
+|===
+
+Example - a typical class generation scenario, where pairs of classes are generated with default Maven source destination and superclass package:
+
+[source,xml,subs="verbatim,attributes"]
+----
+<plugin>
+ <groupId>org.apache.cayenne.plugins</groupId>
+ <artifactId>cayenne-maven-plugin</artifactId>
+ <version>{version}</version>
+
+ <configuration>
+ <map>${project.basedir}/src/main/resources/my.map.xml</map>
+ </configuration>
+
+ <executions>
+ <execution>
+ <goals>
+ <goal>cgen</goal>
+ </goals>
+ </execution>
+ </executions>
+</plugin>
+----
+
+===== cdbgen
+
+`cdbgen` is a `cayenne-maven-plugin` goal that drops and/or generates tables in a database on Cayenne DataMap. By default, it is bound to the pre-integration-test phase.
+
+[#cdbgenTable.table.table-bordered]
+.cdbgen required parameters
+[cols="1,1,4"]
+|===
+|Name |Type|Description
+
+.^|map
+.^|File
+a|DataMap XML file which serves as a source of metadata for class generation. E.g.
+----
+${project.basedir}/src/main/resources/my.map.xml
+----
+
+.^|dataSource
+.^|XML
+.^|An object that contains Data Source parameters
+|===
+
+
+[#dataSourceParameteres.table.table-bordered]
+.<dataSource> parameters
+[cols="2,1,2,5"]
+|===
+|Name |Type |Required |Description
+
+.^|driver
+.^|String
+.^|Yes
+.^|A class of JDBC driver to use for the target database.
+
+.^|url
+.^|String
+.^|Yes
+.^|JDBC URL of a target database.
+
+.^|username
+.^|String
+.^|No
+.^|Database user name.
+
+.^|password
+.^|String
+.^|No
+.^|Database user password.
+|===
+
+[#cdbgenOptionl.table.table-bordered]
+.cdbgen optional parameters
+[cols="1,1,4"]
+|===
+|Name |Type|Description
+
+.^|adapter
+.^|String
+.^|Java class name implementing org.apache.cayenne.dba.DbAdapter. While this attribute is optional (a generic JdbcAdapter is used if not set), it is highly recommended to specify correct target adapter.
+
+
+.^|createFK
+.^|boolean
+.^|Indicates whether cdbgen should create foreign key constraints. Default is "true".
+
+.^|createPK
+.^|boolean
+.^|Indicates whether cdbgen should create Cayenne-specific auto PK objects. Default is "true".
+
+.^|createTables
+.^|boolean
+.^|Indicates whether cdbgen should create new tables. Default is "true".
+
+.^|dropPK
+.^|boolean
+.^|Indicates whether cdbgen should drop Cayenne primary key support objects. Default is "false".
+
+.^|dropTables
+.^|boolean
+.^|Indicates whether cdbgen should drop the tables before attempting to create new ones. Default is "false".
+|===
+
+Example - creating a DB schema on a local HSQLDB database:
+
+[source,xml, subs="verbatim,attributes"]
+----
+<plugin>
+ <groupId>org.apache.cayenne.plugins</groupId>
+ <artifactId>cayenne-maven-plugin</artifactId>
+ <version>{version}</version>
+ <executions>
+ <execution>
+ <configuration>
+ <map>${project.basedir}/src/main/resources/my.map.xml</map>
+ <adapter>org.apache.cayenne.dba.hsqldb.HSQLDBAdapter</adapter>
+ <dataSource>
+ <url>jdbc:hsqldb:hsql://localhost/testdb</url>
+ <driver>org.hsqldb.jdbcDriver</driver>
+ <username>sa</username>
+ </dataSource>
+ </configuration>
+ <goals>
+ <goal>cdbgen</goal>
+ </goals>
+ </execution>
+ </executions>
+</plugin>
+----
+
+[[mavenCdbimort]]
+===== cdbimport
+
+`cdbimport` is a `cayenne-maven-plugin` goal that generates a DataMap based on an existing database schema. By default, it is bound to the generate-sources phase. This allows you to generate your DataMap prior to building your project, possibly followed by "cgen" execution to generate the classes. CDBImport plugin described in details in chapter xref:dbFirstFlow["DB-First Flow"]
+[#cdbimportTable.table.table-bordered]
+.cdbimport parameters
+[cols="2,1,2,5"]
+|===
+|Name |Type |Required |Description
+
+.^|map
+.^|File
+.^|Yes
+.^|DataMap XML file which is the destination of the schema import. Can be an existing file. If this file does not exist, it is created when cdbimport is executed. E.g. `${project.basedir}/src/main/resources/my.map.xml`. If "overwrite" is true (the default), an existing DataMap will be used as a template for the new imported DataMap, i.e. all its entities will be cleared and recreated, but its common settings, such as default Java package, will be preserved (unless changed explicitly in the plugin configuration).
+
+.^|adapter
+.^|String
+.^|No
+.^|A Java class name implementing org.apache.cayenne.dba.DbAdapter. This attribute is optional. If not specified, AutoAdapter is used, which will attempt to guess the DB type.
+
+.^|dataSource
+.^|XML
+.^|Yes
+.^|An object that contains Data Source parameters.
+
+.^|dbimport
+.^|XML
+.^|No
+.^|An object that contains detailed reverse engineering rules about what DB objects should be processed. For full information about this parameter see xref:dbFirstFlow["DB-First Flow"] chapter.
+|===
+
+[#cdbimportDataSource.table.table-bordered]
+.<dataSource> parameters
+[cols="2,1,2,5"]
+|===
+|Name |Type |Required |Description
+
+.^|driver
+.^|String
+.^|Yes
+.^|A class of JDBC driver to use for the target database.
+
+.^|url
+.^|String
+.^|Yes
+.^|JDBC URL of a target database.
+
+.^|username
+.^|String
+.^|No
+.^|Database user name.
+
+.^|password
+.^|String
+.^|No
+.^|Database user password.
+|===
+
+[#dbimportParameters.table.table-bordered]
+.<dbimport> parameters
+[cols="3,1,4"]
+|===
+|Name |Type|Description
+
+.^|defaultPackage
+.^|String
+.^|A Java package that will be set as the imported DataMap default and a package of all the persistent Java classes. This is a required attribute if the "map" itself does not already contain a default package, as otherwise all the persistent classes will be mapped with no package, and will not compile.
+
+.^|forceDataMapCatalog
+.^|boolean
+.^|Automatically tagging each DbEntity with the actual DB catalog/schema (default behavior) may sometimes be undesirable. If this is the case then setting `forceDataMapCatalog` to `true` will set DbEntity catalog to one in the DataMap. Default value is `false`.
+
+.^|forceDataMapSchema
+.^|boolean
+.^|Automatically tagging each DbEntity with the actual DB catalog/schema (default behavior) may sometimes be undesirable. If this is the case then setting `forceDataMapSchema` to `true` will set DbEntity schema to one in the DataMap. Default value is `false`.
+
+.^|meaningfulPkTables
+.^|String
+.^|A comma-separated list of Perl5 patterns that defines which imported tables should have their primary key columns mapped as ObjAttributes. "*" would indicate all tables.
+
+.^|namingStrategy
+.^|String
+.^|The naming strategy used for mapping database names to object entity names. Default is `org.apache.cayenne.dbsync.naming.DefaultObjectNameGenerator`.
+
+.^|skipPrimaryKeyLoading
+.^|boolean
+.^|Whether to load primary keys. Default "false".
+
+.^|skipRelationshipsLoading
+.^|boolean
+.^|Whether to load relationships. Default "false".
+
+.^|stripFromTableNames
+.^|String
+a|Regex that matches the part of the table name that needs to be stripped off when generating ObjEntity name. Here are some examples:
+[source,XML]
+----
+<!-- Strip prefix -->
+<stripFromTableNames>^myt_</stripFromTableNames>
+
+<!-- Strip suffix -->
+<stripFromTableNames>_s$</stripFromTableNames>
+
+<!-- Strip multiple occurrences in the middle -->
+<stripFromTableNames>_abc</stripFromTableNames>
+----
+
+.^|usePrimitives
+.^|boolean
+.^|Whether numeric and boolean data types should be mapped as Java primitives or Java classes. Default is "true", i.e. primitives will be used.
+
+.^|useJava7Types
+.^|boolean
+.^|Whether `DATE`, `TIME` and `TIMESTAMP` data types should be mapped as `java.util.Date` or `java.time.* classes`. Default is "false", i.e. `java.time.*` will be used.
+
+.^|filters configuration
+.^|XML
+a|Detailed reverse engineering rules about what DB objects should be processed. For full information about this parameter see xref:dbFirstFlow["DB-First Flow"] chapter. Here is some simple example:
+[source,XML]
+----
+<dbimport>
+ <catalog name="test_catalog">
+ <schema name="test_schema">
+ <includeTable>.*</includeTable>
+ <excludeTable>test_table</excludeTable>
+ </schema>
+ </catalog>
+
+ <includeProcedure pattern=".*"/>
+</dbimport>
+----
+
+
+|===
+
+Example - loading a DB schema from a local HSQLDB database (essentially a reverse operation compared to the cdbgen example above) :
+
+[source, XML, subs="verbatim,attributes"]
+----
+<plugin>
+ <groupId>org.apache.cayenne.plugins</groupId>
+ <artifactId>cayenne-maven-plugin</artifactId>
+ <version>{version}</version>
+
+ <executions>
+ <execution>
+ <configuration>
+ <map>${project.basedir}/src/main/resources/my.map.xml</map>
+ <dataSource>
+ <url>jdbc:mysql://127.0.0.1/mydb</url>
+ <driver>com.mysql.jdbc.Driver</driver>
+ <username>sa</username>
+ </dataSource>
+ <dbimport>
+ <defaultPackage>com.example.cayenne</defaultPackage>
+ </dbimport>
+ </configuration>
+ <goals>
+ <goal>cdbimport</goal>
+ </goals>
+ </execution>
+ </executions>
+</plugin>
+----
+
+==== Gradle Projects
+
+To include Cayenne into your Gradle project you have two options:
+
+- Simply add Cayenne as a dependency:
+
+[source, Groovy, subs="verbatim,attributes"]
+----
+compile 'org.apache.cayenne:cayenne-server:{version}'
+----
+
+- Or you can use Cayenne Gradle plugin
+
+===== Gradle Plugin
+
+Cayenne Gradle plugin provides several tasks, such as synching generated Java classes with the mapping or synching mapping with the database. Plugin also provides `cayenne` extension that have some useful utility methods. Here is example of how to include Cayenne plugin into your project:
+
+[source, Groovy, subs="verbatim,attributes"]
+----
+buildscript {
+ // add Maven Central repository
+ repositories {
+ mavenCentral()
+ }
+ // add Cayenne Gradle Plugin
+ dependencies {
+ classpath group: 'org.apache.cayenne.plugins', name: 'cayenne-gradle-plugin', version: '{version}'
+ }
+}
+
+// apply plugin
+apply plugin: 'org.apache.cayenne'
+
+// set default DataMap
+cayenne.defaultDataMap 'datamap.map.xml'
+
+// add Cayenne dependencies to your project
+dependencies {
+ // this is a shortcut for 'org.apache.cayenne:cayenne-server:VERSION_OF_PLUGIN'
+ compile cayenne.dependency('server')
+ compile cayenne.dependency('java8')
+}
+----
+
+====== Warning
+
+Cayenne Gradle plugin is experimental and it's API can change later.
+
+===== cgen
+
+Cgen task generates Java classes based on your DataMap, it has same configuration parameters as in Maven Plugin version, described in xref:tablecgen[Table, “cgen required parameters”.]. If you provided default DataMap via `cayenne.defaultDataMap`, you can skip `cgen` configuration as default settings will suffice in common case.
+
+Here is how you can change settings of the default `cgen` task:
+
+[source, Groovy]
+----
+cgen {
+ client = false
+ mode = 'all'
+ overwrite = true
+ createPropertiesNames = true
+}
+----
+
+And here is example of how to define additional cgen task (e.g. for client classes if you are using ROP):
+
+
+[source, Groovy]
+----
+task clientCgen(type: cayenne.cgen) {
+ client = true
+}
+----
+
+===== cdbimport
+
+This task is for creating and synchronizing your Cayenne model from database schema. Full list of parameters are same as in Maven Plugin version, described in xref:cdbimportTable[Table, “cdbimport parameters”], with exception that Gradle version will use Groovy instead of XML.
+
+Here is example of configuration for cdbimport task:
+
+[source, Groovy]
+----
+cdbimport {
+ // map can be skipped if it is defined in cayenne.defaultDataMap
+ map 'datamap.map.xml'
+
+ dataSource {
+ driver 'com.mysql.cj.jdbc.Driver'
+ url 'jdbc:mysql://127.0.0.1:3306/test?useSSL=false'
+ username 'root'
+ password ''
+ }
+
+ dbImport
+ // additional settings
+ usePrimitives false
+ defaultPackage 'org.apache.cayenne.test'
+
+ // DB filter configuration
+ catalog 'catalog-1'
+ schema 'schema-1'
+
+ catalog {
+ name 'catalog-2'
+
+ includeTable 'table0', {
+ excludeColumns '_column_'
+ }
+
+ includeTables 'table1', 'table2', 'table3'
+
+ includeTable 'table4', {
+ includeColumns 'id', 'type', 'data'
+ }
+
+ excludeTable '^GENERATED_.*'
+ }
+
+ catalog {
+ name 'catalog-3'
+ schema {
+ name 'schema-2'
+ includeTable 'test_table'
+ includeTable 'test_table2', {
+ excludeColumn '__excluded'
+ }
+ }
+ }
+
+ includeProcedure 'procedure_test_1'
+
+ includeColumns 'id', 'version'
+
+ tableTypes 'TABLE', 'VIEW'
+ }
+}
+----
+
+===== cdbgen
+
+Cdbgen task drops and/or generates tables in a database on Cayenne DataMap. Full list of parameters are same as in Maven Plugin version, described in xref:cdbgenTable[Table , “cdbgen required parameters”]
+
+Here is example of how to configure default `cdbgen` task:
+
+[source, Groovy]
+----
+cdbgen {
+
+ adapter 'org.apache.cayenne.dba.derby.DerbyAdapter'
+
+ dataSource {
+ driver 'org.apache.derby.jdbc.EmbeddedDriver'
+ url 'jdbc:derby:build/testdb;create=true'
+ username 'sa'
+ password ''
+ }
+
+ dropTables true
+ dropPk true
+
+ createTables true
+ createPk true
+ createFk true
+}
+----
+
+===== Link tasks to Gradle build lifecycle
+
+With gradle you can easily connect Cayenne tasks to default build lifecycle. Here is short example of how to connect defaut `cgen` and `cdbimport` tasks with `compileJava` task:
+
+[source, Groovy]
+----
+cgen.dependsOn cdbimport
+compileJava.dependsOn cgen
+----
+
+NOTE: Running `cdbimport` automatically with build not always a good choice, e.g. in case of complex model that you need to alter in the Cayenne Modeler after import.
+
+==== Ant Projects
+
+Ant tasks are the same as Maven plugin goals described above, namely "cgen", "cdbgen", "cdbimport". Configuration parameters are also similar (except Maven can guess many defaults that Ant can't). To include Ant tasks in the project, use the following Antlib:
+
+[source, XML]
+----
+<typedef resource="org/apache/cayenne/tools/antlib.xml">
+ <classpath>
+ <fileset dir="lib" >
+ <include name="cayenne-ant-*.jar" />
+ <include name="cayenne-cgen-*.jar" />
+ <include name="cayenne-dbsync-*.jar" />
+ <include name="cayenne-di-*.jar" />
+ <include name="cayenne-project-*.jar" />
+ <include name="cayenne-server-*.jar" />
+ <include name="commons-collections-*.jar" />
+ <include name="commons-lang-*.jar" />
+ <include name="slf4j-api-*.jar" />
+ <include name="velocity-*.jar" />
+ <include name="vpp-2.2.1.jar" />
+ </fileset>
+ </classpath>
+</typedef>
+----
+
+===== cgen
+
+===== cdbgen
+
+===== cdbimport
+
+This is an Ant counterpart of "cdbimport" goal of cayenne-maven-plugin described above. It has exactly the same properties. Here is a usage example:
+
+[source, XML]
+----
+ <cdbimport map="${context.dir}/WEB-INF/my.map.xml"
+ driver="com.mysql.jdbc.Driver"
+ url="jdbc:mysql://127.0.0.1/mydb"
+ username="sa"
+ defaultPackage="com.example.cayenne"/>
+----
+
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/lifecycle.adoc
----------------------------------------------------------------------
diff --git a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/lifecycle.adoc b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/lifecycle.adoc
new file mode 100644
index 0000000..9305723
--- /dev/null
+++ b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/lifecycle.adoc
@@ -0,0 +1,273 @@
+// 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.
+
+=== Lifecycle Events
+
+An application might be interested in getting notified when a Persistent object moves through its lifecycle (i.e. fetched from DB, created, modified, committed). E.g. when a new object is created, the application may want to initialize its default properties (this can't be done in constructor, as constructor is also called when an object is fetched from DB). Before save, the application may perform validation and/or set some properties (e.g. "updatedTimestamp"). After save it may want to create an audit record for each saved object, etc., etc.
+
+All this can be achieved by declaring callback methods either in Persistent objects or in non-persistent listener classes defined by the application (further simply called "listeners"). There are eight types of lifecycle events supported by Cayenne, listed later in this chapter. When any such event occurs (e.g. an object is committed), Cayenne would invoke all appropriate callbacks. Persistent objects would receive their own events, while listeners would receive events from any objects.
+
+Cayenne allows to build rather powerful and complex "workflows" or "processors" tied to objects lifecycle, especially with listeners, as they have full access to the application evnironment outside Cayenne. This power comes from such features as filtering which entity events are sent to a given listener and the ability to create a common operation context for multiple callback invocations. All of these are discussed later in this chapter.
+
+==== Types of Lifecycle Events
+
+Cayenne defines the following 8 types of lifecycle events for which callbacks can be regsitered:
+
+[#lifecycleEvent.table.table-bordered]
+.Lifecycle Event Types
+[cols="1,4"]
+|===
+|Event |Occurs...
+
+.^|PostAdd
+.^|right after a new object is created inside `ObjectContext.newObject()`. When this event is fired the object is already registered with its ObjectContext and has its ObjectId and ObjectContext properties set.
+
+.^|PrePersist
+.^|right before a new object is committed, inside `ObjectContext.commitChanges()` and `ObjectContext.commitChangesToParent()` (and after `"validateForInsert()"`).
+
+.^|PreUpdate
+.^|right before a modified object is committed, inside `ObjectContext.commitChanges()` and `ObjectContext.commitChangesToParent()` (and after `"validateForUpdate()"`).
+
+.^|PreRemove
+.^|right before an object is deleted, inside `ObjectContext.deleteObjects()`. The event is also generated for each object indirectly deleted as a result of CASCADE delete rule.
+
+.^|PostPersist
+.^|right after a commit of a new object is done, inside `ObjectContext.commitChanges()`.
+
+.^|PostUpdate
+.^|right after a commit of a modified object is done, inside `ObjectContext.commitChanges()`.
+
+.^|PostRemove
+.^|right after a commit of a deleted object is done, inside `ObjectContext.commitChanges()`.
+
+.^|PostLoad
+a|
+- After an object is fetched inside ObjectContext.performQuery().
+- After an object is reverted inside ObjectContext.rollbackChanges().
+- Anytime a faulted object is resolved (i.e. if a relationship is fetched).
+|===
+
+==== Callbacks on Persistent Objects
+
+Callback methods on Persistent classes are mapped in CayenneModeler for each ObjEntity. Empty callback methods are automatically created as a part of class generation (either with Maven, Ant or the Modeler) and are later filled with appropriate logic by the programmer. E.g. assuming we mapped a 'post-add' callback called 'onNewOrder' in ObjEntity 'Order', the following code will be generated:
+
+[source, Java]
+----
+public abstract class _Order extends CayenneDataObject {
+ protected abstract void onNewOrder();
+}
+
+public class Order extends _Order {
+
+ @Override
+ protected void onNewOrder() {
+ //TODO: implement onNewOrder
+ }
+}
+----
+
+As `onNewOrder()` is already declared in the mapping, it does not need to be registered explicitly. Implementing the method in subclass to do something meaningful is all that is required at this point.
+
+As a rule callback methods do not have any knowledge of the outside application, and can only access the state of the object itself and possibly the state of other persistent objects via object's own ObjectContext.
+
+NOTE: Validation and callbacks: There is a clear overlap in functionality between object callbacks and `DataObject.validateForX()` methods. In the future validation may be completely superceeded by callbacks. It is a good idea to use "validateForX" strictly for validation (or not use it at all). Updating the state before commit should be done via callbacks.
+
+==== Callbacks on Non-Persistent Listeners
+
+A listener is simply some application class that has one or more annotated callback methods. A callback method signature should be `void someMethod(SomePersistentType object)`. It can be public, private, protected or use default access:
+
+[source, Java]
+----
+ public class OrderListener {
+
+ @PostAdd(Order.class)
+ public void setDefaultsForNewOrder(Order o) {
+ o.setCreatedOn(new Date());
+ }
+}
+----
+
+Notice that the example above contains an annotation on the callback method that defines the type of the event this method should be called for. Before we go into annotation details, we'll show how to create and register a listener with Cayenne. It is always a user responsibility to register desired application listeners, usually right after ServerRuntime is started. Here is an example:
+
+First let's define 2 simple listeners.
+
+[source, Java]
+----
+public class Listener1 {
+
+ @PostAdd(MyEntity.class)
+ void postAdd(Persistent object) {
+ // do something
+ }
+}
+
+public class Listener2 {
+
+ @PostRemove({ MyEntity1.class, MyEntity2.class })
+ void postRemove(Persistent object) {
+ // do something
+ }
+
+ @PostUpdate({ MyEntity1.class, MyEntity2.class })
+ void postUpdate(Persistent object) {
+ // do something
+ }
+}
+----
+
+Ignore the annotations for a minute. The important point here is that the listeners are arbitrary classes unmapped and unknown to Cayenne, that contain some callback methods. Now let's register them with runtime:
+
+[source, Java]
+----
+ServerRuntime runtime = ...
+
+runtime.getDataDomain().addListener(new Listener1());
+runtime.getDataDomain().addListener(new Listener2());
+----
+
+
+Listeners in this example are very simple. However they don't have to be. Unlike Persistent objects, normally listeners initialization is managed by the application code, not Cayenne, so listeners may have knowledge of various application services, operation transactional context, etc. Besides a single listener can apply to multiple entities. As a consequence their callbacks can do more than just access a single ObjectContext.
+
+Now let's discuss the annotations. There are eight annotations exactly matching the names of eight lifecycle events. A callback method in a listener should be annotated with at least one, but possibly with more than one of them. Annotation itself defines what event the callback should react to. Annotation parameters are essentially an entity filter, defining a subset of ObjEntities whose events we are interested in:
+
+[source, Java]
+----
+// this callback will be invoked on PostRemove event of any object
+// belonging to MyEntity1, MyEntity2 or their subclasses
+@PostRemove({ MyEntity1.class, MyEntity2.class })
+void postRemove(Persistent object) {
+ ...
+}
+----
+
+[source, Java]
+----
+// similar example with multipe annotations on a single method
+// each matching just one entity
+@PostPersist(MyEntity1.class)
+@PostRemove(MyEntity1.class)
+@PostUpdate(MyEntity1.class)
+void postCommit(MyEntity1 object) {
+ ...
+}
+----
+
+As shown above, "value" (the implicit annotation parameter) can contain one or more entity classes. Only these entities' events will result in callback invocation. There's also another way to match entities - via custom annotations. This allows to match any number of entities without even knowing what they are. Here is an example. We'll first define a custom annotation:
+
+[source, Java]
+----
+@Target(ElementType.TYPE)
+@Retention(RetentionPolicy.RUNTIME)
+public @interface Tag {
+
+}
+----
+
+Now we can define a listener that will react to events from ObjEntities annotated with this annotation:
+
+[source, Java]
+----
+public class Listener3 {
+
+ @PostAdd(entityAnnotations = Tag.class)
+ void postAdd(Persistent object) {
+ // do something
+ }
+}
+----
+
+As you see we don't have any entities yet, still we can define a listener that does something useful. Now let's annotate some entities:
+
+[source, Java]
+----
+@Tag
+public class MyEntity1 extends _MyEntity1 {
+
+}
+
+@Tag
+public class MyEntity2 extends _MyEntity2 {
+
+}
+----
+
+
+==== Combining Listeners with DataChannelFilters
+
+A final touch in the listeners design is preserving the state of the listener within a single select or commit, so that events generated by multiple objects can be collected and processed all together. To do that you will need to implement a `DataChannelFilter`, and add some callback methods to it. They will store their state in a ThreadLocal variable of the filter. Here is an example filter that does something pretty meaningless - counts how many total objects were committed. However it demonstrates the important pattern of aggregating multiple events and presenting a combined result:
+
+[source, Java]
+----
+public class CommittedObjectCounter implements DataChannelFilter {
+
+ private ThreadLocal<int[]> counter;
+
+ @Override
+ public void init(DataChannel channel) {
+ counter = new ThreadLocal<int[]>();
+ }
+
+ @Override
+ public QueryResponse onQuery(ObjectContext originatingContext, Query query, DataChannelFilterChain filterChain) {
+ return filterChain.onQuery(originatingContext, query);
+ }
+
+ @Override
+ public GraphDiff onSync(ObjectContext originatingContext, GraphDiff changes, int syncType,
+ DataChannelFilterChain filterChain) {
+
+ // init the counter for the current commit
+ counter.set(new int[1]);
+
+ try {
+ return filterChain.onSync(originatingContext, changes, syncType);
+ } finally {
+
+ // process aggregated result and release the counter
+ System.out.println("Committed " + counter.get()[0] + " object(s)");
+ counter.set(null);
+ }
+ }
+
+ @PostPersist(entityAnnotations = Tag.class)
+ @PostUpdate(entityAnnotations = Tag.class)
+ @PostRemove(entityAnnotations = Tag.class)
+ void afterCommit(Persistent object) {
+ counter.get()[0]++;
+ }
+}
+----
+
+Now since this is both a filter and a listener, it needs to be registered as such:
+
+[source, Java]
+----
+CommittedObjectCounter counter = new CommittedObjectCounter();
+
+ServerRuntime runtime = ...
+DataDomain domain = runtime.getDataDomain();
+
+// register filter
+// this will also add it as a listener (since 3.2)
+domain.addFilter(counter);
+----
+
+
+
+
+
+
+
+
+
[09/13] cayenne git commit: CAY-2371 Switch documentation from
Docbook to Asciidoctor format
Posted by nt...@apache.org.
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/_getting-started-guide/object-relational-mapping.adoc
----------------------------------------------------------------------
diff --git a/docs/asciidoc/getting-started-guide/src/docs/asciidoc/_getting-started-guide/object-relational-mapping.adoc b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/_getting-started-guide/object-relational-mapping.adoc
new file mode 100644
index 0000000..1851c6d
--- /dev/null
+++ b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/_getting-started-guide/object-relational-mapping.adoc
@@ -0,0 +1,109 @@
+// 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.
+=== Getting started with Object Relational Mapping (ORM)
+The goal of this section is to learn how to create a simple Object-Relational model with
+CayenneModeler. We will create a complete ORM model for the following database
+schema:
+
+image::cayenne-tutorial-model.png[align="center"]
+
+NOTE: Very often you'd have an existing database already, and
+ it can be quickly imported in Cayenne via "Tools > Reengineer Database
+ Schema". This will save you lots of time compared to manual mapping. However
+ understanding how to create the mapping by hand is important, so we are showing
+ the "manual" approach below.
+
+==== Mapping Database Tables and Columns
+Lets go back to CayenneModeler where we have the newly created project open and start
+by adding the ARTIST table. Database tables are called *DbEntities*
+in Cayenne mapping (those can be actual tables or database views).
+
+Select "datamap" on the left-hand side project tree and click "Create DbEntity" button image:icon-dbentity.png[]
+(or use "Project > Create DbEntity" menu). A new DbEntity is created. In "DbEntity
+Name" field enter "ARTIST". Then click on "Create Attribute" button image:icon-attribute.png[]
+on the entity toolbar. This action changes the view to the "Attribute"
+tab and adds a new attribute (attribute means a "table column" in this case) called
+"untitledAttr". Let's rename it to ID, make it an `INTEGER` and make it a PK:
+
+image::modeler-artistid.png[align="center"]
+
+Similarly add NAME `VARCHAR(200)` and DATE_OF_BIRTH `DATE` attributes. After that repeat
+this procedure for PAINTING and GALLERY entities to match DB schema shown above.
+
+==== Mapping Database Relationships
+
+Now we need to specify relationships between ARTIST, PAINTING and GALLERY tables.
+Start by creating a one-to-many ARTIST/PAINTING relationship:
+
+- Select the ARTIST DbEntity on the left and click on the "Properties" tab.
+
+- Click on "Create Relationship" button on the entity toolbar image:icon-relationship.png[] - a relationship
+called "untitledRel" is created.
+
+- Choose the "Target" to be "Painting".
+
+- Click on the "Database Mapping" button image:icon-edit.png[] - relationship
+configuration dialog is presented. Here you can assign a name to the
+relationship and also its complimentary reverse relationship. This name can be
+anything (this is really a symbolic name of the database referential
+constraint), but it is recommended to use a valid Java identifier, as this will
+save some typing later. We'll call the relationship "paintings" and reverse
+relationship "artist".
+
+- Click on "Add" button on the right to add a join
+
+- Select "ID" column for the "Source" and "ARTIST_ID" column for the target.
+
+- Relationship information should now look like this:
+
+image::modeler-dbrelationship.png[align="center"]
+
+- Click "Done" to confirm the changes and close the dialog.
+
+- Two complimentary relationships have been created - from ARTIST to PAINTING
+and back. Still you may have noticed one thing is missing - "paintings"
+relationship should be to-many, but "To Many" checkbox is not checked. Let's
+change that - check the checkbox for "paintings" relationship, and then click on
+PAINTING DbEntity, and uncheck "artist" relationship "To Many" to make the
+reverse relationship "to-one" as it should be.
+
+- Repeat the steps above to create a many-to-one relationship from PAINTING to GALLERY, calling the relationships pair
+"gallery" and "paintings".
+
+==== Mapping Java Classes
+
+Now that the database schema mapping is complete, CayenneModeler can create mappings
+of Java classes (aka "ObjEntities") by deriving everything from DbEntities. At present
+there is no way to do it for the entire DataMap in one click, so we'll do it for each
+table individually.
+
+- Select "ARTIST" DbEntity and click on "Create ObjEntity" button image:icon-new_objentity.png[]
+either on the entity toolbar or on the main toolbar. An ObjEntity called
+"Artist" is created with a Java class field set to
+"org.example.cayenne.persistent.Artist". The modeler transformed the database
+names to the Java-friendly names (e.g., if you click on the "Attributes" tab,
+you'll see that "DATE_OF_BIRTH" column was converted to "dateOfBirth" Java class
+attribute).
+
+- Select "GALLERY" DbEntity and click on "Create ObjEntity" button again - you'll see a "Gallery" ObjEntity created.
+- Finally, do the same thing for "PAINTING".
+
+Now you need to synchronize relationships. Artist and Gallery entities were created
+when there was no related "Painting" entity, so their relationships were not set.
+
+- Click on the "Artist" ObjEntity. Now click on "Sync ObjEntity with DbEntity" button on
+the toolbar image:icon-sync.png[] - you will see the "paintings" relationship appear.
+- Do the same for the "Gallery" entity.
+
+Unless you want to customize the Java class and property names (which you can do easily) the mapping is complete.
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/_getting-started-guide/part2.adoc
----------------------------------------------------------------------
diff --git a/docs/asciidoc/getting-started-guide/src/docs/asciidoc/_getting-started-guide/part2.adoc b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/_getting-started-guide/part2.adoc
new file mode 100644
index 0000000..e12d0f0
--- /dev/null
+++ b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/_getting-started-guide/part2.adoc
@@ -0,0 +1,20 @@
+// 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.
+== Learning mapping basics
+
+include::starting-project.adoc[]
+
+include::object-relational-mapping.adoc[]
+
+include::java-classes.adoc[]
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/_getting-started-guide/part3.adoc
----------------------------------------------------------------------
diff --git a/docs/asciidoc/getting-started-guide/src/docs/asciidoc/_getting-started-guide/part3.adoc b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/_getting-started-guide/part3.adoc
new file mode 100644
index 0000000..cd31060
--- /dev/null
+++ b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/_getting-started-guide/part3.adoc
@@ -0,0 +1,22 @@
+// 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.
+== Learning Cayenne API
+
+include::object-context.adoc[]
+
+include::persistent-objects.adoc[]
+
+include::select-query.adoc[]
+
+include::delete.adoc[]
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/_getting-started-guide/persistent-objects.adoc
----------------------------------------------------------------------
diff --git a/docs/asciidoc/getting-started-guide/src/docs/asciidoc/_getting-started-guide/persistent-objects.adoc b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/_getting-started-guide/persistent-objects.adoc
new file mode 100644
index 0000000..16d4f2a
--- /dev/null
+++ b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/_getting-started-guide/persistent-objects.adoc
@@ -0,0 +1,111 @@
+// 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.
+=== Getting started with persistent objects
+In this chapter we'll learn about persistent objects, how to customize them and how to
+create and save them in DB.
+
+==== Inspecting and Customizing Persistent Objects
+Persistent classes in Cayenne implement a DataObject interface. If you inspect any of
+the classes generated earlier in this tutorial (e.g.
+`org.example.cayenne.persistent.Artist`), you'll see that it extends a class with the name
+that starts with underscore (`org.example.cayenne.persistent.auto._Artist`), which in turn
+extends from `org.apache.cayenne.CayenneDataObject`. Splitting each persistent class into
+user-customizable subclass (`Xyz`) and a generated superclass (`_Xyz`) is a useful technique
+to avoid overwriting the custom code when refreshing classes from the mapping
+model.
+
+Let's for instance add a utility method to the Artist class that sets Artist date of
+birth, taking a string argument for the date. It will be preserved even if the model
+changes later:
+
+[source,java]
+----
+include::{java-include-dir}/persistent/Artist.java[tag=content]
+----
+
+==== Create New Objects
+Now we'll create a bunch of objects and save them to the database. An object is
+created and registered with `ObjectContext` using "`newObject`" method. Objects *must* be registered
+with `DataContext` to be persisted and to allow setting relationships with other objects.
+Add this code to the "main" method of the Main class:
+
+[source,java,indent=0]
+----
+include::{java-include-dir}/Main.java[tag=new-artist]
+----
+
+Note that at this point "picasso" object is only stored in memory and is not saved in
+the database. Let's continue by adding a Metropolitan Museum "`Gallery`" object and a few
+Picasso "Paintings":
+
+[source,java,indent=0]
+----
+include::{java-include-dir}/Main.java[tag=new-painting]
+----
+
+Now we can link the objects together, establishing relationships. Note that in each
+case below relationships are automatically established in both directions (e.g.
+`picasso.addToPaintings(girl)` has exactly the same effect as
+`girl.setToArtist(picasso)`).
+
+[source, java, indent=0]
+----
+include::{java-include-dir}/Main.java[tag=link-objects]
+----
+
+Now lets save all five new objects, in a single method call:
+
+[source, java, indent=0]
+----
+include::{java-include-dir}/Main.java[tag=commit]
+----
+
+Now you can run the application again as described in the previous chapter. The new
+output will show a few actual DB operations:
+
+ ...
+ INFO: --- transaction started.
+ INFO: No schema detected, will create mapped tables
+ INFO: CREATE TABLE GALLERY (ID INTEGER NOT NULL, NAME VARCHAR (200), PRIMARY KEY (ID))
+ INFO: CREATE TABLE ARTIST (DATE_OF_BIRTH DATE, ID INTEGER NOT NULL, NAME VARCHAR (200), PRIMARY KEY (ID))
+ INFO: CREATE TABLE PAINTING (ARTIST_ID INTEGER, GALLERY_ID INTEGER, ID INTEGER NOT NULL,
+ NAME VARCHAR (200), PRIMARY KEY (ID))
+ INFO: ALTER TABLE PAINTING ADD FOREIGN KEY (ARTIST_ID) REFERENCES ARTIST (ID)
+ INFO: ALTER TABLE PAINTING ADD FOREIGN KEY (GALLERY_ID) REFERENCES GALLERY (ID)
+ INFO: CREATE TABLE AUTO_PK_SUPPORT (
+ TABLE_NAME CHAR(100) NOT NULL, NEXT_ID BIGINT NOT NULL, PRIMARY KEY(TABLE_NAME))
+ INFO: DELETE FROM AUTO_PK_SUPPORT WHERE TABLE_NAME IN ('ARTIST', 'GALLERY', 'PAINTING')
+ INFO: INSERT INTO AUTO_PK_SUPPORT (TABLE_NAME, NEXT_ID) VALUES ('ARTIST', 200)
+ INFO: INSERT INTO AUTO_PK_SUPPORT (TABLE_NAME, NEXT_ID) VALUES ('GALLERY', 200)
+ INFO: INSERT INTO AUTO_PK_SUPPORT (TABLE_NAME, NEXT_ID) VALUES ('PAINTING', 200)
+ INFO: SELECT NEXT_ID FROM AUTO_PK_SUPPORT WHERE TABLE_NAME = ? FOR UPDATE [bind: 1:'ARTIST']
+ INFO: SELECT NEXT_ID FROM AUTO_PK_SUPPORT WHERE TABLE_NAME = ? FOR UPDATE [bind: 1:'GALLERY']
+ INFO: SELECT NEXT_ID FROM AUTO_PK_SUPPORT WHERE TABLE_NAME = ? FOR UPDATE [bind: 1:'PAINTING']
+ INFO: INSERT INTO GALLERY (ID, NAME) VALUES (?, ?)
+ INFO: [batch bind: 1->ID:200, 2->NAME:'Metropolitan Museum of Art']
+ INFO: === updated 1 row.
+ INFO: INSERT INTO ARTIST (DATE_OF_BIRTH, ID, NAME) VALUES (?, ?, ?)
+ INFO: [batch bind: 1->DATE_OF_BIRTH:'1881-10-25 00:00:00.0', 2->ID:200, 3->NAME:'Pablo Picasso']
+ INFO: === updated 1 row.
+ INFO: INSERT INTO PAINTING (ARTIST_ID, GALLERY_ID, ID, NAME) VALUES (?, ?, ?, ?)
+ INFO: [batch bind: 1->ARTIST_ID:200, 2->GALLERY_ID:200, 3->ID:200, 4->NAME:'Gertrude Stein']
+ INFO: [batch bind: 1->ARTIST_ID:200, 2->GALLERY_ID:200, 3->ID:201, 4->NAME:'Girl Reading at a Table']
+ INFO: === updated 2 rows.
+ INFO: +++ transaction committed.
+
+So first Cayenne creates the needed tables (remember, we used
+"`CreateIfNoSchemaStrategy`"). Then it runs a number of inserts, generating primary keys
+on the fly. Not bad for just a few lines of code.
+
+
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/_getting-started-guide/select-query.adoc
----------------------------------------------------------------------
diff --git a/docs/asciidoc/getting-started-guide/src/docs/asciidoc/_getting-started-guide/select-query.adoc b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/_getting-started-guide/select-query.adoc
new file mode 100644
index 0000000..56c843d
--- /dev/null
+++ b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/_getting-started-guide/select-query.adoc
@@ -0,0 +1,56 @@
+// 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.
+=== Selecting Objects
+This chapter shows how to select objects from the database using `ObjectSelect` query.
+
+==== Introducing ObjectSelect
+It was shown before how to persist new objects. Cayenne queries are used to access
+already saved objects. The primary query type used for selecting objects is `ObjectSelect`.
+It can be mapped in CayenneModeler or created
+via the API. We'll use the latter approach in this section. We don't have too much data
+in the database yet, but we can still demonstrate the main principles below.
+
+- Select all paintings (the code, and the log output it generates):
+
+[source,java]
+----
+List<Painting> paintings1 = ObjectSelect.query(Painting.class).select(context);
+----
+
+ INFO: SELECT t0.GALLERY_ID, t0.ARTIST_ID, t0.NAME, t0.ID FROM PAINTING t0
+ INFO: === returned 2 rows. - took 18 ms.
+
+- Select paintings that start with "`gi`", ignoring case:
+
+[source,java]
+----
+List<Painting> paintings2 = ObjectSelect.query(Painting.class)
+ .where(Painting.NAME.likeIgnoreCase("gi%")).select(context);
+----
+ INFO: SELECT t0.GALLERY_ID, t0.NAME, t0.ARTIST_ID, t0.ID FROM PAINTING t0 WHERE UPPER(t0.NAME) LIKE UPPER(?)
+ [bind: 1->NAME:'gi%'] - prepared in 6 ms.
+ INFO: === returned 1 row. - took 18 ms.
+
+- Select all paintings done by artists who were born more than a 100 years ago:
+
+[source,java]
+----
+List<Painting> paintings3 = ObjectSelect.query(Painting.class)
+ .where(Painting.ARTIST.dot(Artist.DATE_OF_BIRTH).lt(LocalDate.of(1900,1,1)))
+ .select(context);
+----
+
+ INFO: SELECT t0.GALLERY_ID, t0.NAME, t0.ARTIST_ID, t0.ID FROM PAINTING t0 JOIN ARTIST t1 ON (t0.ARTIST_ID = t1.ID)
+ WHERE t1.DATE_OF_BIRTH < ? [bind: 1->DATE_OF_BIRTH:'1911-01-01 00:00:00.493'] - prepared in 7 ms.
+ INFO: === returned 2 rows. - took 25 ms.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/_getting-started-guide/setup.adoc
----------------------------------------------------------------------
diff --git a/docs/asciidoc/getting-started-guide/src/docs/asciidoc/_getting-started-guide/setup.adoc b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/_getting-started-guide/setup.adoc
new file mode 100644
index 0000000..5a81104
--- /dev/null
+++ b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/_getting-started-guide/setup.adoc
@@ -0,0 +1,26 @@
+// 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.
+== Setting up the environment
+
+The goal of this chapter of the tutorial is to install (or check that you already have
+installed) a minimally needed set of software to build a Cayenne application.
+
+=== Install Java
+
+Obviously, JDK has to be installed. Cayenne 4.0 requires JDK 1.7 or newer.
+
+=== Install IntelliJ IDEA
+
+Download and install IntelliJ IDEA Community Edition.
+This tutorial is based on version 2016.3, still it should work with any recent IntelliJ IDEA version.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/_getting-started-guide/starting-project.adoc
----------------------------------------------------------------------
diff --git a/docs/asciidoc/getting-started-guide/src/docs/asciidoc/_getting-started-guide/starting-project.adoc b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/_getting-started-guide/starting-project.adoc
new file mode 100644
index 0000000..1e041e4
--- /dev/null
+++ b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/_getting-started-guide/starting-project.adoc
@@ -0,0 +1,111 @@
+// 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.
+=== Starting a project
+
+The goal of this chapter is to create a new Java project in IntelliJ IDEA
+containing a basic Cayenne mapping. It presents an introduction to
+CayenneModeler GUI tool, showing how to create the initial mapping
+objects: `DataDomain`, `DataNode`, `DataMap`.
+
+==== Create a new Project in IntelliJ IDEA
+
+In IntelliJ IDEA select `File > New > Project..` and then
+select `Maven` and click `Next`.
+In the dialog shown on the screenshot below, fill the `Group Id`
+and `Artifact Id` fields and click `Next`.
+
+image::tutorial-idea-project.png[align="center"]
+
+On next dialog screen you can customize directory for your project and click `Finish`.
+Now you should have a new empty project.
+
+==== Download and Start CayenneModeler
+
+Although later in this tutorial we'll be using Maven to include Cayenne
+runtime jars in the project, you'll still need to download Cayenne to
+get access to the CayenneModeler tool.
+
+NOTE: If you are really into Maven, you can start CayenneModeler from Maven too.
+ We'll do it in a more traditional way here.
+
+Download the http://cayenne.apache.org/download.html[latest release]. Unpack the distribution
+somewhere in the file system and start CayenneModeler, following platform-specific instructions.
+On most platforms it is done simply by doubleclicking the Modeler icon.
+The welcome screen of the Modeler looks like this:
+
+image::modeler-started.png[align="center"]
+
+==== Create a New Mapping Project in CayenneModeler
+
+Click on the `New Project` button on Welcome screen. A new mapping project will appear
+that contains a single *DataDomain*. The meaning of a
+DataDomain is explained elsewhere in the User Guide. For now it is sufficient to
+understand that DataDomain is the root of your mapping project.
+
+==== Create a DataNode
+
+The next project object you will create is a *DataNode*.
+DataNode is a descriptor of a single database your application
+will connect to. Cayenne mapping project can use more than one database, but for now,
+we'll only use one. With "project" selected on the left, click on `Create DataNode` button image:icon-node.png[]
+on the toolbar (or select `Project > Create DataNode` from the menu).
+
+A new DataNode is displayed. Now you need to specify JDBC connection parameters. For
+an in-memory Derby database you can enter the following settings:
+
+- JDBC Driver: org.apache.derby.jdbc.EmbeddedDriver
+- DB URL: jdbc:derby:memory:testdb;create=true
+
+NOTE: We are creating an in-memory database here. So when
+ you stop your application, all the data will be lost. In most real-life
+ cases you'll be connecting to a database that actually persists its data on
+ disk, but an in-memory DB will do for the simple tutorial.
+
+Also you will need to change "Schema Update Strategy". Select
+`org.apache.cayenne.access.dbsync.CreateIfNoSchemaStrategy` from the dropdown, so that
+Cayenne creates a new schema on Derby based on the ORM mapping when the application
+starts.
+
+image::base-datanode.png[align="center"]
+
+==== Create a DataMap
+
+Now you will create a *DataMap*. DataMap is an object
+that holds all the mapping information. To create it, click on "Create DataMap" button
+image:icon-datamap.png[] (or select a corresponding menu item).
+Note that the newly created DataMap is automatically linked to the DataNode that you created in
+the previous step. If there is more than one DataNode, you may need to link a DataMap
+to the correct node manually. In other words a DataMap within DataDomain must point
+to a database described by the map.
+
+You can leave all the DataMap defaults unchanged except for one - "Java Package".
+Enter `org.example.cayenne.persistent`. This name will later be used for all persistent
+classes.
+
+image::base-datamap.png[align="center"]
+
+==== Save the Project
+
+image::idea-xmlfiles.png[float="right"]
+
+Before you proceed with the actual mapping, let's save the project. Click on "Save"
+button in the toolbar and navigate to the `tutorial` IDEA project folder that was
+created earlier in this section and its `src/main/resources` subfolder and save the
+project there. Now go back to IDEA and you will see two Cayenne XML files.
+
+Note that the location of the XML files is not coincidental. Cayenne runtime looks for
+`cayenne-*.xml` file in the application `CLASSPATH` and `src/main/resources` folder should
+already be a "class folder" in IDEA for our project (and is also a standard location
+that Maven would copy to a jar file, if we were using Maven from command-line).
+
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/_getting-started-guide/webapp.adoc
----------------------------------------------------------------------
diff --git a/docs/asciidoc/getting-started-guide/src/docs/asciidoc/_getting-started-guide/webapp.adoc b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/_getting-started-guide/webapp.adoc
new file mode 100644
index 0000000..2b7d930
--- /dev/null
+++ b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/_getting-started-guide/webapp.adoc
@@ -0,0 +1,280 @@
+// 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.
+== Converting to Web Application
+This chapter shows how to work with Cayenne in a web application.
+
+=== Converting Tutorial to a Web Application
+The web part of the web application tutorial is done in JSP, which is the least common
+denominator of the Java web technologies, and is intentionally simplistic from the UI
+perspective, to concentrate on Cayenne integration aspect, rather than the interface. A
+typical Cayenne web application works like this:
+
+- Cayenne configuration is loaded when an application context is started, using a special servlet filter.
+- User requests are intercepted by the filter, and the DataContext is bound to
+the request thread, so the application can access it easily from anywhere.
+- The same DataContext instance is reused within a single user session;
+different sessions use different DataContexts (and therefore different sets of
+objects). _The context can be scoped differently
+depending on the app specifics. For the tutorial we'll be using a
+session-scoped context._
+
+So let's convert the tutorial that we created to a web application:
+
+- In IDEA under "tutorial" project folder create a new folder `src/main/webapp/WEB-INF`.
+- Under `WEB-INF` create a new file `web.xml` (a standard web app descriptor):
+
+.web.xml
+[source,xml]
+----
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE web-app
+ PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
+ "http://java.sun.com/dtd/web-app_2_3.dtd">
+<web-app>
+ <display-name>Cayenne Tutorial</display-name>
+
+ <!-- This filter bootstraps ServerRuntime and then provides each request thread
+ with a session-bound DataContext. Note that the name of the filter is important,
+ as it points it to the right named configuration file.
+ -->
+ <filter>
+ <filter-name>cayenne-project</filter-name>
+ <filter-class>org.apache.cayenne.configuration.web.CayenneFilter</filter-class>
+ </filter>
+ <filter-mapping>
+ <filter-name>cayenne-project</filter-name>
+ <url-pattern>/*</url-pattern>
+ </filter-mapping>
+ <welcome-file-list>
+ <welcome-file>index.jsp</welcome-file>
+ </welcome-file-list>
+</web-app>
+----
+
+- Create the artist browser page `src/main/webapp/index.jsp` file with the following contents:
+
+.webapp/index.jsp
+[source,jsp]
+----
+<%@ page language="java" contentType="text/html" %>
+<%@ page import="org.example.cayenne.persistent.*" %>
+<%@ page import="org.apache.cayenne.*" %>
+<%@ page import="org.apache.cayenne.query.*" %>
+<%@ page import="org.apache.cayenne.exp.*" %>
+<%@ page import="java.util.*" %>
+
+<%
+ ObjectContext context = BaseContext.getThreadObjectContext();
+ List<Artist> artists = ObjectSelect.query(Artist.class)
+ .orderBy(Artist.NAME.asc())
+ .select(context);
+%>
+
+<html>
+ <head>
+ <title>Main</title>
+ </head>
+ <body>
+ <h2>Artists:</h2>
+
+ <% if(artists.isEmpty()) {%>
+ <p>No artists found</p>
+ <% } else {
+ for(Artist a : artists) {
+ %>
+ <p><a href="detail.jsp?id=<%=Cayenne.intPKForObject(a)%>"> <%=a.getName()%> </a></p>
+ <%
+ }
+ } %>
+ <hr>
+ <p><a href="detail.jsp">Create new artist...</a></p>
+ </body>
+</html>
+----
+
+- Create the artist editor page `src/main/webapp/detail.jsp` with the following content:
+
+.webapp/detail.jsp
+[source,jsp]
+----
+<%@ page language="java" contentType="text/html" %>
+<%@ page import="org.example.cayenne.persistent.*" %>
+<%@ page import="org.apache.cayenne.*" %>
+<%@ page import="org.apache.cayenne.query.*" %>
+<%@ page import="java.util.*" %>
+<%@ page import="java.text.*" %>
+<%@ page import="java.time.format.DateTimeFormatter" %>
+
+<%
+ ObjectContext context = BaseContext.getThreadObjectContext();
+ String id = request.getParameter("id");
+
+ // find artist for id
+ Artist artist = null;
+ if(id != null && id.trim().length() > 0) {
+ artist = SelectById.query(Artist.class, Integer.parseInt(id)).selectOne(context);
+ }
+
+ if("POST".equals(request.getMethod())) {
+ // if no id is saved in the hidden field, we are dealing with
+ // create new artist request
+ if(artist == null) {
+ artist = context.newObject(Artist.class);
+ }
+
+ // note that in a real application we would so dome validation ...
+ // here we just hope the input is correct
+ artist.setName(request.getParameter("name"));
+ artist.setDateOfBirthString(request.getParameter("dateOfBirth"));
+
+ context.commitChanges();
+
+ response.sendRedirect("index.jsp");
+ }
+
+ if(artist == null) {
+ // create transient artist for the form response rendering
+ artist = new Artist();
+ }
+
+ String name = artist.getName() == null ? "" : artist.getName();
+
+ DateTimeFormatter formatter = DateTimeFormatter.ofPattern("yyyyMMdd");
+ String dob = artist.getDateOfBirth() == null
+ ? "" :artist.getDateOfBirth().format(formatter);
+%>
+<html>
+ <head>
+ <title>Artist Details</title>
+ </head>
+ <body>
+ <h2>Artists Details</h2>
+ <form name="EditArtist" action="detail.jsp" method="POST">
+ <input type="hidden" name="id" value="<%= id != null ? id : "" %>" />
+ <table border="0">
+ <tr>
+ <td>Name:</td>
+ <td><input type="text" name="name" value="<%= name %>"/></td>
+ </tr>
+ <tr>
+ <td>Date of Birth (yyyyMMdd):</td>
+ <td><input type="text" name="dateOfBirth" value="<%= dob %>"/></td>
+ </tr>
+ <tr>
+ <td></td>
+ <td align="right"><input type="submit" value="Save" /></td>
+ </tr>
+ </table>
+ </form>
+ </body>
+</html>
+----
+
+==== Running Web Application
+We need to provide javax servlet-api for our application.
+
+.pom.xml
+[source,xml]
+----
+<dependency>
+ <groupId>javax.servlet</groupId>
+ <artifactId>javax.servlet-api</artifactId>
+ <version>3.1.0</version>
+ <scope>provided</scope>
+</dependency>
+----
+
+Also to run the web application we'll use "maven-jetty-plugin". To activate it,
+let's add the following piece of code to the `pom.xml` file, following the "dependencies"
+section and save the POM:
+
+.pom.xml
+[source,xml]
+----
+<build>
+ <plugins>
+ <plugin>
+ <groupId>org.eclipse.jetty</groupId>
+ <artifactId>jetty-maven-plugin</artifactId>
+ <version>9.3.14.v20161028</version>
+ </plugin>
+ </plugins>
+</build>
+----
+
+- Go to "Select Run/Debug Configuration" menu, and then "Edit Configuration..."
+
+image::idea-edit-configurations.png[align="center"]
+
+
+- Click `+` button and select "Maven". Enter "Name" and "Command line" as shown on screenshot:
+
+image:idea-run-configuration.png[]
+
+- Click "Apply" and "Run". On the first execution it may take a few minutes for
+Jetty plugin to download all dependencies, but eventually you'll see the logs
+like this:
+
+ [INFO] ------------------------------------------------------------------------
+ [INFO] Building tutorial 0.0.1-SNAPSHOT
+ [INFO] ------------------------------------------------------------------------
+ ...
+ [INFO] Configuring Jetty for project: tutorial
+ [INFO] webAppSourceDirectory not set. Trying src/main/webapp
+ [INFO] Reload Mechanic: automatic
+ [INFO] Classes = /.../tutorial/target/classes
+ [INFO] Logging initialized @1617ms
+ [INFO] Context path = /
+ [INFO] Tmp directory = /.../tutorial/target/tmp
+ [INFO] Web defaults = org/eclipse/jetty/webapp/webdefault.xml
+ [INFO] Web overrides = none
+ [INFO] web.xml file = file:/.../tutorial/src/main/webapp/WEB-INF/web.xml
+ [INFO] Webapp directory = /.../tutorial/src/main/webapp
+ [INFO] jetty-9.3.0.v20150612
+ [INFO] Started o.e.j.m.p.JettyWebAppContext@6872f9c8{/,file:/.../tutorial/src/main/webapp/,AVAILABLE}{file:/.../tutorial/src/main/webapp/}
+ [INFO] Started ServerConnector@723875bc{HTTP/1.1,[http/1.1]}{0.0.0.0:8080}
+ [INFO] Started @2367ms
+ [INFO] Started Jetty Server</screen>
+
+- So the Jetty container just started.
+
+- Now go to http://localhost:8080/ URL. You should see "No artists found message" in the web browser and
+the following output in the IDEA console:
+
+ INFO: Loading XML configuration resource from file:/.../tutorial/target/classes/cayenne-project.xml
+ INFO: loading user name and password.
+ INFO: Connecting to 'jdbc:derby:memory:testdb;create=true' as 'null'
+ INFO: +++ Connecting: SUCCESS.
+ INFO: setting DataNode 'datanode' as default, used by all unlinked DataMaps
+ INFO: Detected and installed adapter: org.apache.cayenne.dba.derby.DerbyAdapter
+ INFO: --- transaction started.
+ INFO: No schema detected, will create mapped tables
+ INFO: CREATE TABLE GALLERY (ID INTEGER NOT NULL, NAME VARCHAR (200), PRIMARY KEY (ID))
+ INFO: CREATE TABLE ARTIST (DATE_OF_BIRTH DATE, ID INTEGER NOT NULL, NAME VARCHAR (200), PRIMARY KEY (ID))
+ INFO: CREATE TABLE PAINTING (ARTIST_ID INTEGER, GALLERY_ID INTEGER, ID INTEGER NOT NULL,
+ NAME VARCHAR (200), PRIMARY KEY (ID))
+ INFO: ALTER TABLE PAINTING ADD FOREIGN KEY (ARTIST_ID) REFERENCES ARTIST (ID)
+ INFO: ALTER TABLE PAINTING ADD FOREIGN KEY (GALLERY_ID) REFERENCES GALLERY (ID)
+ INFO: CREATE TABLE AUTO_PK_SUPPORT (
+ TABLE_NAME CHAR(100) NOT NULL, NEXT_ID BIGINT NOT NULL, PRIMARY KEY(TABLE_NAME))
+ ...
+ INFO: SELECT t0.DATE_OF_BIRTH, t0.NAME, t0.ID FROM ARTIST t0 ORDER BY t0.NAME
+ INFO: === returned 0 rows. - took 17 ms.
+ INFO: +++ transaction committed.</screen>
+
+- You can click on "Create new artist" link to create artists. Existing artists can be edited by clicking on their name:
+
+image::chrome-webapp.png[align="center"]
+
+You are done with the tutorial!
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/getting-started-guide.adoc
----------------------------------------------------------------------
diff --git a/docs/asciidoc/getting-started-guide/src/docs/asciidoc/getting-started-guide.adoc b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/getting-started-guide.adoc
new file mode 100644
index 0000000..dc0d2ea
--- /dev/null
+++ b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/getting-started-guide.adoc
@@ -0,0 +1,48 @@
+// 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.
+= Getting Started with Cayenne
+:revnumber: {project-major-version} ({project-version})
+// enable section numbering, limiting depth to 2
+:sectnums:
+:sectnumlevels: 2
+// use custom header
+:cayenne-header: _getting-started-guide/header.html
+:cayenne-header-position: body
+// customize final layout
+//:linkcss:
+// base path to java code include
+:cayenne-root: {basedir}/../../..
+:java-include-dir: {cayenne-root}/tutorials/tutorial/src/main/java/org/apache/cayenne/tutorial
+:web-include-dir: {cayenne-root}/tutorials/tutorial/src/main/java/org/apache/cayenne/tutorial
+
+[small]#Copyright © 2011-2017 Apache Software Foundation and individual authors#
+
+.License
+[small]#_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_#
+
+[small]#_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._#
+
+include::_getting-started-guide/setup.adoc[]
+
+include::_getting-started-guide/part2.adoc[]
+
+include::_getting-started-guide/part3.adoc[]
+
+include::_getting-started-guide/webapp.adoc[]
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/images/base-datamap.png
----------------------------------------------------------------------
diff --git a/docs/asciidoc/getting-started-guide/src/docs/asciidoc/images/base-datamap.png b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/images/base-datamap.png
new file mode 100644
index 0000000..a12bc01
Binary files /dev/null and b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/images/base-datamap.png differ
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/images/base-datanode.png
----------------------------------------------------------------------
diff --git a/docs/asciidoc/getting-started-guide/src/docs/asciidoc/images/base-datanode.png b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/images/base-datanode.png
new file mode 100644
index 0000000..69939bb
Binary files /dev/null and b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/images/base-datanode.png differ
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/images/cayenne-tutorial-model.png
----------------------------------------------------------------------
diff --git a/docs/asciidoc/getting-started-guide/src/docs/asciidoc/images/cayenne-tutorial-model.png b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/images/cayenne-tutorial-model.png
new file mode 100644
index 0000000..454d198
Binary files /dev/null and b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/images/cayenne-tutorial-model.png differ
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/images/chrome-webapp.png
----------------------------------------------------------------------
diff --git a/docs/asciidoc/getting-started-guide/src/docs/asciidoc/images/chrome-webapp.png b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/images/chrome-webapp.png
new file mode 100644
index 0000000..603e1df
Binary files /dev/null and b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/images/chrome-webapp.png differ
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/images/database-schema.jpg
----------------------------------------------------------------------
diff --git a/docs/asciidoc/getting-started-guide/src/docs/asciidoc/images/database-schema.jpg b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/images/database-schema.jpg
new file mode 100644
index 0000000..9d4ee21
Binary files /dev/null and b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/images/database-schema.jpg differ
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/images/icon-attribute.png
----------------------------------------------------------------------
diff --git a/docs/asciidoc/getting-started-guide/src/docs/asciidoc/images/icon-attribute.png b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/images/icon-attribute.png
new file mode 100755
index 0000000..77a68eb
Binary files /dev/null and b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/images/icon-attribute.png differ
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/images/icon-datamap.png
----------------------------------------------------------------------
diff --git a/docs/asciidoc/getting-started-guide/src/docs/asciidoc/images/icon-datamap.png b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/images/icon-datamap.png
new file mode 100755
index 0000000..2ea96ca
Binary files /dev/null and b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/images/icon-datamap.png differ
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/images/icon-dbentity.png
----------------------------------------------------------------------
diff --git a/docs/asciidoc/getting-started-guide/src/docs/asciidoc/images/icon-dbentity.png b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/images/icon-dbentity.png
new file mode 100755
index 0000000..87d9d8a
Binary files /dev/null and b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/images/icon-dbentity.png differ
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/images/icon-edit.png
----------------------------------------------------------------------
diff --git a/docs/asciidoc/getting-started-guide/src/docs/asciidoc/images/icon-edit.png b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/images/icon-edit.png
new file mode 100755
index 0000000..027c482
Binary files /dev/null and b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/images/icon-edit.png differ
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/images/icon-new_objentity.png
----------------------------------------------------------------------
diff --git a/docs/asciidoc/getting-started-guide/src/docs/asciidoc/images/icon-new_objentity.png b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/images/icon-new_objentity.png
new file mode 100755
index 0000000..8735d7a
Binary files /dev/null and b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/images/icon-new_objentity.png differ
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/images/icon-node.png
----------------------------------------------------------------------
diff --git a/docs/asciidoc/getting-started-guide/src/docs/asciidoc/images/icon-node.png b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/images/icon-node.png
new file mode 100755
index 0000000..2ff4383
Binary files /dev/null and b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/images/icon-node.png differ
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/images/icon-relationship.png
----------------------------------------------------------------------
diff --git a/docs/asciidoc/getting-started-guide/src/docs/asciidoc/images/icon-relationship.png b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/images/icon-relationship.png
new file mode 100755
index 0000000..44ed7eb
Binary files /dev/null and b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/images/icon-relationship.png differ
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/images/icon-sync.png
----------------------------------------------------------------------
diff --git a/docs/asciidoc/getting-started-guide/src/docs/asciidoc/images/icon-sync.png b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/images/icon-sync.png
new file mode 100755
index 0000000..03e8623
Binary files /dev/null and b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/images/icon-sync.png differ
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/images/idea-edit-configurations.png
----------------------------------------------------------------------
diff --git a/docs/asciidoc/getting-started-guide/src/docs/asciidoc/images/idea-edit-configurations.png b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/images/idea-edit-configurations.png
new file mode 100644
index 0000000..df1d524
Binary files /dev/null and b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/images/idea-edit-configurations.png differ
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/images/idea-file-run-menu.png
----------------------------------------------------------------------
diff --git a/docs/asciidoc/getting-started-guide/src/docs/asciidoc/images/idea-file-run-menu.png b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/images/idea-file-run-menu.png
new file mode 100644
index 0000000..30cf05e
Binary files /dev/null and b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/images/idea-file-run-menu.png differ
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/images/idea-generated-classes.png
----------------------------------------------------------------------
diff --git a/docs/asciidoc/getting-started-guide/src/docs/asciidoc/images/idea-generated-classes.png b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/images/idea-generated-classes.png
new file mode 100644
index 0000000..504dce5
Binary files /dev/null and b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/images/idea-generated-classes.png differ
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/images/idea-run-configuration.png
----------------------------------------------------------------------
diff --git a/docs/asciidoc/getting-started-guide/src/docs/asciidoc/images/idea-run-configuration.png b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/images/idea-run-configuration.png
new file mode 100644
index 0000000..3ebbb62
Binary files /dev/null and b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/images/idea-run-configuration.png differ
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/images/idea-xmlfiles.png
----------------------------------------------------------------------
diff --git a/docs/asciidoc/getting-started-guide/src/docs/asciidoc/images/idea-xmlfiles.png b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/images/idea-xmlfiles.png
new file mode 100644
index 0000000..1b4707d
Binary files /dev/null and b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/images/idea-xmlfiles.png differ
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/images/modeler-artistid.png
----------------------------------------------------------------------
diff --git a/docs/asciidoc/getting-started-guide/src/docs/asciidoc/images/modeler-artistid.png b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/images/modeler-artistid.png
new file mode 100644
index 0000000..fb8c1dd
Binary files /dev/null and b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/images/modeler-artistid.png differ
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/images/modeler-dbrelationship.png
----------------------------------------------------------------------
diff --git a/docs/asciidoc/getting-started-guide/src/docs/asciidoc/images/modeler-dbrelationship.png b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/images/modeler-dbrelationship.png
new file mode 100644
index 0000000..4b23eb5
Binary files /dev/null and b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/images/modeler-dbrelationship.png differ
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/images/modeler-deleterule.png
----------------------------------------------------------------------
diff --git a/docs/asciidoc/getting-started-guide/src/docs/asciidoc/images/modeler-deleterule.png b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/images/modeler-deleterule.png
new file mode 100644
index 0000000..86ada13
Binary files /dev/null and b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/images/modeler-deleterule.png differ
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/images/modeler-started.png
----------------------------------------------------------------------
diff --git a/docs/asciidoc/getting-started-guide/src/docs/asciidoc/images/modeler-started.png b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/images/modeler-started.png
new file mode 100644
index 0000000..dbf8324
Binary files /dev/null and b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/images/modeler-started.png differ
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/images/tutorial-idea-project.png
----------------------------------------------------------------------
diff --git a/docs/asciidoc/getting-started-guide/src/docs/asciidoc/images/tutorial-idea-project.png b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/images/tutorial-idea-project.png
new file mode 100644
index 0000000..058dc1d
Binary files /dev/null and b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/images/tutorial-idea-project.png differ
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/var.adoc
----------------------------------------------------------------------
diff --git a/docs/asciidoc/getting-started-guide/src/docs/asciidoc/var.adoc b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/var.adoc
new file mode 100644
index 0000000..e575eda
--- /dev/null
+++ b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/var.adoc
@@ -0,0 +1 @@
+:version: {project-version}
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/asciidoc/getting-started-rop/pom.xml
----------------------------------------------------------------------
diff --git a/docs/asciidoc/getting-started-rop/pom.xml b/docs/asciidoc/getting-started-rop/pom.xml
new file mode 100644
index 0000000..fca4548
--- /dev/null
+++ b/docs/asciidoc/getting-started-rop/pom.xml
@@ -0,0 +1,151 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+ <parent>
+ <artifactId>cayenne-asciidoc-parent</artifactId>
+ <groupId>org.apache.cayenne.docs</groupId>
+ <version>4.0.B3-SNAPSHOT</version>
+ </parent>
+ <modelVersion>4.0.0</modelVersion>
+
+ <artifactId>getting-started-rop</artifactId>
+
+ <packaging>jar</packaging>
+ <name>getting-started-rop: AsciiDoc - Getting Started with Cayenne ROP (Remote Object Persistence)</name>
+
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.asciidoctor</groupId>
+ <artifactId>asciidoctor-maven-plugin</artifactId>
+ <dependencies>
+ <dependency>
+ <groupId>org.apache.cayenne.docs</groupId>
+ <artifactId>cayenne-asciidoc-extension</artifactId>
+ <version>${project.version}</version>
+ </dependency>
+ </dependencies>
+
+ <executions>
+ <!-- generate "embeddable" html content with front matter and without header/footer/styles -->
+ <execution>
+ <id>asciidoctor-html-web</id>
+ <phase>generate-resources</phase>
+ <goals>
+ <goal>process-asciidoc</goal>
+ </goals>
+ <configuration>
+ <backend>html5</backend>
+ <headerFooter>false</headerFooter> <!-- do not generate header and footer -->
+ <outputDirectory>${project.build.directory}/tmp/</outputDirectory>
+ <extensions>
+ <extension>
+ <className>org.apache.cayenne.asciidoc.CayennePostProcessor</className>
+ </extension>
+ </extensions>
+ <attributes>
+ <toc>auto</toc>
+ </attributes>
+ </configuration>
+ </execution>
+ </executions>
+ </plugin>
+
+ <!-- Move images to proper path for site -->
+ <plugin>
+ <artifactId>maven-resources-plugin</artifactId>
+ <executions>
+ <execution>
+ <id>copy docs for site</id>
+ <phase>install</phase>
+ <goals>
+ <goal>copy-resources</goal>
+ </goals>
+
+ <configuration>
+ <outputDirectory>${project.build.directory}/site/</outputDirectory>
+ <resources>
+ <resource>
+ <directory>${project.build.directory}/tmp/</directory>
+ <includes>
+ <include>${project.artifactId}.html</include>
+ <include>${project.artifactId}.toc.html</include>
+ </includes>
+ </resource>
+ </resources>
+ </configuration>
+ </execution>
+
+ <execution>
+ <id>copy images for site</id>
+ <phase>install</phase>
+ <goals>
+ <goal>copy-resources</goal>
+ </goals>
+
+ <configuration>
+ <outputDirectory>${project.build.directory}/site/${project.artifactId}/images/</outputDirectory>
+ <resources>
+ <resource>
+ <directory>${project.build.directory}/tmp/images/</directory>
+ <filtering>true</filtering>
+ </resource>
+ </resources>
+ </configuration>
+ </execution>
+ </executions>
+ </plugin>
+ </plugins>
+ </build>
+
+ <profiles>
+ <profile>
+ <id>assembly</id>
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.asciidoctor</groupId>
+ <artifactId>asciidoctor-maven-plugin</artifactId>
+ <executions>
+ <!-- generate standalone html help -->
+ <execution>
+ <id>asciidoctor-html-standalone</id>
+ <phase>generate-resources</phase>
+ <goals>
+ <goal>process-asciidoc</goal>
+ </goals>
+ <configuration>
+ <backend>html5</backend>
+ <sourceHighlighter>coderay</sourceHighlighter>
+ <embedAssets>true</embedAssets>
+ <attributes>
+ <toc>left</toc>
+ </attributes>
+ </configuration>
+ </execution>
+
+ <!-- generate PDF -->
+ <execution>
+ <id>generate-pdf-doc</id>
+ <phase>generate-resources</phase>
+ <goals>
+ <goal>process-asciidoc</goal>
+ </goals>
+ <configuration>
+ <backend>pdf</backend>
+ <sourceHighlighter>coderay</sourceHighlighter>
+ <attributes>
+ <pagenums/>
+ <toc/>
+ </attributes>
+ </configuration>
+ </execution>
+ </executions>
+ </plugin>
+ </plugins>
+ </build>
+ </profile>
+ </profiles>
+
+</project>
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/asciidoc/getting-started-rop/src/docs/asciidoc/_getting-started-rop/header.html
----------------------------------------------------------------------
diff --git a/docs/asciidoc/getting-started-rop/src/docs/asciidoc/_getting-started-rop/header.html b/docs/asciidoc/getting-started-rop/src/docs/asciidoc/_getting-started-rop/header.html
new file mode 100644
index 0000000..516fe0b
--- /dev/null
+++ b/docs/asciidoc/getting-started-rop/src/docs/asciidoc/_getting-started-rop/header.html
@@ -0,0 +1,24 @@
+---
+# 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.
+
+title: "Cayenne Getting Started ROP"
+description: "Tutorial how to quick start new Cayenne ROP project"
+cayenneVersion: "4.0"
+docsMenuTitle: "Getting Started ROP"
+weight: 40
+---
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/asciidoc/getting-started-rop/src/docs/asciidoc/_getting-started-rop/part1.adoc
----------------------------------------------------------------------
diff --git a/docs/asciidoc/getting-started-rop/src/docs/asciidoc/_getting-started-rop/part1.adoc b/docs/asciidoc/getting-started-rop/src/docs/asciidoc/_getting-started-rop/part1.adoc
new file mode 100644
index 0000000..384f927
--- /dev/null
+++ b/docs/asciidoc/getting-started-rop/src/docs/asciidoc/_getting-started-rop/part1.adoc
@@ -0,0 +1,17 @@
+// 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.
+
+== Prerequisites
+
+include::part1/prerequisites.adoc[]
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/asciidoc/getting-started-rop/src/docs/asciidoc/_getting-started-rop/part1/prerequisites.adoc
----------------------------------------------------------------------
diff --git a/docs/asciidoc/getting-started-rop/src/docs/asciidoc/_getting-started-rop/part1/prerequisites.adoc b/docs/asciidoc/getting-started-rop/src/docs/asciidoc/_getting-started-rop/part1/prerequisites.adoc
new file mode 100644
index 0000000..22587e0
--- /dev/null
+++ b/docs/asciidoc/getting-started-rop/src/docs/asciidoc/_getting-started-rop/part1/prerequisites.adoc
@@ -0,0 +1,25 @@
+// 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.
+
+=== Prerequisites
+
+This tutorial starts where "Getting Started with Cayenne" left off. If you have gone through the previous tutorial, and have the "tutorial" project open in Eclipse, you can go directly to the next step. If not, here are the compressed instructions to prepare you for work with ROP:
+
+* Step 1 - Eclipse Setup
+* Step 2 - Create a project
+* Step 3 - Create Cayenne OR Mapping
+* Step 4 - Create Java Classes
+* Step 5 - Convert the project to webapp.
+
+Note that at "Step 5" you can skip the JSP creation part. Just setup web.xml and maven-jetty-plugin in the POM.
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/asciidoc/getting-started-rop/src/docs/asciidoc/_getting-started-rop/part2.adoc
----------------------------------------------------------------------
diff --git a/docs/asciidoc/getting-started-rop/src/docs/asciidoc/_getting-started-rop/part2.adoc b/docs/asciidoc/getting-started-rop/src/docs/asciidoc/_getting-started-rop/part2.adoc
new file mode 100644
index 0000000..0f2c23a
--- /dev/null
+++ b/docs/asciidoc/getting-started-rop/src/docs/asciidoc/_getting-started-rop/part2.adoc
@@ -0,0 +1,23 @@
+// 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.
+
+== Remote Object Persistence Quick Start
+
+include::part2/starting.adoc[]
+
+include::part2/hessianWebServ.adoc[]
+
+include::part2/connect.adoc[]
+
+include::part2/adding.adoc[]
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/asciidoc/getting-started-rop/src/docs/asciidoc/_getting-started-rop/part2/adding.adoc
----------------------------------------------------------------------
diff --git a/docs/asciidoc/getting-started-rop/src/docs/asciidoc/_getting-started-rop/part2/adding.adoc b/docs/asciidoc/getting-started-rop/src/docs/asciidoc/_getting-started-rop/part2/adding.adoc
new file mode 100644
index 0000000..c9a86a4
--- /dev/null
+++ b/docs/asciidoc/getting-started-rop/src/docs/asciidoc/_getting-started-rop/part2/adding.adoc
@@ -0,0 +1,126 @@
+// 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.
+
+=== Adding BASIC Authentication
+
+You probably don't want everybody in the world to connect to your service and access (and update!) arbitrary data in the database. The first step in securing Cayenne service is implementing client authentication. The easiest way to do it is to delegate the authentication task to the web container that is running the service. HessianConnection used in the previous chapter supports BASIC authentication on the client side, so we'll demonstrate how to set it up here.
+
+==== Securing ROP Server Application
+
+Open web.xml file in the server project and setup security constraints with BASIC authentication for the ROP service:
+
+[source, XML]
+----
+<security-constraint>
+ <web-resource-collection>
+ <web-resource-name>CayenneService</web-resource-name>
+ <url-pattern>/cayenne-service</url-pattern>
+ </web-resource-collection>
+ <auth-constraint>
+ <role-name>cayenne-service-user</role-name>
+ </auth-constraint>
+</security-constraint>
+
+<login-config>
+ <auth-method>BASIC</auth-method>
+ <realm-name>Cayenne Realm</realm-name>
+</login-config>
+
+<security-role>
+ <role-name>cayenne-service-user</role-name>
+</security-role>
+----
+
+==== Configuring Jetty for BASIC Authentication
+
+NOTE: These instructions are specific to Jetty 6. Other containers (and versions of Jetty) will have different mechansims to achieve the same thing.
+
+Open pom.xml in the server project and configure a "userRealm" for the Jetty plugin:
+
+[source, XML]
+----
+<plugin>
+ <groupId>org.mortbay.jetty</groupId>
+ <artifactId>maven-jetty-plugin</artifactId>
+ <version>6.1.22</version>
+ <!-- adding configuration below: -->
+ <configuration>
+ <userRealms>
+ <userRealm implementation="org.mortbay.jetty.security.HashUserRealm">
+ <!-- this name must match the realm-name in web.xml -->
+ <name>Cayenne Realm</name>
+ <config>realm.properties</config>
+ </userRealm>
+ </userRealms>
+ </configuration>
+ </plugin>
+</plugins>
+----
+
+Now create a new file called {["realm.properties"}} at the root of the server project and put user login/password in there:
+
+[source]
+----
+cayenne-user: secret,cayenne-service-user
+----
+
+Now let's stop the server and start it again. Everything should start as before, but if you go to http://localhost:8080/tutorial/cayenne-service, your browser should pop up authentication dialog. Enter "cayenne-user/secret" for user name / password, and you should see "Hessian Requires POST" message. So the server is now secured.
+
+==== Running Client with Basic Authentication
+
+If you run the client without any changes, you'll get the following error:
+
+[source]
+----
+Mar 01, 2016 7:25:50 PM org.apache.cayenne.rop.http.HttpROPConnector logConnect
+INFO: Connecting to [cayenne-user@http://localhost:8080/tutorial-rop-server/cayenne-service] - dedicated session.
+Mar 01, 2016 7:25:50 PM org.apache.cayenne.rop.HttpClientConnection connect
+INFO: Server returned HTTP response code: 401 for URL: http://localhost:8080/tutorial-rop-server/cayenne-service
+java.rmi.RemoteException: Server returned HTTP response code: 401 for URL: http://localhost:8080/tutorial-rop-server/cayenne-service
+ at org.apache.cayenne.rop.ProxyRemoteService.establishSession(ProxyRemoteService.java:45)
+ at org.apache.cayenne.rop.HttpClientConnection.connect(HttpClientConnection.java:85)
+ at org.apache.cayenne.rop.HttpClientConnection.getServerEventBridge(HttpClientConnection.java:68)
+ at org.apache.cayenne.remote.ClientChannel.setupRemoteChannelListener(ClientChannel.java:279)
+ at org.apache.cayenne.remote.ClientChannel.<init>(ClientChannel.java:71)
+ at org.apache.cayenne.configuration.rop.client.ClientChannelProvider.get(ClientChannelProvider.java:48)
+ at org.apache.cayenne.configuration.rop.client.ClientChannelProvider.get(ClientChannelProvider.java:31)
+ at org.apache.cayenne.di.spi.CustomProvidersProvider.get(CustomProvidersProvider.java:39)
+ at org.apache.cayenne.di.spi.FieldInjectingProvider.get(FieldInjectingProvider.java:43)
+ at org.apache.cayenne.di.spi.DefaultScopeProvider.get(DefaultScopeProvider.java:50)
+ at org.apache.cayenne.di.spi.DefaultInjector.getInstance(DefaultInjector.java:139)
+ at org.apache.cayenne.di.spi.FieldInjectingProvider.value(FieldInjectingProvider.java:105)
+ at org.apache.cayenne.di.spi.FieldInjectingProvider.injectMember(FieldInjectingProvider.java:68)
+ at org.apache.cayenne.di.spi.FieldInjectingProvider.injectMembers(FieldInjectingProvider.java:59)
+ at org.apache.cayenne.di.spi.FieldInjectingProvider.get(FieldInjectingProvider.java:44)
+ at org.apache.cayenne.di.spi.DefaultScopeProvider.get(DefaultScopeProvider.java:50)
+ at org.apache.cayenne.di.spi.DefaultInjector.getInstance(DefaultInjector.java:134)
+ at org.apache.cayenne.configuration.CayenneRuntime.newContext(CayenneRuntime.java:134)
+ at org.apache.cayenne.tutorial.persistent.client.Main.main(Main.java:44)
+----
+
+Which is exactly what you'd expect, as the client is not authenticating itself. So change the line in Main.java where we obtained an ROP connection to this:
+
+[source, java]
+----
+Map<String,String> properties = new HashMap<>();
+properties.put(Constants.ROP_SERVICE_URL_PROPERTY, "http://localhost:8080/tutorial/cayenne-service");
+properties.put(Constants.ROP_SERVICE_USERNAME_PROPERTY, "cayenne-user");
+properties.put(Constants.ROP_SERVICE_PASSWORD_PROPERTY, "secret");
+
+ClientRuntime runtime = new ClientRuntime(properties);
+----
+
+Try running again, and everything should work as before. Obviously in production environment, in addition to authentication you'll need to use HTTPS to access the server to prevent third-party eavesdropping on your password and data.
+
+Congratulations, you are done with the ROP tutorial!
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/asciidoc/getting-started-rop/src/docs/asciidoc/_getting-started-rop/part2/connect.adoc
----------------------------------------------------------------------
diff --git a/docs/asciidoc/getting-started-rop/src/docs/asciidoc/_getting-started-rop/part2/connect.adoc b/docs/asciidoc/getting-started-rop/src/docs/asciidoc/_getting-started-rop/part2/connect.adoc
new file mode 100644
index 0000000..284c7c3
--- /dev/null
+++ b/docs/asciidoc/getting-started-rop/src/docs/asciidoc/_getting-started-rop/part2/connect.adoc
@@ -0,0 +1,174 @@
+// 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.
+
+=== Porting Existing Code to Connect to a Web Service Instead of a Database
+
+==== Starting Command Line Client
+
+One of the benefits of ROP is that the client code is no different from the server code - it uses the same ObjectContext interface for access, same query and commit API. So the code below will be similar to the code presented in the first Cayenne Getting Started Guide, although with a few ROP-specific parts required to bootstrap the ObjectContext.
+
+Let's start by creating an empty Main class with the standard main() method in the client project:
+
+[source, java]
+----
+package org.example.cayenne.persistent.client;
+
+public class Main {
+
+ public static void main(String[] args) {
+
+ }
+}
+----
+
+Now the part that is actually different from regular Cayenne - establishing the server connection and obtaining the ObjectContext:
+
+[source, java]
+----
+Map<String, String> properties = new HashMap<>();
+properties.put(Constants.ROP_SERVICE_URL_PROPERTY, "http://localhost:8080/tutorial/cayenne-service");
+properties.put(Constants.ROP_SERVICE_USERNAME_PROPERTY, "cayenne-user");
+properties.put(Constants.ROP_SERVICE_PASSWORD_PROPERTY, "secret");
+
+ClientRuntime runtime = new ClientRuntime(properties);
+ObjectContext context = runtime.newContext();
+----
+
+Note that the "runtime" can be used to create as many peer ObjectContexts as needed over the same connection, while ObjectContext is a kind of isolated "persistence session", similar to the server-side context. A few more notes. Since we are using HTTP(S) to communicate with ROP server, there's no need to explicitly close the connection (or channel, or context).
+
+So now let's do the same persistent operaions that we did in the first tutorial "Main" class. Let's start by creating and saving some objects:
+
+[source, java]
+----
+// creating new Artist
+Artist picasso = context.newObject(Artist.class);
+picasso.setName("Pablo Picasso");
+
+// Creating other objects
+Gallery metropolitan = context.newObject(Gallery.class);
+metropolitan.setName("Metropolitan Museum of Art");
+
+Painting girl = context.newObject(Painting.class);
+girl.setName("Girl Reading at a Table");
+
+Painting stein = context.newObject(Painting.class);
+stein.setName("Gertrude Stein");
+
+// connecting objects together via relationships
+picasso.addToPaintings(girl);
+picasso.addToPaintings(stein);
+
+girl.setGallery(metropolitan);
+stein.setGallery(metropolitan);
+
+// saving all the changes above
+context.commitChanges();
+----
+
+Now let's select them back:
+
+[source, java]
+----
+// ObjectSelect examples
+List<Painting> paintings1 = ObjectSelect.query(Painting.class).select(context);
+
+List<Painting> paintings2 = ObjectSelect.query(Painting.class)
+ .where(Painting.NAME.likeIgnoreCase("gi%")).select(context);
+----
+
+Now, delete:
+
+[source, java]
+----
+// Delete object example
+Artist picasso = ObjectSelect.query(Artist.class).where(Artist.NAME.eq("Pablo Picasso")).selectOne(context);
+
+if (picasso != null) {
+ context.deleteObject(picasso);
+ context.commitChanges();
+}
+----
+
+This code is exactly the same as in the first tutorial. So now let's try running the client and see what happens. In Eclipse open main class and select "Run > Run As > Java Application" from the menu (assuming the ROP server started in the previous step is still running). You will some output in both server and client process consoles. Client:
+
+[source]
+----
+INFO: Connecting to [http://localhost:8080/tutorial/cayenne-service] - dedicated session.
+INFO: === Connected, session: org.apache.cayenne.remote.RemoteSession@26544ec1[sessionId=17uub1h34r9x1] - took 111 ms.
+INFO: --- Message 0: Bootstrap
+INFO: === Message 0: Bootstrap done - took 58 ms.
+INFO: --- Message 1: flush-cascade-sync
+INFO: === Message 1: flush-cascade-sync done - took 1119 ms.
+INFO: --- Message 2: Query
+INFO: === Message 2: Query done - took 48 ms.
+INFO: --- Message 3: Query
+INFO: === Message 3: Query done - took 63 ms.
+INFO: --- Message 4: Query
+INFO: === Message 4: Query done - took 19 ms.
+INFO: --- Message 5: Query
+INFO: === Message 5: Query done - took 7 ms.
+INFO: --- Message 6: Query
+INFO: === Message 6: Query done - took 5 ms.
+INFO: --- Message 7: Query
+INFO: === Message 7: Query done - took 2 ms.
+INFO: --- Message 8: Query
+INFO: === Message 8: Query done - took 4 ms.
+INFO: --- Message 9: flush-cascade-sync
+INFO: === Message 9: flush-cascade-sync done - took 34 ms.
+----
+
+As you see client prints no SQL statmenets, just a bunch of query and flush messages sent to the server. The server side is more verbose, showing the actual client queries executed against the database:
+
+[source]
+----
+...
+INFO: SELECT NEXT_ID FROM AUTO_PK_SUPPORT WHERE TABLE_NAME = ? FOR UPDATE [bind: 1:'ARTIST']
+INFO: SELECT NEXT_ID FROM AUTO_PK_SUPPORT WHERE TABLE_NAME = ? FOR UPDATE [bind: 1:'GALLERY']
+INFO: SELECT NEXT_ID FROM AUTO_PK_SUPPORT WHERE TABLE_NAME = ? FOR UPDATE [bind: 1:'PAINTING']
+INFO: INSERT INTO ARTIST (DATE_OF_BIRTH, ID, NAME) VALUES (?, ?, ?)
+INFO: [batch bind: 1->DATE_OF_BIRTH:NULL, 2->ID:200, 3->NAME:'Pablo Picasso']
+INFO: === updated 1 row.
+INFO: INSERT INTO GALLERY (ID, NAME) VALUES (?, ?)
+INFO: [batch bind: 1->ID:200, 2->NAME:'Metropolitan Museum of Art']
+INFO: === updated 1 row.
+INFO: INSERT INTO PAINTING (ARTIST_ID, GALLERY_ID, ID, NAME) VALUES (?, ?, ?, ?)
+INFO: [batch bind: 1->ARTIST_ID:200, 2->GALLERY_ID:200, 3->ID:200, 4->NAME:'Girl Reading at a Table']
+INFO: [batch bind: 1->ARTIST_ID:200, 2->GALLERY_ID:200, 3->ID:201, 4->NAME:'Gertrude Stein']
+INFO: === updated 2 rows.
+INFO: +++ transaction committed.
+INFO: --- transaction started.
+INFO: SELECT t0.GALLERY_ID, t0.NAME, t0.ARTIST_ID, t0.ID FROM PAINTING t0
+INFO: === returned 2 rows. - took 14 ms.
+INFO: +++ transaction committed.
+INFO: --- transaction started.
+INFO: SELECT t0.GALLERY_ID, t0.NAME, t0.ARTIST_ID, t0.ID FROM PAINTING t0
+ WHERE UPPER(t0.NAME) LIKE UPPER(?) [bind: 1->NAME:'gi%']
+INFO: === returned 1 row. - took 10 ms.
+INFO: +++ transaction committed.
+INFO: --- transaction started.
+INFO: SELECT t0.DATE_OF_BIRTH, t0.NAME, t0.ID FROM ARTIST t0 WHERE t0.NAME = ? [bind: 1->NAME:'Pablo Picasso']
+INFO: === returned 1 row. - took 8 ms.
+INFO: +++ transaction committed.
+INFO: --- transaction started.
+INFO: DELETE FROM PAINTING WHERE ID = ?
+INFO: [batch bind: 1->ID:200]
+INFO: [batch bind: 1->ID:201]
+INFO: === updated 2 rows.
+INFO: DELETE FROM ARTIST WHERE ID = ?
+INFO: [batch bind: 1->ID:200]
+INFO: === updated 1 row.
+INFO: +++ transaction committed.
+----
+
+You are done with the basic ROP client!
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/asciidoc/getting-started-rop/src/docs/asciidoc/_getting-started-rop/part2/hessianWebServ.adoc
----------------------------------------------------------------------
diff --git a/docs/asciidoc/getting-started-rop/src/docs/asciidoc/_getting-started-rop/part2/hessianWebServ.adoc b/docs/asciidoc/getting-started-rop/src/docs/asciidoc/_getting-started-rop/part2/hessianWebServ.adoc
new file mode 100644
index 0000000..d2768e1
--- /dev/null
+++ b/docs/asciidoc/getting-started-rop/src/docs/asciidoc/_getting-started-rop/part2/hessianWebServ.adoc
@@ -0,0 +1,113 @@
+// 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.
+
+=== Setting up Hessian Web Service
+
+==== Setting up Dependencies
+
+Now lets get back to the "tutorial" project that contains a web application and set up dependencies. The only extra one that we don't have yet is resin-hessian.jar, just like the client, so let's add it (and the caucho repo declaration) to the pom.xml.
+
+[source, XML]
+----
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
+ ...
+ <dependencies>
+ ...
+ <dependency>
+ <groupId>com.caucho</groupId>
+ <artifactId>hessian</artifactId>
+ <version>4.0.38</version>
+ </dependency>
+ </dependencies>
+
+ <build>
+ ...
+ </build>
+
+ <repositories>
+ <repository>
+ <id>caucho</id>
+ <name>Caucho Repository</name>
+ <url>http://caucho.com/m2</url>
+ <layout>default</layout>
+ <snapshots>
+ <enabled>false</enabled>
+ </snapshots>
+ <releases>
+ <enabled>true</enabled>
+ </releases>
+ </repository>
+ </repositories>
+ </project>
+----
+
+NOTE: *Maven Optimization Hint* On a real project both server and client modules will likely share a common parent pom.xml where common repository delcaration can be placed, with child pom's "inheriting" it from parent. This would reduce build code duplication.
+
+==== Client Classes on the Server
+
+Since ROP web service requires both server and client persistent classes, we need to generate a second copy of the client classes inside the server project. This is a minor inconvenience that will hopefully go away in the future versions of Cayenne. Don't forget to refresh the project in Eclipse after class generation is done.
+
+==== Configuring web.xml
+
+Cayenne web service is declared in the web.xml. It is implemented as a servlet "org.apache.cayenne.rop.ROPServlet". Open tutorial/src/main/webapp/WEB-INF/web.xml in Eclipse and add a service declaration:
+
+[source, XML]
+----
+<?xml version="1.0" encoding="utf-8"?>
+ <!DOCTYPE web-app
+ PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
+ "http://java.sun.com/dtd/web-app_2_3.dtd">
+<web-app>
+ <display-name>Cayenne Tutorial</display-name>
+ <servlet>
+ <servlet-name>cayenne-project</servlet-name>
+ <servlet-class>org.apache.cayenne.rop.ROPServlet</servlet-class>
+ <load-on-startup>0</load-on-startup>
+ </servlet>
+ <servlet-mapping>
+ <servlet-name>cayenne-project</servlet-name>
+ <url-pattern>/cayenne-service</url-pattern>
+ </servlet-mapping>
+ </web-app>
+----
+
+NOTE: *Extending Server Behavior via Callbacks* While no custom Java code is required on the server, just a service declaration, it is possible to customizing server-side behavior via callbacks and listeners (not shown in the tutorial).
+
+==== Running ROP Server
+
+Use previosly created Eclipse Jetty run configuration available via "Run > Run Configurations..." (or create a new one if none exists yet). You should see output in the Eclipse console similar to the following:
+
+[source]
+----
+[INFO] Scanning for projects...
+[INFO]
+[INFO] ------------------------------------------------------------------------
+[INFO] Building tutorial 0.0.1-SNAPSHOT
+[INFO] ------------------------------------------------------------------------
+...
+[INFO] Starting jetty 6.1.22 ...
+INFO::jetty-6.1.22
+INFO::No Transaction manager found - if your webapp requires one, please configure one.
+INFO::Started SelectChannelConnector@0.0.0.0:8080
+[INFO] Started Jetty Server
+INFO: Loading XML configuration resource from file:cayenne-project.xml
+INFO: loading user name and password.
+INFO: Created connection pool: jdbc:derby:memory:testdb;create=true
+ Driver class: org.apache.derby.jdbc.EmbeddedDriver
+ Min. connections in the pool: 1
+ Max. connections in the pool: 1
+----
+
+Cayenne ROP service URL is http://localhost:8080/tutorial/cayenne-service. If you click on it, you will see "Hessian Requires POST" message, that means that the service is alive, but you need a client other than the web browser to access it.
\ No newline at end of file
[13/13] cayenne git commit: CAY-2371 Switch documentation from
Docbook to Asciidoctor format
Posted by nt...@apache.org.
CAY-2371 Switch documentation from Docbook to Asciidoctor format
Project: http://git-wip-us.apache.org/repos/asf/cayenne/repo
Commit: http://git-wip-us.apache.org/repos/asf/cayenne/commit/cde78f0b
Tree: http://git-wip-us.apache.org/repos/asf/cayenne/tree/cde78f0b
Diff: http://git-wip-us.apache.org/repos/asf/cayenne/diff/cde78f0b
Branch: refs/heads/STABLE-4.0
Commit: cde78f0b4d1eba0a70ceddd6fafddc77fca67856
Parents: 2f472ce
Author: Nikita Timofeev <st...@gmail.com>
Authored: Fri Jan 5 16:09:37 2018 +0300
Committer: Nikita Timofeev <st...@gmail.com>
Committed: Fri Jan 5 16:09:37 2018 +0300
----------------------------------------------------------------------
.../resources/assemblies/assembly-generic.xml | 8 +-
.../main/resources/assemblies/assembly-mac.xml | 8 +-
.../resources/assemblies/assembly-windows.xml | 8 +-
.../asciidoc/cayenne-asciidoc-extension/pom.xml | 44 +
.../cayenne/asciidoc/CayennePostProcessor.java | 197 ++++
docs/asciidoc/cayenne-guide/pom.xml | 151 ++++
.../_cayenne-guide/configurationProperties.adoc | 123 +++
.../asciidoc/_cayenne-guide/expressionsBNF.adoc | 140 +++
.../docs/asciidoc/_cayenne-guide/header.html | 28 +
.../asciidoc/_cayenne-guide/listOfTables.adoc | 30 +
.../src/docs/asciidoc/_cayenne-guide/part1.adoc | 21 +
.../asciidoc/_cayenne-guide/part1/mapping.adoc | 71 ++
.../asciidoc/_cayenne-guide/part1/modeler.adoc | 61 ++
.../asciidoc/_cayenne-guide/part1/setup.adoc | 112 +++
.../src/docs/asciidoc/_cayenne-guide/part2.adoc | 33 +
.../_cayenne-guide/part2/customize.adoc | 473 ++++++++++
.../_cayenne-guide/part2/expressions.adoc | 279 ++++++
.../_cayenne-guide/part2/including.adoc | 662 ++++++++++++++
.../_cayenne-guide/part2/lifecycle.adoc | 273 ++++++
.../_cayenne-guide/part2/objectContext.adoc | 294 ++++++
.../_cayenne-guide/part2/orderings.adoc | 36 +
.../asciidoc/_cayenne-guide/part2/queries.adoc | 803 +++++++++++++++++
.../asciidoc/_cayenne-guide/part2/starting.adoc | 118 +++
.../asciidoc/_cayenne-guide/part2/tuning.adoc | 354 ++++++++
.../src/docs/asciidoc/_cayenne-guide/part3.adoc | 28 +
.../_cayenne-guide/part3/clientImpl.adoc | 16 +
.../_cayenne-guide/part3/limitations.adoc | 18 +
.../docs/asciidoc/_cayenne-guide/part3/rop.adoc | 54 ++
.../_cayenne-guide/part3/ropDeployment.adoc | 34 +
.../asciidoc/_cayenne-guide/part3/ropSetup.adoc | 20 +
.../_cayenne-guide/part3/serverImpl.adoc | 16 +
.../src/docs/asciidoc/_cayenne-guide/part4.adoc | 25 +
.../_cayenne-guide/part4/filtering.adoc | 369 ++++++++
.../_cayenne-guide/part4/introduction.adoc | 75 ++
.../_cayenne-guide/part4/otherSettings.adoc | 64 ++
.../_cayenne-guide/part4/revEngineering.adoc | 57 ++
.../src/docs/asciidoc/_cayenne-guide/part5.adoc | 30 +
.../_cayenne-guide/part5/cacheInvalidation.adoc | 95 ++
.../_cayenne-guide/part5/commitLog.adoc | 83 ++
.../asciidoc/_cayenne-guide/part5/crypto.adoc | 116 +++
.../_cayenne-guide/part5/dbcpIntegration.adoc | 47 +
.../asciidoc/_cayenne-guide/part5/jCache.adoc | 51 ++
.../asciidoc/_cayenne-guide/part5/java8.adoc | 45 +
.../asciidoc/_cayenne-guide/part5/jodaTime.adoc | 46 +
.../_cayenne-guide/serviceCollections.adoc | 62 ++
.../src/docs/asciidoc/_cayenne-guide/var.adoc | 1 +
.../src/docs/asciidoc/cayenne-guide.adoc | 56 ++
.../asciidoc/images/ext-crypto-obj-entity.png | Bin 0 -> 18145 bytes
.../src/docs/asciidoc/images/ext-dbcp-setup.png | Bin 0 -> 33026 bytes
.../images/re-modeler-datasource-select.png | Bin 0 -> 32658 bytes
.../re-modeler-reverseengineering-dialog.png | Bin 0 -> 37668 bytes
.../images/remote-object-persistence.jpg | Bin 0 -> 54407 bytes
docs/asciidoc/getting-started-guide/pom.xml | 170 ++++
.../asciidoc/_getting-started-guide/delete.adoc | 72 ++
.../asciidoc/_getting-started-guide/header.html | 29 +
.../_getting-started-guide/java-classes.adoc | 113 +++
.../_getting-started-guide/object-context.adoc | 89 ++
.../object-relational-mapping.adoc | 109 +++
.../asciidoc/_getting-started-guide/part2.adoc | 20 +
.../asciidoc/_getting-started-guide/part3.adoc | 22 +
.../persistent-objects.adoc | 111 +++
.../_getting-started-guide/select-query.adoc | 56 ++
.../asciidoc/_getting-started-guide/setup.adoc | 26 +
.../starting-project.adoc | 111 +++
.../asciidoc/_getting-started-guide/webapp.adoc | 280 ++++++
.../docs/asciidoc/getting-started-guide.adoc | 48 +
.../src/docs/asciidoc/images/base-datamap.png | Bin 0 -> 90863 bytes
.../src/docs/asciidoc/images/base-datanode.png | Bin 0 -> 93515 bytes
.../asciidoc/images/cayenne-tutorial-model.png | Bin 0 -> 18875 bytes
.../src/docs/asciidoc/images/chrome-webapp.png | Bin 0 -> 42124 bytes
.../docs/asciidoc/images/database-schema.jpg | Bin 0 -> 28434 bytes
.../src/docs/asciidoc/images/icon-attribute.png | Bin 0 -> 293 bytes
.../src/docs/asciidoc/images/icon-datamap.png | Bin 0 -> 411 bytes
.../src/docs/asciidoc/images/icon-dbentity.png | Bin 0 -> 142 bytes
.../src/docs/asciidoc/images/icon-edit.png | Bin 0 -> 340 bytes
.../docs/asciidoc/images/icon-new_objentity.png | Bin 0 -> 563 bytes
.../src/docs/asciidoc/images/icon-node.png | Bin 0 -> 350 bytes
.../docs/asciidoc/images/icon-relationship.png | Bin 0 -> 347 bytes
.../src/docs/asciidoc/images/icon-sync.png | Bin 0 -> 280 bytes
.../images/idea-edit-configurations.png | Bin 0 -> 17245 bytes
.../docs/asciidoc/images/idea-file-run-menu.png | Bin 0 -> 32911 bytes
.../asciidoc/images/idea-generated-classes.png | Bin 0 -> 207620 bytes
.../asciidoc/images/idea-run-configuration.png | Bin 0 -> 93059 bytes
.../src/docs/asciidoc/images/idea-xmlfiles.png | Bin 0 -> 27783 bytes
.../docs/asciidoc/images/modeler-artistid.png | Bin 0 -> 60176 bytes
.../asciidoc/images/modeler-dbrelationship.png | Bin 0 -> 41430 bytes
.../docs/asciidoc/images/modeler-deleterule.png | Bin 0 -> 78049 bytes
.../docs/asciidoc/images/modeler-started.png | Bin 0 -> 95897 bytes
.../asciidoc/images/tutorial-idea-project.png | Bin 0 -> 48037 bytes
.../src/docs/asciidoc/var.adoc | 1 +
docs/asciidoc/getting-started-rop/pom.xml | 151 ++++
.../asciidoc/_getting-started-rop/header.html | 24 +
.../asciidoc/_getting-started-rop/part1.adoc | 17 +
.../part1/prerequisites.adoc | 25 +
.../asciidoc/_getting-started-rop/part2.adoc | 23 +
.../_getting-started-rop/part2/adding.adoc | 126 +++
.../_getting-started-rop/part2/connect.adoc | 174 ++++
.../part2/hessianWebServ.adoc | 113 +++
.../_getting-started-rop/part2/starting.adoc | 93 ++
.../docs/asciidoc/_getting-started-rop/var.adoc | 1 +
.../src/docs/asciidoc/getting-started-rop.adoc | 45 +
.../asciidoc/images/datamap-enableclient.png | Bin 0 -> 104778 bytes
docs/asciidoc/pom.xml | 132 +++
docs/asciidoc/upgrade-guide/pom.xml | 151 ++++
.../docs/asciidoc/_upgrade_guide/features.adoc | 245 +++++
.../docs/asciidoc/_upgrade_guide/header.html | 24 +
.../src/docs/asciidoc/upgrade-guide.adoc | 44 +
docs/docbook/cayenne-guide/pom.xml | 31 -
.../cayenne-guide/src/docbkx/appendix-a.xml | 190 ----
.../cayenne-guide/src/docbkx/appendix-b.xml | 100 ---
.../cayenne-guide/src/docbkx/appendix-c.xml | 147 ---
.../src/docbkx/cayenne-mapping-structure.xml | 95 --
.../src/docbkx/cayennemodeler-application.xml | 116 ---
.../src/docbkx/current-limitations.xml | 20 -
.../src/docbkx/customizing-cayenne-runtime.xml | 473 ----------
.../cayenne-guide/src/docbkx/expressions.xml | 303 -------
.../src/docbkx/ext-cache-invalidation.xml | 91 --
.../cayenne-guide/src/docbkx/ext-commit-log.xml | 89 --
.../cayenne-guide/src/docbkx/ext-crypto.xml | 135 ---
.../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/implementing-rop-client.xml | 20 -
.../src/docbkx/implementing-rop-server.xml | 20 -
.../src/docbkx/including-cayenne-in-project.xml | 893 -------------------
docs/docbook/cayenne-guide/src/docbkx/index.xml | 49 -
.../src/docbkx/lifecycle-events.xml | 314 -------
.../cayenne-guide/src/docbkx/orderings.xml | 31 -
docs/docbook/cayenne-guide/src/docbkx/part1.xml | 23 -
docs/docbook/cayenne-guide/src/docbkx/part2.xml | 29 -
docs/docbook/cayenne-guide/src/docbkx/part3.xml | 26 -
docs/docbook/cayenne-guide/src/docbkx/part4.xml | 24 -
docs/docbook/cayenne-guide/src/docbkx/part5.xml | 30 -
.../src/docbkx/performance-tuning.xml | 379 --------
.../docbkx/persistent-objects-objectcontext.xml | 288 ------
.../cayenne-guide/src/docbkx/queries-custom.xml | 57 --
.../cayenne-guide/src/docbkx/queries-ejbql.xml | 94 --
.../cayenne-guide/src/docbkx/queries-mapped.xml | 44 -
.../src/docbkx/queries-namedquery.xml | 35 -
.../src/docbkx/queries-procedure.xml | 67 --
.../src/docbkx/queries-procedurecall.xml | 61 --
.../cayenne-guide/src/docbkx/queries-select.xml | 111 ---
.../src/docbkx/queries-selectbyid.xml | 33 -
.../src/docbkx/queries-sqlselect.xml | 45 -
.../src/docbkx/queries-sqltemplate.xml | 420 ---------
.../cayenne-guide/src/docbkx/queries.xml | 55 --
.../cayenne-guide/src/docbkx/re-filtering.xml | 356 --------
.../src/docbkx/re-introduction.xml | 88 --
.../cayenne-guide/src/docbkx/re-modeler.xml | 122 ---
.../src/docbkx/re-other-settings.xml | 65 --
.../cayenne-guide/src/docbkx/rop-deployment.xml | 47 -
.../src/docbkx/rop-introduction.xml | 98 --
.../cayenne-guide/src/docbkx/rop-setup.xml | 26 -
docs/docbook/cayenne-guide/src/docbkx/setup.xml | 176 ----
.../src/docbkx/starting-cayenne.xml | 157 ----
.../docbook/cayenne-guide/src/images/.gitignore | 0
.../src/images/ext-crypto-obj-entity.png | Bin 18145 -> 0 bytes
.../cayenne-guide/src/images/ext-dbcp-setup.png | Bin 33026 -> 0 bytes
.../src/images/re-modeler-datasource-select.png | Bin 32658 -> 0 bytes
.../re-modeler-reverseengineering-dialog.png | Bin 37668 -> 0 bytes
.../src/images/remote-object-persistence.jpg | Bin 54407 -> 0 bytes
docs/docbook/docbook-stylesheets/pom.xml | 45 -
.../src/main/resources/css/cayenne-doc.css | 148 ---
.../src/main/resources/css/highlight.css | 35 -
.../stylesheets/common-customizations.xsl | 32 -
.../main/resources/stylesheets/highlight.xsl | 104 ---
.../src/main/resources/stylesheets/html.xsl | 244 -----
.../src/main/resources/stylesheets/pdf.xsl | 505 -----------
docs/docbook/getting-started-rop/pom.xml | 39 -
.../src/docbkx/authentication.xml | 128 ---
.../src/docbkx/client-code.xml | 159 ----
.../src/docbkx/client-project.xml | 131 ---
.../getting-started-rop/src/docbkx/index.xml | 43 -
.../getting-started-rop/src/docbkx/part1.xml | 22 -
.../getting-started-rop/src/docbkx/part2.xml | 24 -
.../getting-started-rop/src/docbkx/setup.xml | 53 --
.../src/docbkx/web-service.xml | 131 ---
.../src/images/datamap-enableclient.png | Bin 104778 -> 0 bytes
docs/docbook/getting-started/pom.xml | 40 -
.../getting-started/src/docbkx/delete.xml | 79 --
.../getting-started/src/docbkx/index.xml | 44 -
.../getting-started/src/docbkx/java-classes.xml | 129 ---
.../src/docbkx/object-context.xml | 103 ---
.../src/docbkx/object-relational-mapping.xml | 184 ----
.../getting-started/src/docbkx/part1.xml | 21 -
.../getting-started/src/docbkx/part2.xml | 25 -
.../getting-started/src/docbkx/part3.xml | 26 -
.../getting-started/src/docbkx/part4.xml | 22 -
.../src/docbkx/persistent-objects.xml | 145 ---
.../getting-started/src/docbkx/select-query.xml | 60 --
.../getting-started/src/docbkx/setup.xml | 36 -
.../src/docbkx/starting-project.xml | 165 ----
.../getting-started/src/docbkx/webapp.xml | 308 -------
.../getting-started/src/images/base-datamap.png | Bin 90863 -> 0 bytes
.../src/images/base-datanode.png | Bin 93515 -> 0 bytes
.../src/images/chrome-webapp.png | Bin 42124 -> 0 bytes
.../src/images/database-schema.jpg | Bin 28434 -> 0 bytes
.../src/images/icon-attribute.png | Bin 293 -> 0 bytes
.../getting-started/src/images/icon-datamap.png | Bin 411 -> 0 bytes
.../src/images/icon-dbentity.png | Bin 142 -> 0 bytes
.../getting-started/src/images/icon-edit.png | Bin 340 -> 0 bytes
.../src/images/icon-new_objentity.png | Bin 563 -> 0 bytes
.../getting-started/src/images/icon-node.png | Bin 350 -> 0 bytes
.../src/images/icon-relationship.png | Bin 347 -> 0 bytes
.../getting-started/src/images/icon-sync.png | Bin 280 -> 0 bytes
.../src/images/idea-edit-configurations.png | Bin 17245 -> 0 bytes
.../src/images/idea-file-run-menu.png | Bin 32911 -> 0 bytes
.../src/images/idea-generated-classes.png | Bin 207620 -> 0 bytes
.../src/images/idea-run-configuration.png | Bin 93059 -> 0 bytes
.../src/images/idea-xmlfiles.png | Bin 27783 -> 0 bytes
.../src/images/modeler-artistid.png | Bin 60176 -> 0 bytes
.../src/images/modeler-dbrelationship.png | Bin 41430 -> 0 bytes
.../src/images/modeler-deleterule.png | Bin 78049 -> 0 bytes
.../src/images/modeler-started.png | Bin 95897 -> 0 bytes
.../src/images/tutorial-idea-project.png | Bin 48037 -> 0 bytes
docs/docbook/pom.xml | 126 ---
docs/docbook/upgrade-guide/pom.xml | 38 -
docs/docbook/upgrade-guide/src/docbkx/index.xml | 27 -
.../upgrade-guide/src/docbkx/new-features.xml | 238 -----
.../docbook/upgrade-guide/src/images/.gitignore | 2 -
docs/pom.xml | 2 +-
.../java/org/apache/cayenne/tutorial/Main.java | 8 +
.../cayenne/tutorial/persistent/Artist.java | 10 +-
tutorials/tutorial/src/main/webapp/detail.jsp | 4 +-
tutorials/tutorial/src/main/webapp/index.jsp | 4 +-
226 files changed, 8390 insertions(+), 9978 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/assembly/src/main/resources/assemblies/assembly-generic.xml
----------------------------------------------------------------------
diff --git a/assembly/src/main/resources/assemblies/assembly-generic.xml b/assembly/src/main/resources/assemblies/assembly-generic.xml
index ad121d3..4b9028e 100644
--- a/assembly/src/main/resources/assemblies/assembly-generic.xml
+++ b/assembly/src/main/resources/assemblies/assembly-generic.xml
@@ -54,22 +54,22 @@
<files>
<file>
- <source>../docs/docbook/getting-started/target/site/getting-started.pdf</source>
+ <source>../docs/asciidoc/getting-started-guide/target/generated-docs/getting-started-guide.pdf</source>
<outputDirectory>doc</outputDirectory>
<destName>getting-started.pdf</destName>
</file>
<file>
- <source>../docs/docbook/getting-started-rop/target/site/getting-started-rop.pdf</source>
+ <source>../docs/asciidoc/getting-started-rop/target/generated-docs/getting-started-rop.pdf</source>
<outputDirectory>doc</outputDirectory>
<destName>getting-started-rop.pdf</destName>
</file>
<file>
- <source>../docs/docbook/cayenne-guide/target/site/cayenne-guide.pdf</source>
+ <source>../docs/asciidoc/cayenne-guide/target/generated-docs/cayenne-guide.pdf</source>
<outputDirectory>doc</outputDirectory>
<destName>cayenne-guide.pdf</destName>
</file>
<file>
- <source>../docs/docbook/upgrade-guide/target/site/upgrade-guide.pdf</source>
+ <source>../docs/asciidoc/upgrade-guide/target/generated-docs/upgrade-guide.pdf</source>
<outputDirectory>doc</outputDirectory>
<destName>upgrade-guide.pdf</destName>
</file>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/assembly/src/main/resources/assemblies/assembly-mac.xml
----------------------------------------------------------------------
diff --git a/assembly/src/main/resources/assemblies/assembly-mac.xml b/assembly/src/main/resources/assemblies/assembly-mac.xml
index 0261484..b2d292d 100644
--- a/assembly/src/main/resources/assemblies/assembly-mac.xml
+++ b/assembly/src/main/resources/assemblies/assembly-mac.xml
@@ -52,22 +52,22 @@
<files>
<file>
- <source>../docs/docbook/getting-started/target/site/getting-started.pdf</source>
+ <source>../docs/asciidoc/getting-started-guide/target/generated-docs/getting-started-guide.pdf</source>
<outputDirectory>doc</outputDirectory>
<destName>getting-started.pdf</destName>
</file>
<file>
- <source>../docs/docbook/getting-started-rop/target/site/getting-started-rop.pdf</source>
+ <source>../docs/asciidoc/getting-started-rop/target/generated-docs/getting-started-rop.pdf</source>
<outputDirectory>doc</outputDirectory>
<destName>getting-started-rop.pdf</destName>
</file>
<file>
- <source>../docs/docbook/cayenne-guide/target/site/cayenne-guide.pdf</source>
+ <source>../docs/asciidoc/cayenne-guide/target/generated-docs/cayenne-guide.pdf</source>
<outputDirectory>doc</outputDirectory>
<destName>cayenne-guide.pdf</destName>
</file>
<file>
- <source>../docs/docbook/upgrade-guide/target/site/upgrade-guide.pdf</source>
+ <source>../docs/asciidoc/upgrade-guide/target/generated-docs/upgrade-guide.pdf</source>
<outputDirectory>doc</outputDirectory>
<destName>upgrade-guide.pdf</destName>
</file>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/assembly/src/main/resources/assemblies/assembly-windows.xml
----------------------------------------------------------------------
diff --git a/assembly/src/main/resources/assemblies/assembly-windows.xml b/assembly/src/main/resources/assemblies/assembly-windows.xml
index 185ab68..2263287 100644
--- a/assembly/src/main/resources/assemblies/assembly-windows.xml
+++ b/assembly/src/main/resources/assemblies/assembly-windows.xml
@@ -52,22 +52,22 @@
<files>
<file>
- <source>../docs/docbook/getting-started/target/site/getting-started.pdf</source>
+ <source>../docs/asciidoc/getting-started-guide/target/generated-docs/getting-started-guide.pdf</source>
<outputDirectory>doc</outputDirectory>
<destName>getting-started.pdf</destName>
</file>
<file>
- <source>../docs/docbook/getting-started-rop/target/site/getting-started-rop.pdf</source>
+ <source>../docs/asciidoc/getting-started-rop/target/generated-docs/getting-started-rop.pdf</source>
<outputDirectory>doc</outputDirectory>
<destName>getting-started-rop.pdf</destName>
</file>
<file>
- <source>../docs/docbook/cayenne-guide/target/site/cayenne-guide.pdf</source>
+ <source>../docs/asciidoc/cayenne-guide/target/generated-docs/cayenne-guide.pdf</source>
<outputDirectory>doc</outputDirectory>
<destName>cayenne-guide.pdf</destName>
</file>
<file>
- <source>../docs/docbook/upgrade-guide/target/site/upgrade-guide.pdf</source>
+ <source>../docs/asciidoc/upgrade-guide/target/generated-docs/upgrade-guide.pdf</source>
<outputDirectory>doc</outputDirectory>
<destName>upgrade-guide.pdf</destName>
</file>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/asciidoc/cayenne-asciidoc-extension/pom.xml
----------------------------------------------------------------------
diff --git a/docs/asciidoc/cayenne-asciidoc-extension/pom.xml b/docs/asciidoc/cayenne-asciidoc-extension/pom.xml
new file mode 100644
index 0000000..662594e
--- /dev/null
+++ b/docs/asciidoc/cayenne-asciidoc-extension/pom.xml
@@ -0,0 +1,44 @@
+<?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.
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~-->
+
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+ <parent>
+ <artifactId>cayenne-asciidoc-parent</artifactId>
+ <groupId>org.apache.cayenne.docs</groupId>
+ <version>4.0.B3-SNAPSHOT</version>
+ </parent>
+
+ <artifactId>cayenne-asciidoc-extension</artifactId>
+ <description>AsciidoctorJ extension for website version of Cayenne documentation</description>
+ <packaging>jar</packaging>
+ <modelVersion>4.0.0</modelVersion>
+
+ <dependencies>
+ <dependency>
+ <!-- jsoup HTML parser library @ https://jsoup.org/ -->
+ <groupId>org.jsoup</groupId>
+ <artifactId>jsoup</artifactId>
+ <version>1.11.2</version>
+ </dependency>
+ </dependencies>
+
+</project>
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/asciidoc/cayenne-asciidoc-extension/src/main/java/org/apache/cayenne/asciidoc/CayennePostProcessor.java
----------------------------------------------------------------------
diff --git a/docs/asciidoc/cayenne-asciidoc-extension/src/main/java/org/apache/cayenne/asciidoc/CayennePostProcessor.java b/docs/asciidoc/cayenne-asciidoc-extension/src/main/java/org/apache/cayenne/asciidoc/CayennePostProcessor.java
new file mode 100644
index 0000000..1502429
--- /dev/null
+++ b/docs/asciidoc/cayenne-asciidoc-extension/src/main/java/org/apache/cayenne/asciidoc/CayennePostProcessor.java
@@ -0,0 +1,197 @@
+/*****************************************************************
+ * 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.
+ ****************************************************************/
+
+package org.apache.cayenne.asciidoc;
+
+import java.io.BufferedWriter;
+import java.io.IOException;
+import java.nio.file.FileSystems;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.nio.file.StandardOpenOption;
+import java.util.Collections;
+import java.util.Map;
+
+import org.asciidoctor.Options;
+import org.asciidoctor.ast.Document;
+import org.asciidoctor.ast.DocumentRuby;
+import org.asciidoctor.extension.Postprocessor;
+import org.jsoup.Jsoup;
+
+/**
+ * <p>
+ * AsciidoctorJ post processor, that extracts ToC into separate file and optionally can inject content into rendered document.
+ * Can be used only for HTML backend, will <b>fail</b> if used with PDF.
+ * <p>
+ * It is targeted to inject "front-matter" section suitable for cayenne website tools.
+ * <p>
+ * Extension controlled by attributes in *.adoc file:
+ * <ul>
+ * <li>cayenne-header: header file name or constant "front-matter" that will inject empty front matter markup
+ * <li>cayenne-header-position [optional]: "top" to inject just above all content or "body" to inject right after >body< tag
+ * <li>cayenne-footer: footer file name or constant "front-matter" that will inject empty front matter markup
+ * <li>cayenne-footer-position [optional]: "bottom" to inject just after all content or "body" to inject right before >/body< tag
+ * </ul>
+ *
+ * @since 4.1
+ */
+public class CayennePostProcessor extends Postprocessor {
+
+ private static final String FRONT_MATTER = "front-matter";
+ private static final String EMPTY_FRONT_MATTER = "---\n---\n\n";
+ private static final String POSITION_TOP = "top";
+ private static final String POSITION_BODY = "body";
+ private static final String POSITION_BOTTOM = "bottom";
+
+ public CayennePostProcessor(DocumentRuby documentRuby) {
+ super();
+ }
+
+ public String process(Document document, String output) {
+ output = extractTableOfContents(document, output);
+ output = fixupDom(document, output);
+ output = processHeader(document, output);
+ output = processFooter(document, output);
+ return output;
+ }
+
+ private String fixupDom(Document document, String output) {
+ org.jsoup.nodes.Document jsoupDoc = Jsoup.parseBodyFragment(output);
+
+ jsoupDoc.select(".icon-note")
+ .removeClass("icon-note")
+ .addClass("fa-info-circle")
+ .addClass("fa-2x");
+
+ jsoupDoc.select(".icon-tip")
+ .removeClass("icon-tip")
+ .addClass("fa-lightbulb-o")
+ .addClass("fa-2x");
+
+ jsoupDoc.select("code").forEach(el -> {
+ String codeClass = el.attr("data-lang");
+ if(!codeClass.isEmpty()) {
+ el.addClass(codeClass);
+ }
+ });
+
+ jsoupDoc.select("div#preamble").remove();
+
+ return jsoupDoc.body().html();
+ }
+
+ protected String extractTableOfContents(Document document, String output) {
+ int start = output.indexOf("<div id=\"toc\" class=\"toc\">");
+ if(start == -1) {
+ // no toc found, exit
+ return output;
+ }
+
+ String tocEndString = "</ul>\n</div>";
+ int end = output.indexOf(tocEndString, start);
+ if(end == -1) {
+ // bad, no end..
+ return output;
+ }
+
+ end += tocEndString.length() + 1;
+
+ org.jsoup.nodes.Document tocDoc = Jsoup.parseBodyFragment(output.substring(start, end));
+ tocDoc.select("ul").addClass("nav");
+ tocDoc.select("a").addClass("nav-link");
+ tocDoc.select("div#toc").addClass("toc-side");
+ String toc = tocDoc.body().html();
+
+ Object destDir = document.getOptions().get(Options.DESTINATION_DIR);
+ Object docname = ((Map)document.getOptions().get(Options.ATTRIBUTES)).get("docname");
+
+ Path path = FileSystems.getDefault().getPath((String) destDir, docname + ".toc.html");
+ try(BufferedWriter br = Files.newBufferedWriter(path, StandardOpenOption.CREATE_NEW, StandardOpenOption.WRITE)) {
+ br.write(toc, 0, toc.length());
+ br.flush();
+ } catch (IOException ex) {
+ ex.printStackTrace(System.err);
+ }
+
+ if(start == 0) {
+ return output.substring(end);
+ }
+
+ return output.substring(0, start) + output.substring(end);
+ }
+
+ protected String processHeader(Document document, String output) {
+ String headerFile = (String) document.getAttr("cayenne-header", "");
+ String headerPosition = (String)document.getAttr("cayenne-header-position", POSITION_TOP);
+
+ if(headerFile.isEmpty()) {
+ return output;
+ }
+
+ String header = "";
+ // inject empty front matter
+ if(FRONT_MATTER.equals(headerFile.trim())) {
+ header = EMPTY_FRONT_MATTER ;
+ } else {
+ // treat as a file
+ header = document.readAsset(headerFile, Collections.emptyMap());
+ }
+
+ switch (headerPosition.trim()) {
+ case POSITION_BODY: {
+ int bodyStart = output.indexOf("<div id=\"header\">");
+ if(bodyStart == -1) {
+ // no header
+ return header + output;
+ }
+ return output.substring(0, bodyStart) + header + output.substring(bodyStart);
+ }
+
+ case POSITION_TOP:
+ default:
+ return header + output;
+ }
+ }
+
+ protected String processFooter(Document document, String output) {
+ String footerFile = (String) document.getAttr("cayenne-footer", "");
+ String footerPosition = (String)document.getAttr("cayenne-footer-position", POSITION_BOTTOM);
+
+ if(footerFile.isEmpty()) {
+ return output;
+ }
+
+ String footer = document.readAsset(footerFile, Collections.emptyMap());
+
+ switch (footerPosition.trim()) {
+ case POSITION_BODY: {
+ int bodyStart = output.indexOf("</body>");
+ if(bodyStart == -1) {
+ // no footer
+ return output + footer;
+ }
+ return output.substring(0, bodyStart) + footer + output.substring(bodyStart);
+ }
+
+ case POSITION_BOTTOM:
+ default:
+ return output + footer;
+ }
+ }
+}
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/asciidoc/cayenne-guide/pom.xml
----------------------------------------------------------------------
diff --git a/docs/asciidoc/cayenne-guide/pom.xml b/docs/asciidoc/cayenne-guide/pom.xml
new file mode 100644
index 0000000..89027c0
--- /dev/null
+++ b/docs/asciidoc/cayenne-guide/pom.xml
@@ -0,0 +1,151 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+ <parent>
+ <artifactId>cayenne-asciidoc-parent</artifactId>
+ <groupId>org.apache.cayenne.docs</groupId>
+ <version>4.0.B3-SNAPSHOT</version>
+ </parent>
+ <modelVersion>4.0.0</modelVersion>
+
+ <artifactId>cayenne-guide</artifactId>
+
+ <packaging>jar</packaging>
+ <name>cayenne-guide: AsciiDoc - Cayenne Framework Guide</name>
+
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.asciidoctor</groupId>
+ <artifactId>asciidoctor-maven-plugin</artifactId>
+ <dependencies>
+ <dependency>
+ <groupId>org.apache.cayenne.docs</groupId>
+ <artifactId>cayenne-asciidoc-extension</artifactId>
+ <version>${project.version}</version>
+ </dependency>
+ </dependencies>
+
+ <executions>
+ <!-- generate "embeddable" html content with front matter and without header/footer/styles -->
+ <execution>
+ <id>asciidoctor-html-web</id>
+ <phase>generate-resources</phase>
+ <goals>
+ <goal>process-asciidoc</goal>
+ </goals>
+ <configuration>
+ <backend>html5</backend>
+ <headerFooter>false</headerFooter> <!-- do not generate header and footer -->
+ <outputDirectory>${project.build.directory}/tmp/</outputDirectory>
+ <extensions>
+ <extension>
+ <className>org.apache.cayenne.asciidoc.CayennePostProcessor</className>
+ </extension>
+ </extensions>
+ <attributes>
+ <toc>auto</toc>
+ </attributes>
+ </configuration>
+ </execution>
+ </executions>
+ </plugin>
+
+ <!-- Move images to proper path for site -->
+ <plugin>
+ <artifactId>maven-resources-plugin</artifactId>
+ <executions>
+ <execution>
+ <id>copy docs for site</id>
+ <phase>install</phase>
+ <goals>
+ <goal>copy-resources</goal>
+ </goals>
+
+ <configuration>
+ <outputDirectory>${project.build.directory}/site/</outputDirectory>
+ <resources>
+ <resource>
+ <directory>${project.build.directory}/tmp/</directory>
+ <includes>
+ <include>${project.artifactId}.html</include>
+ <include>${project.artifactId}.toc.html</include>
+ </includes>
+ </resource>
+ </resources>
+ </configuration>
+ </execution>
+
+ <execution>
+ <id>copy images for site</id>
+ <phase>install</phase>
+ <goals>
+ <goal>copy-resources</goal>
+ </goals>
+
+ <configuration>
+ <outputDirectory>${project.build.directory}/site/${project.artifactId}/images/</outputDirectory>
+ <resources>
+ <resource>
+ <directory>${project.build.directory}/tmp/images/</directory>
+ <filtering>true</filtering>
+ </resource>
+ </resources>
+ </configuration>
+ </execution>
+ </executions>
+ </plugin>
+ </plugins>
+ </build>
+
+ <profiles>
+ <profile>
+ <id>assembly</id>
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.asciidoctor</groupId>
+ <artifactId>asciidoctor-maven-plugin</artifactId>
+ <executions>
+ <!-- generate standalone html help -->
+ <execution>
+ <id>asciidoctor-html-standalone</id>
+ <phase>generate-resources</phase>
+ <goals>
+ <goal>process-asciidoc</goal>
+ </goals>
+ <configuration>
+ <backend>html5</backend>
+ <sourceHighlighter>coderay</sourceHighlighter>
+ <embedAssets>true</embedAssets>
+ <attributes>
+ <toc>left</toc>
+ </attributes>
+ </configuration>
+ </execution>
+
+ <!-- generate PDF -->
+ <execution>
+ <id>generate-pdf-doc</id>
+ <phase>generate-resources</phase>
+ <goals>
+ <goal>process-asciidoc</goal>
+ </goals>
+ <configuration>
+ <backend>pdf</backend>
+ <sourceHighlighter>coderay</sourceHighlighter>
+ <attributes>
+ <pagenums/>
+ <toc/>
+ </attributes>
+ </configuration>
+ </execution>
+ </executions>
+ </plugin>
+ </plugins>
+ </build>
+ </profile>
+ </profiles>
+
+</project>
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/configurationProperties.adoc
----------------------------------------------------------------------
diff --git a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/configurationProperties.adoc b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/configurationProperties.adoc
new file mode 100644
index 0000000..2bedc73
--- /dev/null
+++ b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/configurationProperties.adoc
@@ -0,0 +1,123 @@
+// 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.
+
+== Appendix A. Configuration Properties
+
+Note that the property names below are defined as constants in `org.apache.cayenne.configuration.Constants` interface.
+
+[#configProperties]
+* `cayenne.jdbc.driver[.domain_name.node_name]`
+ defines a JDBC driver class to use when creating a DataSource. If domain name and optionally - node name are specified,
+ the setting overrides DataSource info just for this domain/node. Otherwise the override is applied to all domains/nodes in the system.
+ ** Default value: none, project DataNode configuration is used
+
+* `cayenne.jdbc.url[.domain_name.node_name]`
+ defines a DB URL to use when creating a DataSource. If domain name and optionally - node name are specified,
+ the setting overrides DataSource info just for this domain/node. Otherwise the override is applied to all domains/nodes in the system.
+ ** Default value: none, project DataNode configuration is used
+
+* `cayenne.jdbc.username[.domain_name.node_name]`
+ defines a DB user name to use when creating a DataSource. If domain name and optionally - node name are specified,
+ the setting overrides DataSource info just for this domain/node. Otherwise the override is applied to all domains/nodes in the system.
+ ** Possible values: any
+ ** Default value: none, project DataNode configuration is used
+
+* `cayenne.jdbc.password[.domain_name.node_name]`
+ defines a DB password to use when creating a DataSource. If domain name and optionally - node name are specified,
+ the setting overrides DataSource info just for this domain/node. Otherwise the override is applied to all domains/nodes in the system
+ ** Default value: none, project DataNode configuration is used
+
+* `cayenne.jdbc.min_connections[.domain_name.node_name]`
+ defines the DB connection pool minimal size. If domain name and optionally - node name are specified, the setting
+ overrides DataSource info just for this domain/node. Otherwise the override is applied to all domains/nodes in the system
+ ** Default value: none, project DataNode configuration is used
+
+* `cayenne.jdbc.max_connections[.domain_name.node_name]`
+ defines the DB connection pool maximum size. If domain name and optionally - node name are specified, the setting
+ overrides DataSource info just for this domain/node. Otherwise the override is applied to all domains/nodes in the system
+ ** Default value: none, project DataNode configuration is used
+
+* `cayenne.querycache.size`
+ An integer defining the maximum number of entries in the query cache. Note that not all QueryCache providers may respect this property.
+ MapQueryCache uses it, but the rest would use alternative configuration methods.
+ ** Possible values: any positive int value
+ ** Default value: 2000
+
+* `cayenne.server.contexts_sync_strategy`
+ defines whether peer ObjectContexts should receive snapshot events after commits from other contexts. If true (_default_),
+ the contexts would automatically synchronize their state with peers.
+ ** Possible values: true, false
+ ** Default value: true
+
+* `cayenne.server.object_retain_strategy`
+ defines fetched objects retain strategy for ObjectContexts. When weak or soft strategy is used, objects retained by ObjectContext
+ that have no local changes can potentially get garbage collected when JVM feels like doing it.
+ ** Possible values: weak, soft, hard
+ ** Default value: weak
+
+* `cayenne.server.max_id_qualifier_size`
+ defines a maximum number of ID qualifiers in the WHERE clause of queries that are generated for paginated queries and for DISJOINT_BY_ID prefetch processing.
+ This is needed to avoid hitting WHERE clause size limitations and memory usage efficiency.
+ ** Possible values: any positive int
+ ** Default value: 10000
+
+* `cayenne.server.external_tx`
+ defines whether runtime should use external transactions.
+ ** Possible values: true, false
+ ** Default value: false
+
+* `cayenne.rop.service_url`
+ defines the URL of the ROP server
+ ** Default value: none
+
+* `cayenne.rop.service_username`
+ defines the user name for an ROP client to login to an ROP server.
+ ** Default value: none
+
+* `cayenne.rop.service_password`
+ defines the password for an ROP client to login to an ROP server.
+ ** Default value: none
+
+* `cayenne.rop.shared_session_name`
+ defines the name of the shared session that an ROP client wants to join on an ROP server. If omitted, a dedicated session is created.
+ ** Default value: none
+
+* `cayenne.rop.service.timeout`
+ a value in milliseconds for the ROP client-server connection read operation timeout
+ ** Possible values: any positive long value
+ ** Default value: none
+
+* `cayenne.rop.channel_events`
+ defines whether client-side DataChannel should dispatch events to child ObjectContexts.
+ If set to true, ObjectContexts will receive commit events and merge changes committed by peer contexts that passed through the common client DataChannel.
+ ** Possible values: true, false
+ ** Default value: false
+
+* `cayenne.rop.context_change_events`
+ defines whether object property changes in the client context result in firing events. Client UI components can listen to these events and update the UI. Disabled by default.
+ ** Possible values: true, false
+ ** Default value: false
+
+* `cayenne.rop.context_lifecycle_events`
+ defines whether object commit and rollback operations in the client context result in firing events.
+ Client UI components can listen to these events and update the UI. Disabled by default.
+ ** Possible values: true,false
+ ** Default value: false
+
+* `cayenne.server.rop_event_bridge_factory`
+ defines the name of the `org.apache.cayenne.event.EventBridgeFactory` that is passed from the ROP server to the client.
+ I.e. server DI would provide a name of the factory, passing this name to the client via the wire.
+ The client would instantiate it to receive events from the server. Note that this property is stored
+ in `cayenne.server.rop_event_bridge_properties` map, not in the main `cayenne.properties`.
+ ** Default value: false
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/expressionsBNF.adoc
----------------------------------------------------------------------
diff --git a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/expressionsBNF.adoc b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/expressionsBNF.adoc
new file mode 100644
index 0000000..ee3726a
--- /dev/null
+++ b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/expressionsBNF.adoc
@@ -0,0 +1,140 @@
+// 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.
+
+== Appendix C. Expressions BNF
+
+[source]
+----
+TOKENS
+<DEFAULT> SKIP : {
+" "
+| "\t"
+| "\n"
+| "\r"
+}
+
+<DEFAULT> TOKEN : {
+<NULL: "null" | "NULL">
+| <TRUE: "true" | "TRUE">
+| <FALSE: "false" | "FALSE">
+}
+
+<DEFAULT> TOKEN : {
+<PROPERTY_PATH: <IDENTIFIER> ("." <IDENTIFIER>)*>
+}
+
+<DEFAULT> TOKEN : {
+<IDENTIFIER: <LETTER> (<LETTER> | <DIGIT>)* (["+"])?>
+| <#LETTER: ["_","a"-"z","A"-"Z"]>
+| <#DIGIT: ["0"-"9"]>
+}
+
+/**
+ * Quoted Strings, whose object value is stored in the token manager's
+ * "literalValue" field. Both single and double qoutes are allowed
+ */<DEFAULT> MORE : {
+"\'" : WithinSingleQuoteLiteral
+| "\"" : WithinDoubleQuoteLiteral
+}
+
+<WithinSingleQuoteLiteral> MORE : {
+<ESC: "\\" (["n","r","t","b","f","\\","\'","`","\""] | (["0"-"3"])? ["0"-"7"] (["0"-"7"])?)> : {
+| <~["\'","\\"]> : {
+}
+
+<WithinSingleQuoteLiteral> TOKEN : {
+<SINGLE_QUOTED_STRING: "\'"> : DEFAULT
+}
+
+<WithinDoubleQuoteLiteral> MORE : {
+<STRING_ESC: <ESC>> : {
+| <~["\"","\\"]> : {
+}
+
+<WithinDoubleQuoteLiteral> TOKEN : {
+<DOUBLE_QUOTED_STRING: "\""> : DEFAULT
+}
+
+/**
+ * Integer or real Numeric literal, whose object value is stored in the token manager's
+ * "literalValue" field.
+ */<DEFAULT> TOKEN : {
+<INT_LITERAL: ("0" (["0"-"7"])* | ["1"-"9"] (["0"-"9"])* | "0" ["x","X"] (["0"-"9","a"-"f","A"-"F"])+)
+ (["l","L","h","H"])?> : {
+| <FLOAT_LITERAL: <DEC_FLT> (<EXPONENT>)? (<FLT_SUFF>)? | <DEC_DIGITS> <EXPONENT> (<FLT_SUFF>)?
+| <DEC_DIGITS> <FLT_SUFF>> : {
+| <#DEC_FLT: (["0"-"9"])+ "." (["0"-"9"])* | "." (["0"-"9"])+>
+| <#DEC_DIGITS: (["0"-"9"])+>
+| <#EXPONENT: ["e","E"] (["+","-"])? (["0"-"9"])+>
+| <#FLT_SUFF: ["d","D","f","F","b","B"]>
+}
+
+NON-TERMINALS
+ expression := orCondition <EOF>
+ orCondition := andCondition ( "or" andCondition )*
+ andCondition := notCondition ( "and" notCondition )*
+ notCondition := ( "not" | "!" ) simpleCondition
+ | simpleCondition
+ simpleCondition := <TRUE>
+ | <FALSE>
+ | scalarConditionExpression
+ ( simpleNotCondition
+ | ( "=" | "==" ) scalarExpression
+ | ( "!=" | "<>" ) scalarExpression
+ | "<=" scalarExpression
+ | "<" scalarExpression | ">" scalarExpression
+ | ">=" scalarExpression
+ | "like" scalarExpression
+ | "likeIgnoreCase" scalarExpression
+ | "in" ( namedParameter | "(" scalarCommaList ")" )
+ | "between" scalarExpression "and" scalarExpression
+ )?
+ simpleNotCondition := ( "not" | "!" )
+ ( "like" scalarExpression
+ | "likeIgnoreCase" scalarExpression
+ | "in" ( namedParameter | "(" scalarCommaList ")" )
+ | "between" scalarExpression "and" scalarExpression
+ )
+ scalarCommaList := ( scalarConstExpression ( "," scalarConstExpression )* )
+ scalarConditionExpression := scalarNumericExpression
+ | <SINGLE_QUOTED_STRING>
+ | <DOUBLE_QUOTED_STRING>
+ | <NULL>
+ scalarExpression := scalarConditionExpression
+ | <TRUE>
+ | <FALSE>
+ scalarConstExpression := <SINGLE_QUOTED_STRING>
+ | <DOUBLE_QUOTED_STRING>
+ | namedParameter
+ | <INT_LITERAL>
+ | <FLOAT_LITERAL>
+ | <TRUE>
+ | <FALSE>
+ scalarNumericExpression := multiplySubtractExp
+ ( "+" multiplySubtractExp | "-" multiplySubtractExp )*
+ multiplySubtractExp := numericTerm ( "*" numericTerm | "/" numericTerm )*
+ numericTerm := ( "+" )? numericPrimary
+ | "-" numericPrimary
+ numericPrimary := "(" orCondition ")"
+ | pathExpression
+ | namedParameter
+ | <INT_LITERAL>
+ | <FLOAT_LITERAL>
+ namedParameter := "$" <PROPERTY_PATH>
+ pathExpression := ( <PROPERTY_PATH>
+ | "obj:" <PROPERTY_PATH>
+ | "db:" <PROPERTY_PATH>
+ | "enum:" <PROPERTY_PATH> )
+----
+
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/header.html
----------------------------------------------------------------------
diff --git a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/header.html b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/header.html
new file mode 100644
index 0000000..a011d2a
--- /dev/null
+++ b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/header.html
@@ -0,0 +1,28 @@
+---
+# 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.
+
+title: "Cayenne Guide"
+description: "Cayenne Guide"
+cayenneVersion: "4.0"
+weight: 10
+menu:
+ footer:
+ weight: 20
+ parent: docs
+ name: "Cayenne Guide (4.0)"
+---
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/listOfTables.adoc
----------------------------------------------------------------------
diff --git a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/listOfTables.adoc b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/listOfTables.adoc
new file mode 100644
index 0000000..8cd25ae
--- /dev/null
+++ b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/listOfTables.adoc
@@ -0,0 +1,30 @@
+// 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.
+
+== List of tables
+
+* xref:versionHistory[Cayenne Version History]
+* xref:pluginParameteres[modeler plugin parameters]
+* xref:tablecgen[cgen required parameters]
+* xref:cgenOptional[cgen optional parameters]
+* xref:cdbgenTable[cdbgen required parameters]
+* xref:dataSourceParameteres[<dataSource> parameters]
+* xref:cdbgenOptionl[cdbgen optional parameters]
+* xref:cdbimportTable[cdbimport parameters]
+* xref:cdbimportDataSource[<dataSource> parameters]
+* xref:dbimportParameters[<dbimport> parameters]
+* xref:persistenceStates[Persistence States]
+* xref:lifecycleEvent[Lifecycle Event Types]
+* xref:congigProperties[Configuration Properties Recognized by ServerRuntime and/or ClientRuntime]
+* xref:serviceCollections[Service Collection Keys Present in ServerRuntime and/or ClientRuntime]
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part1.adoc
----------------------------------------------------------------------
diff --git a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part1.adoc b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part1.adoc
new file mode 100644
index 0000000..a99d627
--- /dev/null
+++ b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part1.adoc
@@ -0,0 +1,21 @@
+// 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.
+
+== Object Relational Mapping with Cayenne
+
+include::part1/setup.adoc[]
+
+include::part1/mapping.adoc[]
+
+include::part1/modeler.adoc[]
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part1/mapping.adoc
----------------------------------------------------------------------
diff --git a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part1/mapping.adoc b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part1/mapping.adoc
new file mode 100644
index 0000000..ab26eea
--- /dev/null
+++ b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part1/mapping.adoc
@@ -0,0 +1,71 @@
+// 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.
+
+
+=== Cayenne Mapping Structure
+
+==== Cayenne Project
+
+A Cayenne project is an XML representation of a model connecting database schema with Java classes. A project is normally created and manipulated via CayenneModeler GUI and then used to initialize Cayenne runtime. A project is made of one or more files. There's always a root project descriptor file in any valid project. It is normally called cayenne-xyz.xml, where "xyz" is the name of the project.
+
+Project descriptor can reference DataMap files, one per DataMap. DataMap files are normally called xyz.map.xml, where "xyz" is the name of the DataMap. For legacy reasons this naming convention is different from the convention for the root project descriptor above, and we may align it in the future versions. Here is how a typical project might look on the file system:
+
+----
+$ ls -l
+total 24
+-rw-r--r-- 1 cayenne staff 491 Jan 28 18:25 cayenne-project.xml
+-rw-r--r-- 1 cayenne staff 313 Jan 28 18:25 datamap.map.xml
+----
+
+DataMap are referenced by name in the root descriptor:
+
+[source,xml]
+----
+<map name="datamap"/>
+----
+
+Map files are resolved by Cayenne by appending ".map.xml" extension to the map name, and resolving the resulting string relative to the root descriptor URI. The following sections discuss varios ORM model objects, without regards to their XML representation. XML format details are really unimportant to the Cayenne users.
+
+==== DataMap
+
+DataMap is a container of persistent entities and other object-relational metadata. DataMap provides developers with a scope to organize their entities, but it does not provide a namespace for entities. In fact all DataMaps present in runtime are combined in a single namespace. Each DataMap must be associated with a DataNode. This is how Cayenne knows which database to use when running a query.
+
+==== DataNode
+
+DataNode is model of a database. It is actually pretty simple. It has an arbitrary user-provided name and information needed to create or locate a JDBC DataSource. Most projects only have one DataNode, though there may be any number of nodes if needed.
+
+==== DbEntity
+
+DbEntity is a model of a single DB table or view. DbEntity is made of DbAttributes that correspond to columns, and DbRelationships that map PK/FK pairs. DbRelationships are not strictly tied to FK constraints in DB, and should be mapped for all logical "relationships" between the tables.
+
+==== ObjEntity
+
+ObjEntity is a model of a single persistent Java class. ObjEntity is made of ObjAttributes and ObjRelationships. Both correspond to entity class properties. However ObjAttributes represent "simple" properties (normally things like String, numbers, dates, etc.), while ObjRelationships correspond to properties that have a type of another entity.
+
+ObjEntity maps to one or more DbEntities. There's always one "root" DbEntity for each ObjEntity. ObjAttribiute maps to a DbAttribute or an Embeddable. Most often mapped DbAttribute is from the root DbEntity. Sometimes mapping is done to a DbAttribute from another DbEntity somehow related to the root DbEntity. Such ObjAttribute is called "flattened". Similarly ObjRelationship maps either to a single DbRelationship, or to a chain of DbRelationships ("flattened" ObjRelationship).
+
+ObjEntities may also contain mapping of their lifecycle callback methods.
+
+==== Embeddable
+
+Embeddable is a model of a Java class that acts as a single attribute of an ObjEntity, but maps to multiple columns in the database.
+
+==== Procedure
+
+A model of a stored procedure in the database.
+
+==== Query
+
+A model of a query. Cayenne allows queries to be mapped in Cayenne project, or created in the code. Depending on the circumstances the users may take one or the other approach.
+
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part1/modeler.adoc
----------------------------------------------------------------------
diff --git a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part1/modeler.adoc b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part1/modeler.adoc
new file mode 100644
index 0000000..56cf7f1
--- /dev/null
+++ b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part1/modeler.adoc
@@ -0,0 +1,61 @@
+// 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.
+
+=== CayenneModeler Application
+
+==== Working with Mapping Projects
+
+==== Reverse Engineering Database
+
+See chapter xref:reverse[Reverse Engineering in Cayenne Modeler]
+
+==== Generating Database Schema
+
+With Cayenne Modeler you can create simple database schemas without any additional database tools. This is a good option for initial database setup if you completely created you model with the Modeler. You can start SQL schema generation by selecting menu *Tools > Generate Database Schema*
+
+You can select what database parts should be generated and what tables you want
+
+==== Migrations
+
+==== Generating Java Classes
+
+Before using Cayenne in you code you need to generate java source code for persistent objects. This can be done with Modeler GUI or via xref:cgen[cgen] maven/ant plugin.
+
+To generate classes in the modeler use *Tools > Generate Classes*
+
+There is three default types of code generation
+
+- *Standard Persistent Objects*
+
+Default type of generation suitable for almost all cases. Use this type unless you now what exactly you need to customize.
+
+- *Client Persistent Objects*
+
+- *Advanced*
+
+In advanced mode you can control almost all aspects of code generation including custom templates for java code. See default Cayenne templates on GitHub as an example.
+
+==== Modeling Inheritance
+
+==== Modeling Generic Persistent Classes
+
+Normally each ObjEntity is mapped to a specific Java class (such as Artist or Painting) that explicitly declare all entity properties as pairs of getters and setters. However Cayenne allows to map a completly generic class to any number of entities. The only expectation is that a generic class implements org.apache.cayenne.DataObject. So an ideal candidate for a generic class is CayenneDataObject, or some custom subclass of CayenneDataObject.
+
+If you don't enter anything for Java Class of an ObjEntity, Cayenne assumes generic mapping and uses the following implicit rules to determine a class of a generic object. If DataMap "Custom Superclass" is set, runtime uses this class to instantiate new objects. If not, `org.apache.cayenne.CayenneDataObject` is used.
+
+Class generation procedures (either done in the Modeler or with Ant or Maven) would skip entities that are mapped to CayenneDataObject explicitly or have no class mapping.
+
+==== Mapping ObjAttributes to Custom Classes
+
+==== Modeling Primary Key Generation Strategy
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part1/setup.adoc
----------------------------------------------------------------------
diff --git a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part1/setup.adoc b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part1/setup.adoc
new file mode 100644
index 0000000..61431af
--- /dev/null
+++ b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part1/setup.adoc
@@ -0,0 +1,112 @@
+// 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.
+
+include::../var.adoc[]
+
+=== Setup
+
+==== System Requirements
+
+- Java: Cayenne runtime framework and CayenneModeler GUI tool are written in 100% Java, and run on any Java-compatible platform. Minimal required JDK version depends on the version of Cayenne you are using, as shown in the following table:
+
+[#versionHistory.table.table-bordered]
+.Cayenne Version History
+|===
+|Cayenne Version |Java Version |Status
+
+|4.1
+|Java 1.8 or newer
+|Development
+
+|4.0
+|Java 1.7 or newer
+|Beta
+
+|3.1
+|Java 1.5 or newer
+|Stable
+
+|3.0
+|Java 1.5
+|Aging
+
+|1.2 / 2.0
+|Java 1.4
+|Legacy
+
+|1.1
+|Java 1.3
+|Legacy
+|===
+
+
+- JDBC Driver: An appropriate DB-specific JDBC driver is needed to access the database. It can be included in the application or used in web container DataSource configuration.
+
+- Third-party Libraries: Cayenne runtime framework has a minimal set of required and a few more optional dependencies on third-party open source packages. See xref:include["Including Cayenne in a Project"]. chapter for details.
+
+[[runModeler]]
+==== Running CayenneModeler
+
+CayenneModeler GUI tool is intended to work with object relational mapping projects. While you can edit your XML by hand, it is rarely needed, as the Modeler is a pretty advanced tool included in Cayenne distribution. To obtain CayenneModeler, download Cayenne distribution archive from http://cayenne.apache.org/download.html matching the OS you are using. Of course Java needs to be installed on the machine where you are going to run the Modeler.
+
+- OS X distribution contains CayenneModeler.app at the root of the distribution disk image.
+- Windows distribution contains CayenneModeler.exe file in the bin directory.
+- Cross-platform distribution (targeting Linux, but as the name implies, compatible with any OS) contains a runnable CayenneModeler.jar in the bin directory. It can be executed either by double-clicking, or if the environment is not configured to execute jars, by running from command-line:
+
+[source]
+----
+$ java -jar CayenneModeler.jar
+----
+
+The Modeler can also be started from Maven. While it may look like an exotic way to start a GUI application, it has its benefits - no need to download Cayenne distribution, the version of the Modeler always matches the version of the framework, the plugin can find mapping files in the project automatically. So it is an attractive option to some developers. Maven option requires a declaration in the POM:
+[source,xml,subs="verbatim,attributes"]
+----
+<build>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.cayenne.plugins</groupId>
+ <artifactId>cayenne-modeler-maven-plugin</artifactId>
+ <version>{version}</version>
+ </plugin>
+ </plugins>
+</build>
+----
+
+And then can be run as
+
+----
+$ mvn cayenne-modeler:run
+----
+
+[#pluginParameteres.table.table-bordered]
+.Modeler plugin parameters
+[cols="2,1,6"]
+|===
+|Name |Type|Description
+
+.^|modelFile
+.^|File
+a|Name of the model file to open. Here is some simple example:
+[source,xml]
+----
+<plugin>
+ <groupId>org.apache.cayenne.plugins</groupId>
+ <artifactId>cayenne-modeler-maven-plugin</artifactId>
+ <version>${cayenne.version}</version>
+ <configuration>
+ <modelFile>src/main/resources/cayenne.xml</modelFile>
+ </configuration>
+</plugin>
+----
+|===
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2.adoc
----------------------------------------------------------------------
diff --git a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2.adoc b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2.adoc
new file mode 100644
index 0000000..505a029
--- /dev/null
+++ b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2.adoc
@@ -0,0 +1,33 @@
+// 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.
+
+== Cayenne Framework
+
+include::part2/including.adoc[]
+
+include::part2/starting.adoc[]
+
+include::part2/objectContext.adoc[]
+
+include::part2/expressions.adoc[]
+
+include::part2/orderings.adoc[]
+
+include::part2/queries.adoc[]
+
+include::part2/lifecycle.adoc[]
+
+include::part2/tuning.adoc[]
+
+include::part2/customize.adoc[]
\ No newline at end of file
[02/13] cayenne git commit: CAY-2371 Switch documentation from
Docbook to Asciidoctor format
Posted by nt...@apache.org.
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/getting-started-rop/src/docbkx/client-project.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/getting-started-rop/src/docbkx/client-project.xml b/docs/docbook/getting-started-rop/src/docbkx/client-project.xml
deleted file mode 100644
index a777edb..0000000
--- a/docs/docbook/getting-started-rop/src/docbkx/client-project.xml
+++ /dev/null
@@ -1,131 +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.
--->
-<chapter xmlns="http://docbook.org/ns/docbook"
- xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0">
- <title>Starting Client Project</title>
- <section xml:id="create-rop-client-project">
- <title>Create an ROP Client Project in Eclipse</title>
- <para>Creation of a new Eclipse project has been discussed in some details in "Getting
- Started with Cayenne" guide, so we will omit the screenshots for the common
- parts.</para>
- <para>In Eclipse select "File > New > Other..." and then "Maven > Maven Project".
- Click "Next". On the following screen check "Create a simple project" checkbox and click
- "Next" again. In the dialog shown on the screenshot below, enter "org.example.cayenne"
- for the "Group Id" and "tutorial-rop-client" for the "Artifact Id" (both without the
- quotes) and click "Finish". </para>
- <para>Now you should have a new empty project in the Eclipse workspace. Check that the
- project Java compiler settings are correct. Rightclick on the "tutorial-rop-client"
- project, select "Properties > Java Compiler" and ensure that "Compiler compliance
- level" is at least 1.5 (some versions of Maven plugin seem to be setting it to 1.4 by
- default).</para>
- </section>
- <section xml:id="create-client-java-classes">
- <title>Create Client Java Classes</title>
- <para>The client doesn't need the XML ORM mapping, as it is loaded from the server. However
- it needs the client-side Java classes. Let's generate them from the existing
- mapping:</para>
- <itemizedlist>
- <listitem>
- <para>Start CayenneModeler and open cayenne.xml from the "tutorial" project (located
- under "tutorial/src/main/resources", unless it is already open.</para>
- </listitem>
- <listitem>
- <para>Select the "datamap" DataMap and check "Allow Client Entities"
- checkbox.</para>
- </listitem>
- <listitem>
- <para>Enter "org.example.cayenne.persistent.client" for the "Client Java Package"
- and click "Update.." button next to the field to refresh the client package of
- all entities.</para>
- <para><inlinemediaobject>
- <imageobject>
- <imagedata fileref="images/datamap-enableclient.png" scalefit="1" width="100%"/>
- </imageobject>
- </inlinemediaobject></para>
- </listitem>
- </itemizedlist>
- <itemizedlist>
- <listitem>
- <para>Select "Tools > Generate Classes" menu.</para>
- </listitem>
- <listitem>
- <para>For "Type" select "Client Persistent Objects".</para>
- </listitem>
- <listitem>
- <para>For the "Output Directory" select "tutorial-rop-client/src/main/java" folder
- (as client classes should go in the <emphasis role="italic">client</emphasis>
- project).</para>
- </listitem>
- <listitem>
- <para>Click on "Classes" tab and check the "Check All Classes" checkbox (unless it
- is already checked and reads "Uncheck all Classes").</para>
- </listitem>
- <listitem>
- <para>Click "Generate".</para>
- </listitem>
- </itemizedlist>
- <para>Now go back to Eclipse, right click on "tutorial-rop-client" project and select
- "Refresh" - you should see pairs of classes generated for each mapped entity, same as on
- the server. And again, we see a bunch of errors in those classes. Let's fix it now by
- adding two dependencies, "cayenne-client" and "resin-hessian", in the bottom of the
- pom.xml file. We also need to add Caucho M2 repository to pull Hessian jar files. The
- resulting POM should look like this:</para>
- <programlisting><project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
- <modelVersion>4.0.0</modelVersion>
- <groupId>org.example.cayenne</groupId>
- <artifactId>tutorial-rop-client</artifactId>
- <version>0.0.1-SNAPSHOT</version>
-
- <dependencies>
- <dependency>
- <groupId>org.apache.cayenne</groupId>
- <artifactId>cayenne-client</artifactId>
- <!-- Here specify the version of Cayenne you are actually using -->
- <version>4.0.M3</version>
- </dependency>
- <dependency>
- <groupId>com.caucho</groupId>
- <artifactId>hessian</artifactId>
- <version>4.0.38</version>
- </dependency>
- </dependencies>
-
- <repositories>
- <repository>
- <id>caucho</id>
- <name>Caucho Repository</name>
- <url>http://caucho.com/m2</url>
- <layout>default</layout>
- <snapshots>
- <enabled>false</enabled>
- </snapshots>
- <releases>
- <enabled>true</enabled>
- </releases>
- </repository>
- </repositories>
-</project></programlisting>
- <para>Your computer must be connected to the internet. Once you save the pom.xml, Eclipse
- will download the needed jar files and add them to the project build path. After that
- all the errors should disappear.</para>
- <para>Now let's check the entity class pairs. They look almost identical to their server
- counterparts, although the superclass and the property access code are different. At
- this point these differences are somewhat academic, so let's go on with the
- tutorial.</para>
- </section>
-</chapter>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/getting-started-rop/src/docbkx/index.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/getting-started-rop/src/docbkx/index.xml b/docs/docbook/getting-started-rop/src/docbkx/index.xml
deleted file mode 100644
index c6814f4..0000000
--- a/docs/docbook/getting-started-rop/src/docbkx/index.xml
+++ /dev/null
@@ -1,43 +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.
--->
-<book xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
- xml:id="getting-started-rop" xmlns:xi="http://www.w3.org/2001/XInclude">
- <info>
- <title>Getting Started with Cayenne ROP (Remote Object Persistence)</title>
- <copyright>
- <year>2011-<?dbtimestamp format="Y"?></year>
- <holder>Apache Software Foundation and individual authors</holder>
- </copyright>
- <legalnotice>
- <title>License</title>
- <para>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</para>
-
- <para>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.</para>
- </legalnotice>
- </info>
- <xi:include href="part1.xml"/>
- <xi:include href="part2.xml"/>
-</book>
-
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/getting-started-rop/src/docbkx/part1.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/getting-started-rop/src/docbkx/part1.xml b/docs/docbook/getting-started-rop/src/docbkx/part1.xml
deleted file mode 100644
index cf86a52..0000000
--- a/docs/docbook/getting-started-rop/src/docbkx/part1.xml
+++ /dev/null
@@ -1,22 +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.
--->
-<part xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
- xml:id="getting-started-rop-part1" xmlns:xi="http://www.w3.org/2001/XInclude">
- <title>Prerequisites</title>
- <xi:include href="setup.xml"/>
-</part>
-
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/getting-started-rop/src/docbkx/part2.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/getting-started-rop/src/docbkx/part2.xml b/docs/docbook/getting-started-rop/src/docbkx/part2.xml
deleted file mode 100644
index 3f17927..0000000
--- a/docs/docbook/getting-started-rop/src/docbkx/part2.xml
+++ /dev/null
@@ -1,24 +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.
--->
-<part xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
- xml:id="getting-started-rop-part2" xmlns:xi="http://www.w3.org/2001/XInclude">
- <title>Remote Object Persistence Quick Start</title>
- <xi:include href="client-project.xml"/>
- <xi:include href="web-service.xml"/>
- <xi:include href="client-code.xml"/>
- <xi:include href="authentication.xml"/>
-</part>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/getting-started-rop/src/docbkx/setup.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/getting-started-rop/src/docbkx/setup.xml b/docs/docbook/getting-started-rop/src/docbkx/setup.xml
deleted file mode 100644
index 4c5f5b9..0000000
--- a/docs/docbook/getting-started-rop/src/docbkx/setup.xml
+++ /dev/null
@@ -1,53 +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.
--->
-<chapter xmlns="http://docbook.org/ns/docbook"
- xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0">
- <title>Prerequisites</title>
- <para>This tutorial starts where "Getting Started with Cayenne" left
- off. If you have gone through the previous tutorial, and have the "tutorial" project open in
- Eclipse, you can go directly to the
- next step. If not, here are the compressed instructions to prepare you for work
- with ROP:</para>
- <itemizedlist>
- <listitem>
- <para>
- Step 1 - Eclipse Setup
- </para>
- </listitem>
- <listitem>
- <para>
- Step 2 - Create a project
- </para>
- </listitem>
- <listitem>
- <para>
- Step 3 - Create Cayenne OR Mapping
- </para>
- </listitem>
- <listitem>
- <para>
- Step 4 - Create Java Classes
- </para>
- </listitem>
- <listitem>
- <para>
- Step 5 - Convert the project to webapp.</para>
- </listitem>
- </itemizedlist>
- <para>Note that at "Step 5" you can skip the JSP creation part. Just setup web.xml and
- maven-jetty-plugin in the POM.</para>
-</chapter>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/getting-started-rop/src/docbkx/web-service.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/getting-started-rop/src/docbkx/web-service.xml b/docs/docbook/getting-started-rop/src/docbkx/web-service.xml
deleted file mode 100644
index 62ad70f..0000000
--- a/docs/docbook/getting-started-rop/src/docbkx/web-service.xml
+++ /dev/null
@@ -1,131 +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.
--->
-<chapter xmlns="http://docbook.org/ns/docbook"
- xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0">
- <title>Setting up Hessian Web Service</title>
- <section xml:id="setting-up-dependencies">
- <title>Setting up Dependencies</title>
- <para>Now lets get back to the "tutorial" project that contains a web application and set up
- dependencies. The only extra one that we don't have yet is resin-hessian.jar, just like
- the client, so let's add it (and the caucho repo declaration) to the pom.xml.</para>
- <programlisting><project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
- ...
- <dependencies>
- ...
- <dependency>
- <groupId>com.caucho</groupId>
- <artifactId>hessian</artifactId>
- <version>4.0.38</version>
- </dependency>
- </dependencies>
-
- <build>
- ...
- </build>
-
- <repositories>
- <repository>
- <id>caucho</id>
- <name>Caucho Repository</name>
- <url>http://caucho.com/m2</url>
- <layout>default</layout>
- <snapshots>
- <enabled>false</enabled>
- </snapshots>
- <releases>
- <enabled>true</enabled>
- </releases>
- </repository>
- </repositories>
- </project></programlisting>
-
- <note>
- <para><emphasis role="bold">Maven Optimization
- Hint</emphasis> On a real project both server and client modules will
- likely share a common parent pom.xml where common repository delcaration can
- be placed, with child pom's "inheriting" it from parent. This would reduce
- build code duplication.</para>
- </note>
- </section>
- <section xml:id="client-classes-on-server">
- <title>Client Classes on the Server</title>
- <para>Since ROP web service requires both server and client persistent classes, we need to
- generate a second copy of the client classes inside the server project. This is a minor
- inconvenience that will hopefully go away in the future versions of Cayenne. <emphasis
- role="italic">Don't forget to refresh the project in Eclipse after class generation
- is done.</emphasis></para>
- </section>
- <section xml:id="configuring-web-xml">
- <title>Configuring web.xml</title>
- <para>Cayenne web service is declared in the web.xml. It is implemented as a servlet
- "org.apache.cayenne.rop.ROPServlet". Open
- tutorial/src/main/webapp/WEB-INF/web.xml in Eclipse and add a service declaration: </para>
- <programlisting><?xml version="1.0" encoding="utf-8"?>
- <!DOCTYPE web-app
- PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
- "http://java.sun.com/dtd/web-app_2_3.dtd">
-<web-app>
- <display-name>Cayenne Tutorial</display-name>
- <servlet>
- <servlet-name>cayenne-project</servlet-name>
- <servlet-class>org.apache.cayenne.rop.ROPServlet</servlet-class>
- <load-on-startup>0</load-on-startup>
- </servlet>
- <servlet-mapping>
- <servlet-name>cayenne-project</servlet-name>
- <url-pattern>/cayenne-service</url-pattern>
- </servlet-mapping>
- </web-app></programlisting>
- <note>
- <para><emphasis role="bold">Extending Server Behavior via
- Callbacks</emphasis> While no custom Java code is required on the
- server, just a service declaration, it is possible to customizing
- server-side behavior via callbacks and listeners (not shown in the
- tutorial).</para>
- </note>
- </section>
- <section xml:id="running-rop-server">
- <title>Running ROP Server</title>
- <para>Use previosly
- created Eclipse Jetty run configuration available via "Run > Run
- Configurations..." (or create a new
- one if none exists yet). You should see output in the Eclipse console similar
- to the following:</para>
- <programlisting>[INFO] Scanning for projects...
-[INFO]
-[INFO] ------------------------------------------------------------------------
-[INFO] Building tutorial 0.0.1-SNAPSHOT
-[INFO] ------------------------------------------------------------------------
-...
-[INFO] Starting jetty 6.1.22 ...
-INFO::jetty-6.1.22
-INFO::No Transaction manager found - if your webapp requires one, please configure one.
-INFO::Started SelectChannelConnector@0.0.0.0:8080
-[INFO] Started Jetty Server
-INFO: Loading XML configuration resource from file:cayenne-project.xml
-INFO: loading user name and password.
-INFO: Created connection pool: jdbc:derby:memory:testdb;create=true
- Driver class: org.apache.derby.jdbc.EmbeddedDriver
- Min. connections in the pool: 1
- Max. connections in the pool: 1</programlisting>
- <para>Cayenne ROP service URL is <emphasis role="italic"
- >http://localhost:8080/tutorial/cayenne-service</emphasis>. If you click on it, you
- will see "Hessian Requires POST" message, that means that the service is alive, but you
- need a client other than the web browser to access it.</para>
- </section>
-</chapter>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/getting-started-rop/src/images/datamap-enableclient.png
----------------------------------------------------------------------
diff --git a/docs/docbook/getting-started-rop/src/images/datamap-enableclient.png b/docs/docbook/getting-started-rop/src/images/datamap-enableclient.png
deleted file mode 100644
index 62a2af2..0000000
Binary files a/docs/docbook/getting-started-rop/src/images/datamap-enableclient.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/getting-started/pom.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/getting-started/pom.xml b/docs/docbook/getting-started/pom.xml
deleted file mode 100644
index e56ecf3..0000000
--- a/docs/docbook/getting-started/pom.xml
+++ /dev/null
@@ -1,40 +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.
--->
-
-<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
- <parent>
- <groupId>org.apache.cayenne.docs</groupId>
- <artifactId>cayenne-docbook</artifactId>
- <version>4.0.B3-SNAPSHOT</version>
- </parent>
-
- <modelVersion>4.0.0</modelVersion>
- <artifactId>getting-started</artifactId>
- <packaging>jar</packaging>
- <name>getting-started: Docbook - Getting Started with Cayenne</name>
-
- <build>
- <resources>
- <resource>
- <directory>target/site</directory>
- </resource>
- </resources>
- </build>
-</project>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/getting-started/src/docbkx/delete.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/getting-started/src/docbkx/delete.xml b/docs/docbook/getting-started/src/docbkx/delete.xml
deleted file mode 100644
index b2ecdb3..0000000
--- a/docs/docbook/getting-started/src/docbkx/delete.xml
+++ /dev/null
@@ -1,79 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<?xml-model href="http://www.oasis-open.org/docbook/xml/5.0/rng/docbook.rng" schematypens="http://relaxng.org/ns/structure/1.0"?>
-<!--
- 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.
--->
-<section xmlns="http://docbook.org/ns/docbook"
- xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0">
- <title>Deleting Objects</title>
- <para>This chapter explains how to model relationship delete rules and how to delete individual
- objects as well as sets of objects. Also demonstrated the use of Cayenne class to run a
- query.</para>
- <section xml:id="setup-delete-rules">
- <title>Setting Up Delete Rules</title>
- <para>Before we discuss the API for object deletion, lets go back to CayenneModeler and set
- up some delete rules. Doing this is optional but will simplify correct handling of the
- objects related to deleted objects.</para>
- <para>In the Modeler go to "Artist" ObjEntity, "Relationships" tab and select "Cascade" for
- the "paintings" relationship delete rule:</para>
- <para><inlinemediaobject>
- <imageobject>
- <imagedata fileref="images/modeler-deleterule.png" scalefit="1" width="100%"/>
- </imageobject>
- </inlinemediaobject>
- </para>
- <para>Repeat this step for other relationships:</para>
- <itemizedlist>
- <listitem>
- <para>For Gallery set "paintings" relationship to be "Nullify", as a painting can
- exist without being displayed in a gallery.</para>
- </listitem>
- <listitem>
- <para>For Painting set both relationships rules to "Nullify".</para>
- </listitem>
- </itemizedlist>
- <para>Now save the mapping.</para>
- </section>
- <section xml:id="deleting-objects">
- <title>Deleting Objects</title>
- <para>While deleting objects is possible via SQL, qualifying a delete on one or more IDs, a
- more common way in Cayenne (or ORM in general) is to get a hold of the object first, and
- then delete it via the context. Let's use utility class Cayenne to find an
- artist:</para>
- <programlisting language="java">Artist picasso = ObjectSelect.query(Artist.class)
- .where(Artist.NAME.eq("Pablo Picasso")).selectOne(context);</programlisting>
- <para>Now let's delete the artist:</para>
- <programlisting language="java">if (picasso != null) {
- context.deleteObject(picasso);
- context.commitChanges();
-}</programlisting>
- <para>Since we set up "Cascade" delete rule for the Artist.paintings relationships, Cayenne
- will automatically delete all paintings of this artist. So when your run the app you'll
- see this output:</para>
- <screen>INFO: SELECT t0.DATE_OF_BIRTH, t0.NAME, t0.ID FROM ARTIST t0
- WHERE t0.NAME = ? [bind: 1->NAME:'Pablo Picasso'] - prepared in 6 ms.
-INFO: === returned 1 row. - took 18 ms.
-INFO: +++ transaction committed.
-INFO: --- transaction started.
-INFO: DELETE FROM PAINTING WHERE ID = ?
-INFO: [batch bind: 1->ID:200]
-INFO: [batch bind: 1->ID:201]
-INFO: === updated 2 rows.
-INFO: DELETE FROM ARTIST WHERE ID = ?
-INFO: [batch bind: 1->ID:200]
-INFO: === updated 1 row.
-INFO: +++ transaction committed.</screen>
- </section>
-</section>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/getting-started/src/docbkx/index.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/getting-started/src/docbkx/index.xml b/docs/docbook/getting-started/src/docbkx/index.xml
deleted file mode 100644
index 433c098..0000000
--- a/docs/docbook/getting-started/src/docbkx/index.xml
+++ /dev/null
@@ -1,44 +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.
--->
-<book xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
- xml:id="getting-started" xmlns:xi="http://www.w3.org/2001/XInclude">
- <info>
- <title>Getting Started with Cayenne</title>
- <copyright>
- <year>2011-<?dbtimestamp format="Y"?></year>
- <holder>Apache Software Foundation and individual authors</holder>
- </copyright>
- <legalnotice>
- <title>License</title>
- <para>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</para>
-
- <para>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.</para>
- </legalnotice>
- </info>
- <xi:include href="part1.xml"/>
- <xi:include href="part2.xml"/>
- <xi:include href="part3.xml"/>
- <xi:include href="part4.xml"/>
-</book>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/getting-started/src/docbkx/java-classes.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/getting-started/src/docbkx/java-classes.xml b/docs/docbook/getting-started/src/docbkx/java-classes.xml
deleted file mode 100644
index 34ab663..0000000
--- a/docs/docbook/getting-started/src/docbkx/java-classes.xml
+++ /dev/null
@@ -1,129 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<?xml-model href="http://www.oasis-open.org/docbook/xml/5.0/rng/docbook.rng" schematypens="http://relaxng.org/ns/structure/1.0"?>
-<!--
- 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.
--->
-<section xmlns="http://docbook.org/ns/docbook"
- xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0">
- <title>Creating Java Classes</title>
- <para>Here we'll generate the Java classes from the model that was created in the previous
- section. CayenneModeler can be used to also generate the database schema, but since we
- specified "<code>CreateIfNoSchemaStrategy</code>" earlier when we created a DataNode, we'll skip the
- database schema step. Still be aware that you can do it if you need to via "Tools >
- Create Database Schema".
- </para>
- <section xml:id="creating-java-classes">
- <title>Creating Java Classes</title>
- <itemizedlist>
- <listitem>
- <para>Select "Tools > Generate Classes" menu.</para>
- </listitem>
- <listitem>
- <para>For "Type" select "Standard Persistent Objects", if it is not already
- selected.</para>
- </listitem>
- <listitem>
- <para>For the "Output Directory" select "<code>src/main/java</code>" folder under your IDEA
- project folder (this is a "peer" location to the <code>cayenne-*.xml</code> location we
- selected before).</para>
- </listitem>
- <listitem>
- <para>Click on "Classes" tab and check the "Check All Classes" checkbox (unless it
- is already checked and reads "Uncheck all Classes").</para>
- </listitem>
- <listitem>
- <para>Click "Generate"</para>
- </listitem>
- </itemizedlist>
- <para>Now go back to IDEA - you
- should see pairs of classes generated for each mapped entity. You probably also see that
- there's a bunch of red squiggles next to the newly generated Java classes in IDEA.
- This is because our project does not include Cayenne as a Maven dependency yet. Let's
- fix it now by adding "cayenne-server" and "cayenne-java8" artifacts in the bottom of the <code>pom.xml</code> file.
- Also we should tell Maven compile plugin that our project needs Java 8.
- The resulting POM should look like
- this:<programlisting language="xml"><project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
- <modelVersion>4.0.0</modelVersion>
- <groupId>org.example.cayenne</groupId>
- <artifactId>tutorial</artifactId>
- <version>0.0.1-SNAPSHOT</version>
-
- <dependencies>
- <dependency>
- <groupId>org.apache.cayenne</groupId>
- <artifactId>cayenne-server</artifactId>
- <!-- Here specify the version of Cayenne you are actually using -->
- <version><?eval ${project.version}?></version>
- </dependency>
- <!-- For java.time.* types you need to use this dependency-->
- <dependency>
- <groupId>org.apache.cayenne</groupId>
- <artifactId>cayenne-java8</artifactId>
- <version><?eval ${project.version}?></version>
- </dependency>
- <dependency>
- <groupId>org.slf4j</groupId>
- <artifactId>slf4j-simple</artifactId>
- <version>1.7.25</version>
- </dependency>
- </dependencies>
-
- <build>
- <plugins>
- <!-- Tell maven to support Java 8 -->
- <plugin>
- <groupId>org.apache.maven.plugins</groupId>
- <artifactId>maven-compiler-plugin</artifactId>
- <version>3.6.1</version>
- <configuration>
- <source>1.8</source>
- <target>1.8</target>
- </configuration>
- </plugin>
- </plugins>
- </build>
-</project></programlisting></para>
- <para>Your computer must be connected to the internet. Once you edit the <code>pom.xml</code>, IDEA
- will download the needed Cayenne jar file and add it to the project build path. As a
- result, all the errors should disappear. In tutorial for console output we use slf4j-simple logger
- implementation. Due to use SLF4J logger in Apache Cayenne, you can use your custom logger (e.g. log4j
- or commons-logging) through bridges.
- </para>
- <para><inlinemediaobject>
- <imageobject>
- <imagedata fileref="images/idea-generated-classes.png" scalefit="1" width="100%"/>
- </imageobject>
- </inlinemediaobject></para>
- <para>Now let's check the entity class pairs. Each one is made of a superclass (e.g. <code>_Artist</code>)
- and a subclass (e.g. <code>Artist</code>). You <emphasis role="bold">should not</emphasis> modify the
- superclasses whose names start with "_" (underscore), as they will be replaced on
- subsequent generator runs. Instead all custom logic should be placed in the subclasses
- in "<code>org.example.cayenne.persistent</code>" package - those will never be overwritten by the
- class generator.</para>
- <para>
- <note>
- <title>Class Generation Hint</title>
- <para> Often you'd start by generating classes from the
- Modeler, but at the later stages of the project the generation is usually
- automated either via Ant cgen task or Maven cgen mojo. All three methods are
- interchangeable, however Ant and Maven methods would ensure that you never
- forget to regenerate classes on mapping changes, as they are integrated into
- the build cycle.</para>
- </note>
- </para>
-
- </section>
-</section>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/getting-started/src/docbkx/object-context.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/getting-started/src/docbkx/object-context.xml b/docs/docbook/getting-started/src/docbkx/object-context.xml
deleted file mode 100644
index d17b64a..0000000
--- a/docs/docbook/getting-started/src/docbkx/object-context.xml
+++ /dev/null
@@ -1,103 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<?xml-model href="http://www.oasis-open.org/docbook/xml/5.0/rng/docbook.rng" schematypens="http://relaxng.org/ns/structure/1.0"?>
-<!--
- 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.
--->
-<section xmlns="http://docbook.org/ns/docbook"
- xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0">
- <title>Getting started with ObjectContext</title>
- <para>In this section we'll write a simple main class to run our application, and get a brief
- introduction to Cayenne ObjectContext.</para>
- <section xml:id="creating-main-class">
- <title>Creating the Main Class</title>
- <itemizedlist>
- <listitem>
- <para>In IDEA create a new class called "<code>Main</code>" in the "<code>org.example.cayenne</code>"
- package.</para>
- </listitem>
- <listitem>
- <para>Create a standard "main" method to make it a runnable
- class:<programlisting language="java">package org.example.cayenne;
-
-public class Main {
-
- public static void main(String[] args) {
-
- }
-}</programlisting></para>
- </listitem>
- <listitem>
- <para>The first thing you need to be able to access the database is to create a
- <code>ServerRuntime</code> object (which is essentially a wrapper around Cayenne stack) and
- use it to obtain an instance of an
- <code>ObjectContext</code>.<programlisting language="java">package org.example.cayenne;
-
-import org.apache.cayenne.ObjectContext;
-import org.apache.cayenne.configuration.server.ServerRuntime;
-
-public class Main {
-
- public static void main(String[] args) {
- ServerRuntime cayenneRuntime = ServerRuntime.builder()
- .addConfig("cayenne-project.xml")
- .build();
- ObjectContext context = cayenneRuntime.newContext();
- }
-}</programlisting></para>
- <para><code>ObjectContext</code> is an isolated "session" in Cayenne that provides all needed API
- to work with data. ObjectContext has methods to execute queries and manage
- persistent objects. We'll discuss them in the following sections. When the first
- ObjectContext is created in the application, Cayenne loads XML mapping files and
- creates a shared access stack that is later reused by other ObjectContexts.
- </para>
- </listitem>
- </itemizedlist>
- </section>
- <section xml:id="runnning-app">
- <title>Running Application</title>
- <para>Let's check what happens when you run the application. But before we do that we need
- to add another dependency to the <code>pom.xml</code> - Apache Derby, our embedded database engine.
- The following piece of XML needs to be added to the
- <code><dependencies>...</dependencies></code> section, where we already have Cayenne
- jars:<programlisting language="xml"><dependency>
- <groupId>org.apache.derby</groupId>
- <artifactId>derby</artifactId>
- <version>10.13.1.1</version>
-</dependency></programlisting>Now
- we are ready to run. Right click the "Main" class in IDEA and select "Run 'Main.main()'".
- </para>
- <para>
- <inlinemediaobject>
- <imageobject>
- <imagedata fileref="images/idea-file-run-menu.png"/>
- </imageobject>
- </inlinemediaobject>
- </para>
- <para>
- In the console you'll see output similar to this, indicating that Cayenne stack has been started:
- <screen>INFO: Loading XML configuration resource from file:/.../cayenne-project.xml
-INFO: Loading XML DataMap resource from file:/.../datamap.map.xml
-INFO: loading user name and password.
-INFO: Connecting to 'jdbc:derby:memory:testdb;create=true' as 'null'
-INFO: +++ Connecting: SUCCESS.
-INFO: setting DataNode 'datanode' as default, used by all unlinked DataMaps</screen>
-
- <note>
- <title>How to Configure Cayenne Logging</title>
- <para>Follow the instructions in the logging chapter to tweak verbosity of the logging output.</para>
- </note>
- </para>
- </section>
-</section>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/getting-started/src/docbkx/object-relational-mapping.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/getting-started/src/docbkx/object-relational-mapping.xml b/docs/docbook/getting-started/src/docbkx/object-relational-mapping.xml
deleted file mode 100644
index ba2b771..0000000
--- a/docs/docbook/getting-started/src/docbkx/object-relational-mapping.xml
+++ /dev/null
@@ -1,184 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<?xml-model href="http://www.oasis-open.org/docbook/xml/5.0/rng/docbook.rng" schematypens="http://relaxng.org/ns/structure/1.0"?>
-<!--
- 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.
--->
-<section xmlns="http://docbook.org/ns/docbook"
- xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0">
- <title>Getting started with Object Relational Mapping (ORM)</title>
- <para> The goal of this section is to learn how to create a simple Object-Relational model with
- CayenneModeler. We will create a complete ORM model for the following database
- schema:</para>
- <para><inlinemediaobject>
- <imageobject>
- <imagedata fileref="images/database-schema.jpg"/>
- </imageobject>
- </inlinemediaobject>
- </para>
- <para>
- <note><para>Very often you'd have an existing database already, and
- it can be quickly imported in Cayenne via "Tools > Reengineer Database
- Schema". This will save you lots of time compared to manual mapping. However
- understanding how to create the mapping by hand is important, so we are showing
- the "manual" approach below.</para></note>
- </para>
- <section xml:id="mapping-db-tables-and-columns">
- <title>Mapping Database Tables and Columns</title>
- <para>Lets go back to CayenneModeler where we have the newly created project open and start
- by adding the ARTIST table. Database tables are called <emphasis role="bold">"DbEntities"</emphasis>
- in Cayenne mapping (those can be actual tables or database views).
- </para>
- <para>Select "datamap" on the left-hand side project tree and click "Create DbEntity" button <inlinemediaobject>
- <imageobject>
- <imagedata fileref="images/icon-dbentity.png"/>
- </imageobject>
- </inlinemediaobject>
- (or use "Project > Create DbEntity" menu). A new DbEntity is created. In "DbEntity
- Name" field enter "ARTIST". Then click on "Create Attribute" button <inlinemediaobject>
- <imageobject>
- <imagedata fileref="images/icon-attribute.png"/>
- </imageobject>
- </inlinemediaobject> on the entity
- toolbar. This action changes the view to the "Attribute"
- tab and adds a new attribute (attribute means a "table column" in this case) called
- "untitledAttr". Let's rename it to ID, make it an <code>INTEGER</code> and make it a PK:
- </para>
- <para><inlinemediaobject>
- <imageobject>
- <imagedata fileref="images/modeler-artistid.png" scalefit="1" width="100%"/>
- </imageobject>
- </inlinemediaobject></para>
- <para>Similarly add NAME <code>VARCHAR(200)</code> and DATE_OF_BIRTH <code>DATE</code> attributes. After that repeat
- this procedure for PAINTING and GALLERY entities to match DB schema shown above.</para>
- <para>
- <note>
- <para>
- Don't forget to save your project periodically to avoid losing your work.
- </para>
- </note>
- </para>
- </section>
- <section xml:id="mapping-db-relationships">
- <title>Mapping Database Relationships</title>
- <para>Now we need to specify relationships between ARTIST, PAINTING and GALLERY tables.
- Start by creating a one-to-many ARTIST/PAINTING relationship:</para>
- <itemizedlist>
- <listitem>
- <para>Select the ARTIST DbEntity on the left and click on the "Properties"
- tab.</para>
- </listitem>
- <listitem>
- <para>Click on "Create Relationship" button on the entity toolbar <inlinemediaobject>
- <imageobject>
- <imagedata fileref="images/icon-relationship.png"/>
- </imageobject>
- </inlinemediaobject> - a relationship called "untitledRel" is created.</para>
- </listitem>
- <listitem>
- <para>Choose the "Target" to be "Painting".</para>
- </listitem>
- <listitem>
- <para>Click on the "Database Mapping" button <inlinemediaobject>
- <imageobject>
- <imagedata fileref="images/icon-edit.png"/>
- </imageobject>
- </inlinemediaobject> - relationship
- configuration dialog is presented. Here you can assign a name to the
- relationship and also its complimentary reverse relationship. This name can be
- anything (this is really a symbolic name of the database referential
- constraint), but it is recommended to use a valid Java identifier, as this will
- save some typing later. We'll call the relationship "paintings" and reverse
- relationship "artist".</para>
- </listitem>
- <listitem>
- <para>Click on "Add" button on the right to add a join</para>
- </listitem>
- <listitem>
- <para>Select "ID" column for the "Source" and "ARTIST_ID" column for the
- target.</para>
- </listitem>
- <listitem>
- <para>Relationship information should now look like this:</para>
- </listitem>
- </itemizedlist>
- <para><inlinemediaobject>
- <imageobject>
- <imagedata fileref="images/modeler-dbrelationship.png" scalefit="1" width="100%"/>
- </imageobject>
- </inlinemediaobject></para>
- <itemizedlist>
- <listitem>
- <para>Click "Done" to confirm the changes and close the dialog.</para>
- </listitem>
- <listitem>
- <para>Two complimentary relationships have been created - from ARTIST to PAINTING
- and back. Still you may have noticed one thing is missing - "paintings"
- relationship should be to-many, but "To Many" checkbox is not checked. Let's
- change that - check the checkbox for "paintings" relationship, and then click on
- PAINTING DbEntity, and uncheck "artist" relationship "To Many" to make the
- reverse relationship "to-one" as it should be.</para>
- </listitem>
- <listitem>
- <para>Repeat the steps above to create a many-to-one relationship from PAINTING to
- GALLERY, calling the relationships pair "gallery" and "paintings".</para>
- </listitem>
- </itemizedlist>
- </section>
- <section xml:id="mapping-java-classes">
- <title>Mapping Java Classes</title>
- <para>Now that the database schema mapping is complete, CayenneModeler can create mappings
- of Java classes (aka "ObjEntities") by deriving everything from DbEntities. At present
- there is no way to do it for the entire DataMap in one click, so we'll do it for each
- table individually.</para>
- <itemizedlist>
- <listitem>
- <para>Select "ARTIST" DbEntity and click on "Create ObjEntity" button <inlinemediaobject>
- <imageobject>
- <imagedata fileref="images/icon-new_objentity.png"/>
- </imageobject>
- </inlinemediaobject> either on the entity toolbar or on the main toolbar. An ObjEntity called
- "Artist" is created with a Java class field set to
- "org.example.cayenne.persistent.Artist". The modeler transformed the database
- names to the Java-friendly names (e.g., if you click on the "Attributes" tab,
- you'll see that "DATE_OF_BIRTH" column was converted to "dateOfBirth" Java class
- attribute).</para>
- </listitem>
- <listitem>
- <para>Select "GALLERY" DbEntity and click on "Create ObjEntity" button again -
- you'll see a "Gallery" ObjEntity created.</para>
- </listitem>
- <listitem>
- <para>Finally, do the same thing for "PAINTING".</para>
- </listitem>
- </itemizedlist>
- <para>Now you need to synchronize relationships. Artist and Gallery entities were created
- when there was no related "Painting" entity, so their relationships were not set. <itemizedlist>
- <listitem>
- <para>Click on the "Artist" ObjEntity. Now click on "Sync ObjEntity with DbEntity" button on
- the toolbar <inlinemediaobject>
- <imageobject>
- <imagedata fileref="images/icon-sync.png"/>
- </imageobject>
- </inlinemediaobject> - you will see the "paintings" relationship
- appear.</para>
- </listitem>
- <listitem>
- <para>Do the same for the "Gallery" entity.</para>
- </listitem>
- </itemizedlist></para>
- <para>Unless you want to customize the Java class and property names (which you can do
- easily) the mapping is complete. </para>
- </section>
-</section>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/getting-started/src/docbkx/part1.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/getting-started/src/docbkx/part1.xml b/docs/docbook/getting-started/src/docbkx/part1.xml
deleted file mode 100644
index a08bd3e..0000000
--- a/docs/docbook/getting-started/src/docbkx/part1.xml
+++ /dev/null
@@ -1,21 +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.
--->
-<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
- xml:id="getting-started-part1" xmlns:xi="http://www.w3.org/2001/XInclude">
- <title>Setting up the environment</title>
- <xi:include href="setup.xml"/>
-</chapter>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/getting-started/src/docbkx/part2.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/getting-started/src/docbkx/part2.xml b/docs/docbook/getting-started/src/docbkx/part2.xml
deleted file mode 100644
index 9a1f247..0000000
--- a/docs/docbook/getting-started/src/docbkx/part2.xml
+++ /dev/null
@@ -1,25 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<?xml-model href="http://www.oasis-open.org/docbook/xml/5.0/rng/docbook.rng" schematypens="http://relaxng.org/ns/structure/1.0"?>
-<!--
- 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="getting-started-part2" xmlns:xi="http://www.w3.org/2001/XInclude">
- <title>Learning mapping basics</title>
- <xi:include href="starting-project.xml"/>
- <xi:include href="object-relational-mapping.xml"/>
- <xi:include href="java-classes.xml"/>
-</chapter>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/getting-started/src/docbkx/part3.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/getting-started/src/docbkx/part3.xml b/docs/docbook/getting-started/src/docbkx/part3.xml
deleted file mode 100644
index cc4bcd9..0000000
--- a/docs/docbook/getting-started/src/docbkx/part3.xml
+++ /dev/null
@@ -1,26 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<?xml-model href="http://www.oasis-open.org/docbook/xml/5.0/rng/docbook.rng" schematypens="http://relaxng.org/ns/structure/1.0"?>
-<!--
- 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="getting-started-part3" xmlns:xi="http://www.w3.org/2001/XInclude">
- <title>Learning Cayenne API</title>
- <xi:include href="object-context.xml"/>
- <xi:include href="persistent-objects.xml"/>
- <xi:include href="select-query.xml"/>
- <xi:include href="delete.xml"/>
-</chapter>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/getting-started/src/docbkx/part4.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/getting-started/src/docbkx/part4.xml b/docs/docbook/getting-started/src/docbkx/part4.xml
deleted file mode 100644
index ad87fa9..0000000
--- a/docs/docbook/getting-started/src/docbkx/part4.xml
+++ /dev/null
@@ -1,22 +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.
--->
-<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
- xml:id="getting-started-part4" xmlns:xi="http://www.w3.org/2001/XInclude">
- <title>Converting to Web Application</title>
- <xi:include href="webapp.xml"/>
-</chapter>
-
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/getting-started/src/docbkx/persistent-objects.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/getting-started/src/docbkx/persistent-objects.xml b/docs/docbook/getting-started/src/docbkx/persistent-objects.xml
deleted file mode 100644
index 08396e3..0000000
--- a/docs/docbook/getting-started/src/docbkx/persistent-objects.xml
+++ /dev/null
@@ -1,145 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<?xml-model href="http://www.oasis-open.org/docbook/xml/5.0/rng/docbook.rng" schematypens="http://relaxng.org/ns/structure/1.0"?>
-<!--
- 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.
--->
-<section xmlns="http://docbook.org/ns/docbook"
- xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0">
- <title>Getting started with persistent objects</title>
- <para>In this chapter we'll learn about persistent objects, how to customize them and how to
- create and save them in DB.</para>
- <section xml:id="customizing-persistent-objects">
- <title>Inspecting and Customizing Persistent Objects</title>
- <para>Persistent classes in Cayenne implement a DataObject interface. If you inspect any of
- the classes generated earlier in this tutorial (e.g.
- <code>org.example.cayenne.persistent.Artist</code>), you'll see that it extends a class with the name
- that starts with underscore (<code>org.example.cayenne.persistent.auto._Artist</code>), which in turn
- extends from <code>org.apache.cayenne.CayenneDataObject</code>. Splitting each persistent class into
- user-customizable subclass (<code>Xyz</code>) and a generated superclass (<code>_Xyz</code>) is a useful technique
- to avoid overwriting the custom code when refreshing classes from the mapping
- model.</para>
- <para>Let's for instance add a utility method to the Artist class that sets Artist date of
- birth, taking a string argument for the date. It will be preserved even if the model
- changes later:</para>
- <programlisting language="java">package org.example.cayenne.persistent;
-
-import java.time.LocalDate;
-import java.time.format.DateTimeFormatter;
-import java.time.format.DateTimeParseException;
-
-import org.example.cayenne.persistent.auto._Artist;
-
-public class Artist extends _Artist {
-
- static final String DEFAULT_DATE_FORMAT = "yyyyMMdd";
-
- /**
- * Sets date of birth using a string in format yyyyMMdd.
- */
- public void setDateOfBirthString(String yearMonthDay) {
- if (yearMonthDay == null) {
- setDateOfBirth(null);
- } else {
-
- LocalDate date;
- try {
- DateTimeFormatter formatter = DateTimeFormatter.ofPattern(DEFAULT_DATE_FORMAT);
- date = LocalDate.parse(yearMonthDay, formatter);
- } catch (DateTimeParseException e) {
- throw new IllegalArgumentException(
- "A date argument must be in format '"
- + DEFAULT_DATE_FORMAT + "': " + yearMonthDay);
- }
-
- setDateOfBirth(date);
- }
- }
-}</programlisting>
- </section>
- <section xml:id="create-new-objects">
- <title>Create New Objects</title>
- <para>Now we'll create a bunch of objects and save them to the database. An object is
- created and registered with <code>ObjectContext</code> using "<code>newObject</code>" method. Objects <emphasis
- role="bold">must</emphasis> be registered with <code>DataContext</code> to be persisted and to
- allow setting relationships with other objects. Add this code to the "main" method of
- the Main class:</para>
- <programlisting language="java">Artist picasso = context.newObject(Artist.class);
-picasso.setName("Pablo Picasso");
-picasso.setDateOfBirthString("18811025");</programlisting>
- <para>Note that at this point "picasso" object is only stored in memory and is not saved in
- the database. Let's continue by adding a Metropolitan Museum "<code>Gallery</code>" object and a few
- Picasso "Paintings":</para>
- <programlisting language="java">Gallery metropolitan = context.newObject(Gallery.class);
-metropolitan.setName("Metropolitan Museum of Art");
-
-Painting girl = context.newObject(Painting.class);
-girl.setName("Girl Reading at a Table");
-
-Painting stein = context.newObject(Painting.class);
-stein.setName("Gertrude Stein");</programlisting>
- <para>Now we can link the objects together, establishing relationships. Note that in each
- case below relationships are automatically established in both directions (e.g.
- <code>picasso.addToPaintings(girl)</code> has exactly the same effect as
- <code>girl.setToArtist(picasso)</code>).</para>
- <programlisting language="java">picasso.addToPaintings(girl);
-picasso.addToPaintings(stein);
-
-girl.setGallery(metropolitan);
-stein.setGallery(metropolitan);</programlisting>
- <para>Now lets save all five new objects, in a single method call:</para>
- <programlisting language="java">context.commitChanges();</programlisting>
- <para>Now you can run the application again as described in the previous chapter. The new
- output will show a few actual DB operations:</para>
- <screen>org.apache.cayenne.configuration.XMLDataChannelDescriptorLoader load
-INFO: Loading XML configuration resource from file:cayenne-project.xml
-...
-INFO: Connecting to 'jdbc:derby:memory:testdb;create=true' as 'null'
-INFO: +++ Connecting: SUCCESS.
-INFO: setting DataNode 'datanode' as default, used by all unlinked DataMaps
-INFO: Detected and installed adapter: org.apache.cayenne.dba.derby.DerbyAdapter
-INFO: --- transaction started.
-INFO: No schema detected, will create mapped tables
-INFO: CREATE TABLE GALLERY (ID INTEGER NOT NULL, NAME VARCHAR (200), PRIMARY KEY (ID))
-INFO: CREATE TABLE ARTIST (DATE_OF_BIRTH DATE, ID INTEGER NOT NULL, NAME VARCHAR (200), PRIMARY KEY (ID))
-INFO: CREATE TABLE PAINTING (ARTIST_ID INTEGER, GALLERY_ID INTEGER, ID INTEGER NOT NULL,
- NAME VARCHAR (200), PRIMARY KEY (ID))
-INFO: ALTER TABLE PAINTING ADD FOREIGN KEY (ARTIST_ID) REFERENCES ARTIST (ID)
-INFO: ALTER TABLE PAINTING ADD FOREIGN KEY (GALLERY_ID) REFERENCES GALLERY (ID)
-INFO: CREATE TABLE AUTO_PK_SUPPORT (
- TABLE_NAME CHAR(100) NOT NULL, NEXT_ID BIGINT NOT NULL, PRIMARY KEY(TABLE_NAME))
-INFO: DELETE FROM AUTO_PK_SUPPORT WHERE TABLE_NAME IN ('ARTIST', 'GALLERY', 'PAINTING')
-INFO: INSERT INTO AUTO_PK_SUPPORT (TABLE_NAME, NEXT_ID) VALUES ('ARTIST', 200)
-INFO: INSERT INTO AUTO_PK_SUPPORT (TABLE_NAME, NEXT_ID) VALUES ('GALLERY', 200)
-INFO: INSERT INTO AUTO_PK_SUPPORT (TABLE_NAME, NEXT_ID) VALUES ('PAINTING', 200)
-INFO: SELECT NEXT_ID FROM AUTO_PK_SUPPORT WHERE TABLE_NAME = ? FOR UPDATE [bind: 1:'ARTIST']
-INFO: SELECT NEXT_ID FROM AUTO_PK_SUPPORT WHERE TABLE_NAME = ? FOR UPDATE [bind: 1:'GALLERY']
-INFO: SELECT NEXT_ID FROM AUTO_PK_SUPPORT WHERE TABLE_NAME = ? FOR UPDATE [bind: 1:'PAINTING']
-INFO: INSERT INTO GALLERY (ID, NAME) VALUES (?, ?)
-INFO: [batch bind: 1->ID:200, 2->NAME:'Metropolitan Museum of Art']
-INFO: === updated 1 row.
-INFO: INSERT INTO ARTIST (DATE_OF_BIRTH, ID, NAME) VALUES (?, ?, ?)
-INFO: [batch bind: 1->DATE_OF_BIRTH:'1881-10-25 00:00:00.0', 2->ID:200, 3->NAME:'Pablo Picasso']
-INFO: === updated 1 row.
-INFO: INSERT INTO PAINTING (ARTIST_ID, GALLERY_ID, ID, NAME) VALUES (?, ?, ?, ?)
-INFO: [batch bind: 1->ARTIST_ID:200, 2->GALLERY_ID:200, 3->ID:200, 4->NAME:'Gertrude Stein']
-INFO: [batch bind: 1->ARTIST_ID:200, 2->GALLERY_ID:200, 3->ID:201, 4->NAME:'Girl Reading at a Table']
-INFO: === updated 2 rows.
-INFO: +++ transaction committed.
-</screen>
- <para>So first Cayenne creates the needed tables (remember, we used
- "<code>CreateIfNoSchemaStrategy</code>"). Then it runs a number of inserts, generating primary keys
- on the fly. Not bad for just a few lines of code.</para>
- </section>
-</section>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/getting-started/src/docbkx/select-query.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/getting-started/src/docbkx/select-query.xml b/docs/docbook/getting-started/src/docbkx/select-query.xml
deleted file mode 100644
index 72ee254..0000000
--- a/docs/docbook/getting-started/src/docbkx/select-query.xml
+++ /dev/null
@@ -1,60 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<?xml-model href="http://www.oasis-open.org/docbook/xml/5.0/rng/docbook.rng" schematypens="http://relaxng.org/ns/structure/1.0"?>
-<!--
- 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.
--->
-<section xmlns="http://docbook.org/ns/docbook"
- xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0">
- <title>Selecting Objects</title>
- <para>This chapter shows how to select objects from the database using <code>ObjectSelect</code> query. </para>
- <section xml:id="introducing-select-query">
- <title>Introducing ObjectSelect</title>
- <para>It was shown before how to persist new objects. Cayenne queries are used to access
- already saved objects. The primary query type used for selecting objects is <code>ObjectSelect</code>.
- It can be mapped in CayenneModeler or created
- via the API. We'll use the latter approach in this section. We don't have too much data
- in the database yet, but we can still demonstrate the main principles below.</para>
- <itemizedlist>
- <listitem>
- <para>Select all paintings (the code, and the log output it generates):</para>
- </listitem>
- </itemizedlist>
- <programlisting language="java">List<Painting> paintings1 = ObjectSelect.query(Painting.class).select(context); </programlisting>
- <screen>INFO: SELECT t0.GALLERY_ID, t0.ARTIST_ID, t0.NAME, t0.ID FROM PAINTING t0
-INFO: === returned 2 rows. - took 18 ms.</screen>
- <itemizedlist>
- <listitem>
- <para>Select paintings that start with "<code>gi</code>", ignoring case:</para>
- </listitem>
- </itemizedlist>
- <programlisting language="java">List<Painting> paintings2 = ObjectSelect.query(Painting.class)
- .where(Painting.NAME.likeIgnoreCase("gi%")).select(context); </programlisting>
- <screen>INFO: SELECT t0.GALLERY_ID, t0.NAME, t0.ARTIST_ID, t0.ID FROM PAINTING t0 WHERE UPPER(t0.NAME) LIKE UPPER(?)
- [bind: 1->NAME:'gi%'] - prepared in 6 ms.
-INFO: === returned 1 row. - took 18 ms.</screen>
- <itemizedlist>
- <listitem>
- <para>Select all paintings done by artists who were born more than a 100 years
- ago:</para>
- </listitem>
- </itemizedlist>
- <programlisting language="java">List<Painting> paintings3 = ObjectSelect.query(Painting.class)
- .where(Painting.ARTIST.dot(Artist.DATE_OF_BIRTH).lt(LocalDate.of(1900,1,1)))
- .select(context); </programlisting>
- <screen>INFO: SELECT t0.GALLERY_ID, t0.NAME, t0.ARTIST_ID, t0.ID FROM PAINTING t0 JOIN ARTIST t1 ON (t0.ARTIST_ID = t1.ID)
- WHERE t1.DATE_OF_BIRTH < ? [bind: 1->DATE_OF_BIRTH:'1911-01-01 00:00:00.493'] - prepared in 7 ms.
-INFO: === returned 2 rows. - took 25 ms.</screen>
- </section>
-</section>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/getting-started/src/docbkx/setup.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/getting-started/src/docbkx/setup.xml b/docs/docbook/getting-started/src/docbkx/setup.xml
deleted file mode 100644
index f3f9774..0000000
--- a/docs/docbook/getting-started/src/docbkx/setup.xml
+++ /dev/null
@@ -1,36 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<?xml-model href="http://www.oasis-open.org/docbook/xml/5.0/rng/docbook.rng" schematypens="http://relaxng.org/ns/structure/1.0"?>
-<!--
- 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.
--->
-<section xmlns="http://docbook.org/ns/docbook"
- xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0">
- <title>Setup</title>
- <para> The goal of this chapter of the tutorial is to install (or check that you already have
- installed) a minimally needed set of software to build a Cayenne application. </para>
- <section xml:id="install-java">
- <title>Install Java</title>
- <para>
- Obviously, JDK has to be installed. Cayenne 4.0 requires JDK 1.7 or newer.
- </para>
- </section>
- <section xml:id="install-idea">
- <title>Install IntelliJ IDEA</title>
- <para>
- Download and install IntelliJ IDEA Community Edition.
- This tutorial is based on version 2016.3, still it should work with any recent IntelliJ IDEA version.
- </para>
- </section>
-</section>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/getting-started/src/docbkx/starting-project.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/getting-started/src/docbkx/starting-project.xml b/docs/docbook/getting-started/src/docbkx/starting-project.xml
deleted file mode 100644
index c883d5a..0000000
--- a/docs/docbook/getting-started/src/docbkx/starting-project.xml
+++ /dev/null
@@ -1,165 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<?xml-model href="http://www.oasis-open.org/docbook/xml/5.0/rng/docbook.rng" schematypens="http://relaxng.org/ns/structure/1.0"?>
-<!--
- 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.
--->
-<section xmlns="http://docbook.org/ns/docbook"
- xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0">
- <title>Starting a project</title>
- <para>
- The goal of this chapter is to create a new Java project in IntelliJ IDEA
- containing a basic Cayenne mapping. It presents an introduction to
- CayenneModeler GUI tool, showing how to create the initial mapping
- objects: <code>DataDomain</code>, <code>DataNode</code>, <code>DataMap</code>.
- </para>
- <section xml:id="create-new-project">
- <title>Create a new Project in IntelliJ IDEA</title>
- <para>
- In IntelliJ IDEA select "<guimenu>File</guimenu> > <guimenuitem>New</guimenuitem> > <guimenuitem>Project...</guimenuitem>" and then
- select "Maven" and click "Next".
- In the dialog shown on the screenshot below, fill the "Group Id"
- and "Artifact Id" fields and click "Next".
- </para>
- <para>
- <inlinemediaobject>
- <imageobject>
- <imagedata fileref="images/tutorial-idea-project.png" scalefit="1" width="100%"/>
- </imageobject>
- </inlinemediaobject>
- </para>
- <para>
- On next dialog screen you can customize directory for your project and click "Finish".
- Now you should have a new empty project.
- </para>
- </section>
- <section xml:id="download-and-start-cayenne-modeler">
- <title>Download and Start CayenneModeler</title>
- <para>
- Although later in this tutorial we'll be using Maven to include Cayenne
- runtime jars in the project, you'll still need to download Cayenne to
- get access to the CayenneModeler tool.
- </para>
- <para>
- <note>
- <para>If you are really into Maven, you can start
- CayenneModeler from Maven too. We'll do it in a more traditional way
- here.</para>
- </note>
- </para>
- <para>Download the <link xlink:href="http://cayenne.apache.org/download.html">latest release</link>. Unpack the distribution somewhere in the file system and
- start CayenneModeler, following platform-specific instructions. On most platforms it is
- done simply by doubleclicking the Modeler icon. The welcome screen of the Modeler looks
- like this:
- </para>
- <para>
- <inlinemediaobject>
- <imageobject>
- <imagedata fileref="images/modeler-started.png" scalefit="1" width="100%"/>
- </imageobject>
- </inlinemediaobject>
- </para>
- </section>
- <section xml:id="create-new-mapping-project">
- <title>Create a New Mapping Project in CayenneModeler</title>
- <para>Click on the "New Project" button on Welcome screen. A new mapping project will appear
- that contains a single <emphasis role="bold">DataDomain</emphasis>. The meaning of a
- DataDomain is explained elsewhere in the User Guide. For now it is sufficient to
- understand that DataDomain is the root of your mapping project.
- </para>
- </section>
- <section xml:id="create-datanode">
- <title>Create a DataNode</title>
- <para>The next project object you will create is a <emphasis role="bold"
- >DataNode</emphasis>. DataNode is a descriptor of a single database your application
- will connect to. Cayenne mapping project can use more than one database, but for now,
- we'll only use one. With "project" selected on the left, click on "Create DataNode"
- button <inlinemediaobject>
- <imageobject>
- <imagedata fileref="images/icon-node.png"/>
- </imageobject>
- </inlinemediaobject> on the toolbar (or select "Project > Create DataNode" from the menu).
- </para>
- <para>A new DataNode is displayed. Now you need to specify JDBC connection parameters. For
- an in-memory Derby database you can enter the following settings: <itemizedlist>
- <listitem>
- <para>JDBC Driver: org.apache.derby.jdbc.EmbeddedDriver</para>
- </listitem>
- <listitem>
- <para>DB URL: jdbc:derby:memory:testdb;create=true</para>
- </listitem>
- </itemizedlist></para>
- <para>
- <note><para>We are creating an in-memory database here. So when
- you stop your application, all the data will be lost. In most real-life
- cases you'll be connecting to a database that actually persists its data on
- disk, but an in-memory DB will do for the simple tutorial.</para>
- </note>
- </para>
- <para>Also you will need to change "Schema Update Strategy". Select
- "<code>org.apache.cayenne.access.dbsync.CreateIfNoSchemaStrategy</code>" from the dropdown, so that
- Cayenne creates a new schema on Derby based on the ORM mapping when the application
- starts.</para>
- <para>
- <inlinemediaobject>
- <imageobject>
- <imagedata fileref="images/base-datanode.png" scalefit="1" width="100%"/>
- </imageobject>
- </inlinemediaobject>
- </para>
- </section>
- <section xml:id="create-datamap">
- <title>Create a DataMap</title>
- <para>Now you will create a <emphasis role="bold">DataMap</emphasis>. DataMap is an object
- that holds all the mapping information. To create it, click on "Create DataMap" button
- <inlinemediaobject>
- <imageobject>
- <imagedata fileref="images/icon-datamap.png"/>
- </imageobject>
- </inlinemediaobject>
- (or select a corresponding menu item). Note that the newly created DataMap is
- automatically linked to the DataNode that you created in the previous step. If there is
- more than one DataNode, you may need to link a DataMap to the correct node manually. In
- other words a DataMap within DataDomain must point to a database described by the
- map.
- </para>
- <para>You can leave all the DataMap defaults unchanged except for one - "Java Package".
- Enter "<code>org.example.cayenne.persistent</code>". This name will later be used for all persistent
- classes.
- </para>
- <para>
- <inlinemediaobject>
- <imageobject>
- <imagedata fileref="images/base-datamap.png" scalefit="1" width="100%"/>
- </imageobject>
- </inlinemediaobject>
- </para>
- </section>
- <section xml:id="save-project">
- <title>Save the Project</title>
- <para>Before you proceed with the actual mapping, let's save the project. Click on "Save"
- button in the toolbar and navigate to the "<code>tutorial</code>" IDEA project folder that was
- created earlier in this section and its "<code>src/main/resources</code>" subfolder and save the
- project there. Now go back to IDEA and you will see two Cayenne XML files.</para>
- <para><inlinemediaobject>
- <imageobject>
- <imagedata fileref="images/idea-xmlfiles.png"/>
- </imageobject>
- </inlinemediaobject></para>
- <para>Note that the location of the XML files is not coincidental. Cayenne runtime looks for
- "<code>cayenne-*.xml</code>" file in the application <code>CLASSPATH</code> and "<code>src/main/resources</code>" folder should
- already be a "class folder" in IDEA for our project (and is also a standard location
- that Maven would copy to a jar file, if we were using Maven from command-line).</para>
- </section>
-</section>
[03/13] cayenne git commit: CAY-2371 Switch documentation from
Docbook to Asciidoctor format
Posted by nt...@apache.org.
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/cayenne-guide/src/docbkx/starting-cayenne.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/cayenne-guide/src/docbkx/starting-cayenne.xml b/docs/docbook/cayenne-guide/src/docbkx/starting-cayenne.xml
deleted file mode 100644
index c8dfdb7..0000000
--- a/docs/docbook/cayenne-guide/src/docbkx/starting-cayenne.xml
+++ /dev/null
@@ -1,157 +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.
--->
-<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
- version="5.0" xml:id="starting-cayenne">
- <title>Starting Cayenne</title>
- <section xml:id="starting-serverruntime">
- <title>Starting and Stopping ServerRuntime</title>
- <para>In runtime Cayenne is accessed via
- <code>org.apache.cayenne.configuration.server.ServerRuntime</code>. ServerRuntime is
- created by calling a convenient builder:
- <programlisting language="java">ServerRuntime runtime = ServerRuntime.builder()
- .addConfig("com/example/cayenne-project.xml")
- .build();</programlisting></para>
- <para>The parameter you pass to the builder is a location of the main project file. Location
- is a '/'-separated path (same path separator is used on UNIX and Windows) that is
- resolved relative to the application classpath. The project file can be placed in the
- root package or in a subpackage (e.g. in the code above it is in "com/example"
- subpackage).</para>
- <para>ServerRuntime encapsulates a single Cayenne stack. Most applications will just have
- one ServerRuntime using it to create as many ObjectContexts as needed, access the
- Dependency Injection (DI) container and work with other Cayenne features. Internally
- ServerRuntime is just a thin wrapper around the DI container. Detailed features of the
- container are discussed in <link linkend="customizing-cayenne-runtime">"Customizing Cayenne Runtime"</link> chapter. Here we'll just show
- an example of how an application might turn on external transactions:<programlisting language="java">Module extensions = binder ->
- ServerModule.contributeProperties(binder).put(Constants.SERVER_EXTERNAL_TX_PROPERTY, "true");
-ServerRuntime runtime = ServerRuntime.builder()
- .addConfig("com/example/cayenne-project.xml")
- .addModule(extensions)
- .build();</programlisting></para>
- <para>It is a good idea to shut down the runtime when it is no longer needed, usually before the
- application itself is shutdown: <programlisting language="java">runtime.shutdown();</programlisting>When
- a runtime object has the same scope as the application, this may not be always
- necessary, however in some cases it is essential, and is generally considered a good
- practice. E.g. in a web container hot redeploy of a webapp will cause resource leaks and
- eventual OutOfMemoryError if the application fails to shutdown CayenneRuntime.</para>
- </section>
- <section>
- <title>Merging Multiple Projects</title>
- <para>ServerRuntime requires at least one mapping project to run. But it can also take multiple
- projects and merge them together in a single configuration. This way different parts of
- a database can be mapped independently from each other (even by different software
- providers), and combined in runtime when assembling an application. Doing it is as easy
- as passing multiple project locations to ServerRuntime builder:</para><programlisting language="java">ServerRuntime runtime = ServerRuntime.builder()
- .addConfig("com/example/cayenne-project.xml")
- .addConfig("org/foo/cayenne-library1.xml")
- .addConfig("org/foo/cayenne-library2.xml")
- .build();</programlisting>
- <para>When the projects are merged, the following rules are applied:<itemizedlist>
- <listitem>
- <para>The order of projects matters during merge. If there are two conflicting
- metadata objects belonging to two projects, an object from the <emphasis
- role="italic">last</emphasis> project takes precedence over the object
- from the first one. This makes possible to override pieces of metadata. This
- is also similar to how DI modules are merged in Cayenne.</para>
- </listitem>
- <listitem>
- <para>Runtime DataDomain name is set to the name of the last project in the
- list.</para>
- </listitem>
- <listitem>
- <para>Runtime DataDomain properties are the same as the properties of the last
- project in the list. I.e. <emphasis role="italic">properties are not
- merged</emphasis> to avoid invalid combinations and unexpected runtime
- behavior.</para>
- </listitem>
- <listitem>
- <para>If there are two or more DataMaps with the same name, only one DataMap is
- used in the merged project, the rest are discarded. Same precedence rules
- apply - DataMap from the project with the highest index in the project list
- overrides all other DataMaps with the same name.</para>
- </listitem>
- <listitem>
- <para>If there are two or more DataNodes with the same name, only one DataNodes
- is used in the merged project, the rest are discarded. DataNode coming from
- project with the highest index in the project list is chosen per precedence
- rule above.</para>
- </listitem>
- <listitem>
- <para>There is a notion of "default" DataNode. After the merge if any DataMaps
- are not explicitly linked to DataNodes, their queries will be executed via a
- default DataNode. This makes it possible to build mapping "libraries" that
- are only associated with a specific database in runtime. If there's only one
- DataNode in the merged project, it will be automatically chosen as default.
- A possible way to explicitly designate a specific node as default is to
- override <code>DataDomainProvider.createAndInitDataDomain()</code>.</para>
- </listitem>
- </itemizedlist></para>
- </section>
- <section xml:id="webapps">
- <title>Web Applications</title>
- <para>Web applications can use a variety of mechanisms to configure and start the "services"
- they need, Cayenne being one of such services. Configuration can be done within standard
- Servlet specification objects like Servlets, Filters, or ServletContextListeners, or can
- use Spring, JEE CDI, etc. This is a user's architectural choice and Cayenne is agnostic
- to it and will happily work in any environment. As described above, all that is needed
- is to create an instance of ServerRuntime somewhere and provide the application code
- with means to access it. And shut it down when the application ends to avoid container
- leaks.</para>
- <para>Still Cayenne includes a piece of web app configuration code that can assist in
- quickly setting up simple Cayenne-enabled web applications. We are talking about
- CayenneFilter. It is declared in
- web.xml:<programlisting language="xml"><web-app>
- ...
- <filter>
- <filter-name>cayenne-project</filter-name>
- <filter-class>org.apache.cayenne.configuration.web.CayenneFilter</filter-class>
- </filter>
- <filter-mapping>
- <filter-name>cayenne-project</filter-name>
- <url-pattern>/*</url-pattern>
- </filter-mapping>
- ...
- </web-app> </programlisting></para>
- <para>When started by the web container, it creates a instance of ServerRuntime and stores
- it in the ServletContext. Note that the name of Cayenne XML project file is derived from
- the "filter-name". In the example above CayenneFilter will look for an XML file
- "cayenne-project.xml". This can be overridden with "configuration-location" init
- parameter.</para>
- <para>When the application runs, all HTTP requests matching the filter url-pattern will have
- access to a session-scoped ObjectContext like
- this:<programlisting language="java">ObjectContext context = BaseContext.getThreadObjectContext();</programlisting>Of
- course the ObjectContext scope, and other behavior of the Cayenne runtime can be
- customized via dependency injection. For this another filter init parameter called
- "extra-modules" is used. "extra-modules" is a comma or space-separated list of class
- names, with each class implementing Module interface. These optional custom modules are
- loaded after the the standard ones, which allows users to override all standard
- definitions.</para>
- <para>For those interested in the DI container contents of the runtime created by CayenneFilter,
- it is the same ServerRuntime as would've been created by other means, but with an extra
- <code>org.apache.cayenne.configuration.web.WebModule</code> module that provides
- <code>org.apache.cayenne.configuration.web.RequestHandler</code> service. This is
- the service to override in the custom modules if you need to provide a different
- ObjectContext scope, etc.</para>
- <para>
- <note>
- <para>You should not think of CayenneFilter as the only way to start and use Cayenne in a web
- application. In fact CayenneFilter is entirely optional. Use it if you don't
- have any special design for application service management. If you do, simply
- integrate Cayenne into that design.</para>
- </note>
- </para>
- </section>
-</chapter>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/cayenne-guide/src/images/.gitignore
----------------------------------------------------------------------
diff --git a/docs/docbook/cayenne-guide/src/images/.gitignore b/docs/docbook/cayenne-guide/src/images/.gitignore
deleted file mode 100644
index e69de29..0000000
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/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
deleted file mode 100644
index 2d8c32a..0000000
Binary files a/docs/docbook/cayenne-guide/src/images/ext-crypto-obj-entity.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/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
deleted file mode 100644
index f681b9d..0000000
Binary files a/docs/docbook/cayenne-guide/src/images/ext-dbcp-setup.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/cayenne-guide/src/images/re-modeler-datasource-select.png
----------------------------------------------------------------------
diff --git a/docs/docbook/cayenne-guide/src/images/re-modeler-datasource-select.png b/docs/docbook/cayenne-guide/src/images/re-modeler-datasource-select.png
deleted file mode 100644
index 79ada1c..0000000
Binary files a/docs/docbook/cayenne-guide/src/images/re-modeler-datasource-select.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/cayenne-guide/src/images/re-modeler-reverseengineering-dialog.png
----------------------------------------------------------------------
diff --git a/docs/docbook/cayenne-guide/src/images/re-modeler-reverseengineering-dialog.png b/docs/docbook/cayenne-guide/src/images/re-modeler-reverseengineering-dialog.png
deleted file mode 100644
index 8b09d07..0000000
Binary files a/docs/docbook/cayenne-guide/src/images/re-modeler-reverseengineering-dialog.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/cayenne-guide/src/images/remote-object-persistence.jpg
----------------------------------------------------------------------
diff --git a/docs/docbook/cayenne-guide/src/images/remote-object-persistence.jpg b/docs/docbook/cayenne-guide/src/images/remote-object-persistence.jpg
deleted file mode 100644
index 43f820d..0000000
Binary files a/docs/docbook/cayenne-guide/src/images/remote-object-persistence.jpg and /dev/null differ
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/docbook-stylesheets/pom.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/docbook-stylesheets/pom.xml b/docs/docbook/docbook-stylesheets/pom.xml
deleted file mode 100644
index 88b8795..0000000
--- a/docs/docbook/docbook-stylesheets/pom.xml
+++ /dev/null
@@ -1,45 +0,0 @@
-<?xml version="1.0"?>
-<!--
- 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.
--->
-<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
- <modelVersion>4.0.0</modelVersion>
-
- <parent>
- <groupId>org.apache.cayenne.docs</groupId>
- <artifactId>cayenne-docbook</artifactId>
- <version>4.0.B3-SNAPSHOT</version>
- </parent>
-
- <artifactId>docbook-stylesheets</artifactId>
- <name>docbook-stylesheets: Docbook - Cayenne Stylesheets</name>
-
- <properties>
- <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
- </properties>
-
- <build>
- <resources>
- <resource>
- <directory>src/main/resources</directory>
- <filtering>true</filtering>
- </resource>
- </resources>
- </build>
-
-</project>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/docbook-stylesheets/src/main/resources/css/cayenne-doc.css
----------------------------------------------------------------------
diff --git a/docs/docbook/docbook-stylesheets/src/main/resources/css/cayenne-doc.css b/docs/docbook/docbook-stylesheets/src/main/resources/css/cayenne-doc.css
deleted file mode 100644
index c6e8ad2..0000000
--- a/docs/docbook/docbook-stylesheets/src/main/resources/css/cayenne-doc.css
+++ /dev/null
@@ -1,148 +0,0 @@
-@IMPORT url("highlight.css");
-
-html {
- padding: 0pt;
- margin: 0pt;
-}
-
-body, td {
- margin-left: 10%;
- margin-right: 10%;
- font-family: "Lucida Grande","Trebuchet MS",Verdana,sans-serif;
- font-size: small;
-}
-
-div {
- margin: 0pt;
-}
-
-p {
- text-align: justify;
-}
-
-hr {
- border: 1px solid gray;
- background: gray;
-}
-
-h1, h2, h3, h4 {
- font-family: "Trebuchet MS","Lucida Grande",Verdana,sans-serif;
- font-weight: normal;
- line-height: normal;
- margin: 1em 0 0.5em;
-}
-
-h2 {
- color: #660000;
- font-size: 170%;
- padding: 0;
-}
-
-h3 {
- border-bottom: 1px solid #EAEAEA;
- color: #CC4400;
- font-size: 135%;
- padding-bottom: 3px;
-}
-
-h4 {
- color: #AAAA99;
- font-size: 130%;
-}
-
-pre {
- line-height: 1.0;
- color: black;
-
- -moz-tab-size: 4;
- -o-tab-size: 4;
- tab-size: 4;
-}
-
-pre.programlisting {
- font-size: 10pt;
- padding: 7pt 3pt;
- border: 1pt solid black;
- background: #F9F9F6;
- clear: both;
-}
-
-pre.screen {
- font-family: Courier New,monospace;
- font-size: 10pt;
- padding: 7pt 3pt;
- border: 1pt solid black;
- background: #F9F9F6;
-}
-
-div.table {
- margin: 1em;
- padding: 0.5em;
- text-align: center;
-}
-
-table[frame=void] {
- display: table;
- width: 100%;
- border: 1px black solid;
- border-collapse: collapse;
- border-spacing: 0;
-}
-
-table[frame=void] td {
- padding-left: 7px;
- padding-right: 7px;
- border: 1px black solid;
-}
-
-table[frame=void] th {
- padding-left: 7px;
- padding-right: 7px;
- border: 1px black solid;
-}
-
-.sidebar {
- float: right;
- margin: 10px 0 10px 30px;
- padding: 10px 20px 20px 20px;
- width: 33%;
- border: 1px solid black;
- background-color: #F4F4F4;
- font-size: 14px;
-}
-
-.code {
- font-family: Courier New,monospace;
-}
-
-.mediaobject {
- padding-top: 30px;
- padding-bottom: 30px;
-}
-
-.legalnotice {
- font-size: 12px;
- font-style: italic;
-}
-
-p.releaseinfo {
- font-size: 100%;
- font-weight: bold;
- padding-top: 10px;
-}
-
-p.pubdate {
- font-size: 120%;
- font-weight: bold;
-}
-
-span.productname {
- font-size: 200%;
- font-weight: bold;
-}
-
-th.versioninfo {
- font-size: 10px;
- font-weight: normal;
- text-align: left;
-}
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/docbook-stylesheets/src/main/resources/css/highlight.css
----------------------------------------------------------------------
diff --git a/docs/docbook/docbook-stylesheets/src/main/resources/css/highlight.css b/docs/docbook/docbook-stylesheets/src/main/resources/css/highlight.css
deleted file mode 100644
index f6a057d..0000000
--- a/docs/docbook/docbook-stylesheets/src/main/resources/css/highlight.css
+++ /dev/null
@@ -1,35 +0,0 @@
-/*
- code highlight CSS resemblign the Eclipse IDE default color schema
- @author Costin Leau
-*/
-
-.hl-keyword {
- color: #7F0055;
- font-weight: bold;
-}
-
-.hl-comment {
- color: #3F5F5F;
- font-style: italic;
-}
-
-.hl-multiline-comment {
- color: #3F5FBF;
- font-style: italic;
-}
-
-.hl-tag {
- color: #3F7F7F;
-}
-
-.hl-attribute {
- color: #7F007F;
-}
-
-.hl-value {
- color: #2A00FF;
-}
-
-.hl-string {
- color: #2A00FF !important;
-}
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/docbook-stylesheets/src/main/resources/stylesheets/common-customizations.xsl
----------------------------------------------------------------------
diff --git a/docs/docbook/docbook-stylesheets/src/main/resources/stylesheets/common-customizations.xsl b/docs/docbook/docbook-stylesheets/src/main/resources/stylesheets/common-customizations.xsl
deleted file mode 100644
index d51510d..0000000
--- a/docs/docbook/docbook-stylesheets/src/main/resources/stylesheets/common-customizations.xsl
+++ /dev/null
@@ -1,32 +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.
--->
-<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
-
- <!-- The next line is needed to work with maven injecting the docbook stylesheets -->
- <!---->
- <!-- <xsl:import href="urn:docbkx:stylesheet/highlight.xsl"/> -->
-
- <xsl:param name="keep.relative.image.uris" select="1"/>
- <xsl:param name="toc.section.depth">1</xsl:param>
-
- <!-- disable TOC for each part -->
- <xsl:template name="generate.part.toc" />
-
-</xsl:stylesheet>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/docbook-stylesheets/src/main/resources/stylesheets/highlight.xsl
----------------------------------------------------------------------
diff --git a/docs/docbook/docbook-stylesheets/src/main/resources/stylesheets/highlight.xsl b/docs/docbook/docbook-stylesheets/src/main/resources/stylesheets/highlight.xsl
deleted file mode 100644
index e25baf0..0000000
--- a/docs/docbook/docbook-stylesheets/src/main/resources/stylesheets/highlight.xsl
+++ /dev/null
@@ -1,104 +0,0 @@
-<?xml version="1.0" encoding="ASCII"?>
-<!--
- 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.
--->
-<!--This file was created automatically by html2xhtml-->
-<!--from the HTML stylesheets.-->
-<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:d="http://docbook.org/ns/docbook"
- xmlns:xslthl="http://xslthl.sf.net" xmlns="http://www.w3.org/1999/xhtml" exclude-result-prefixes="xslthl d" version="1.0">
-
- <xsl:import href="urn:docbkx:stylesheet/highlight.xsl"/>
- <!-- ********************************************************************
- $Id: highlight.xsl 8911 2010-09-28 17:02:06Z abdelazer $
- ********************************************************************
-
- This file is part of the XSL DocBook Stylesheet distribution.
- See ../README or http://docbook.sf.net/release/xsl/current/ for
- and other information.
-
-
-
- ******************************************************************** -->
- <!-- <xsl:import href="urn:/highlighting/common.xsl"/> -->
- <xsl:template match="xslthl:keyword" mode="xslthl">
- <span class="hl-keyword">
- <xsl:apply-templates mode="xslthl"/>
- </span>
- </xsl:template>
- <xsl:template match="xslthl:string" mode="xslthl">
- <span class="hl-string">
- <xsl:apply-templates mode="xslthl"/>
- </span>
- </xsl:template>
- <xsl:template match="xslthl:comment" mode="xslthl">
- <span class="hl-comment">
- <xsl:apply-templates mode="xslthl"/>
- </span>
- </xsl:template>
- <xsl:template match="xslthl:directive" mode="xslthl">
- <span class="hl-directive">
- <xsl:apply-templates mode="xslthl"/>
- </span>
- </xsl:template>
- <xsl:template match="xslthl:tag" mode="xslthl">
- <span class="hl-tag">
- <xsl:apply-templates mode="xslthl"/>
- </span>
- </xsl:template>
- <xsl:template match="xslthl:attribute" mode="xslthl">
- <span class="hl-attribute">
- <xsl:apply-templates mode="xslthl"/>
- </span>
- </xsl:template>
- <xsl:template match="xslthl:value" mode="xslthl">
- <span class="hl-value">
- <xsl:apply-templates mode="xslthl"/>
- </span>
- </xsl:template>
- <xsl:template match="xslthl:html" mode="xslthl">
- <strong>
- <span>
- <xsl:apply-templates mode="xslthl"/>
- </span>
- </strong>
- </xsl:template>
- <xsl:template match="xslthl:xslt" mode="xslthl">
- <span>
- <xsl:apply-templates mode="xslthl"/>
- </span>
- </xsl:template>
- <!-- Not emitted since XSLTHL 2.0 -->
- <xsl:template match="xslthl:section" mode="xslthl">
- <span>
- <xsl:apply-templates mode="xslthl"/>
- </span>
- </xsl:template>
- <xsl:template match="xslthl:number" mode="xslthl">
- <span class="hl-number">
- <xsl:apply-templates mode="xslthl"/>
- </span>
- </xsl:template>
- <xsl:template match="xslthl:annotation" mode="xslthl">
- <span class="hl-annotation">
- <xsl:apply-templates mode="xslthl"/>
- </span>
- </xsl:template>
- <!-- Not sure which element will be in final XSLTHL 2.0 -->
- <xsl:template match="xslthl:doccomment|xslthl:doctype" mode="xslthl">
- <strong class="hl-tag">
- <xsl:apply-templates mode="xslthl"/>
- </strong>
- </xsl:template>
-</xsl:stylesheet>
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/docbook-stylesheets/src/main/resources/stylesheets/html.xsl
----------------------------------------------------------------------
diff --git a/docs/docbook/docbook-stylesheets/src/main/resources/stylesheets/html.xsl b/docs/docbook/docbook-stylesheets/src/main/resources/stylesheets/html.xsl
deleted file mode 100644
index 11b6d4f..0000000
--- a/docs/docbook/docbook-stylesheets/src/main/resources/stylesheets/html.xsl
+++ /dev/null
@@ -1,244 +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.
--->
-<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
- version="1.0" xmlns:d="http://docbook.org/ns/docbook">
-
-
- <xsl:import href="urn:docbkx:stylesheet"/>
- <xsl:import href="highlight.xsl"/>
- <xsl:include href="common-customizations.xsl"/>
-
- <!--<xsl:param name="highlight.source" select="1"/>-->
- <xsl:param name="html.stylesheet" select="'css/cayenne-doc.css'"/>
- <xsl:param name="chunker.output.encoding">UTF-8</xsl:param>
-
- <!-- Only chapters start a new page -->
- <xsl:param name="chunk.section.depth">0</xsl:param>
-
- <!-- Don't add any embedded styles -->
- <xsl:param name="css.decoration">0</xsl:param>
-
- <xsl:param name="ignore.image.scaling">1</xsl:param>
-
- <xsl:param name="use.id.as.filename">1</xsl:param>
-
- <xsl:param name="navig.showtitles">1</xsl:param>
-
- <!--
- BODY > HEAD Customization
- Customized template for generate meta tags with cayenne version in head of
- page with documentation
- -->
- <xsl:template name="head.content">
- <xsl:param name="node" select="."/>
- <xsl:param name="title">
- <xsl:apply-templates select="$node" mode="object.title.markup.textonly"/>
- </xsl:param>
-
- <title>
- <xsl:copy-of select="$title"/>
- </title>
-
- <xsl:if test="$html.base != ''">
- <base href="{$html.base}"/>
- </xsl:if>
-
- <!-- Insert links to CSS files or insert literal style elements -->
- <xsl:call-template name="generate.css"/>
-
- <xsl:if test="$html.stylesheet != ''">
- <xsl:call-template name="output.html.stylesheets">
- <xsl:with-param name="stylesheets" select="normalize-space($html.stylesheet)"/>
- </xsl:call-template>
- </xsl:if>
-
- <xsl:if test="$link.mailto.url != ''">
- <link rev="made" href="{$link.mailto.url}"/>
- </xsl:if>
-
- <meta name="keywords" content="Cayenne ${cayenne.version.major} documentation"/>
- <meta name="description" content="User documentation for Apache Cayenne version ${cayenne.version.major}"/>
-
- <xsl:if test="$generate.meta.abstract != 0">
- <xsl:variable name="info" select="(d:articleinfo
- |d:bookinfo
- |d:prefaceinfo
- |d:chapterinfo
- |d:appendixinfo
- |d:sectioninfo
- |d:sect1info
- |d:sect2info
- |d:sect3info
- |d:sect4info
- |d:sect5info
- |d:referenceinfo
- |d:refentryinfo
- |d:partinfo
- |d:info
- |d:docinfo)[1]"/>
- <xsl:if test="$info and $info/d:abstract">
- <meta name="description">
- <xsl:attribute name="content">
- <xsl:for-each select="$info/d:abstract[1]/*">
- <xsl:value-of select="normalize-space(.)"/>
- <xsl:if test="position() < last()">
- <xsl:text> </xsl:text>
- </xsl:if>
- </xsl:for-each>
- </xsl:attribute>
- </meta>
- </xsl:if>
- </xsl:if>
-
- <xsl:if test="($draft.mode = 'yes' or
- ($draft.mode = 'maybe' and
- ancestor-or-self::*[@status][1]/@status = 'draft'))
- and $draft.watermark.image != ''">
- <style type="text/css"><xsl:text>
-body { background-image: url('</xsl:text>
- <xsl:value-of select="$draft.watermark.image"/><xsl:text>');
- background-repeat: no-repeat;
- background-position: top left;
- /* The following properties make the watermark "fixed" on the page. */
- /* I think that's just a bit too distracting for the reader... */
- /* background-attachment: fixed; */
- /* background-position: center center; */
- }</xsl:text>
- </style>
- </xsl:if>
- <xsl:apply-templates select="." mode="head.keywords.content"/>
- </xsl:template>
-
- <!-- GoogleAnalytics script for web publishing -->
- <xsl:template name="user.head.content">
- <script type="text/javascript">
- var _gaq = _gaq || [];
- _gaq.push(['_setAccount', 'UA-7036673-1']);
- _gaq.push(['_trackPageview']);
- (function() {
- var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
- ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
- var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
- })();
- </script>
- </xsl:template>
-
- <!--
- TOP NAVIGATION
- -->
- <xsl:template name="header.navigation">
- <xsl:param name="prev" select="/d:foo"/>
- <xsl:param name="next" select="/d:foo"/>
- <xsl:param name="nav.context"/>
-
- <xsl:variable name="home" select="/*[1]"/>
- <xsl:variable name="up" select="parent::*"/>
-
- <xsl:variable name="row1" select="$navig.showtitles != 0"/>
- <xsl:variable name="row2" select="count($prev) > 0
- or (count($up) > 0
- and generate-id($up) != generate-id($home)
- and $navig.showtitles != 0)
- or count($next) > 0"/>
-
- <xsl:if test="$suppress.navigation = '0' and $suppress.header.navigation = '0'">
- <div class="navheader">
- <xsl:if test="$row1 or $row2">
- <table width="100%" summary="Navigation header">
-
- <!-- Add Apache Cayenne version info -->
- <xsl:if test="$row1">
- <tr>
- <th class="versioninfo">v.${cayenne.version.major} (${pom.version})</th>
- <th align="center">
- <xsl:apply-templates select="." mode="object.title.markup"/>
- </th>
- <th></th>
- </tr>
- </xsl:if>
-
- <xsl:if test="$row2">
-
- <tr>
- <td width="20%" align="{$direction.align.start}">
- <xsl:if test="count($prev)>0">
- <a accesskey="p">
- <xsl:attribute name="href">
- <xsl:call-template name="href.target">
- <xsl:with-param name="object" select="$prev"/>
- </xsl:call-template>
- </xsl:attribute>
- <xsl:call-template name="navig.content">
- <xsl:with-param name="direction" select="'prev'"/>
- </xsl:call-template>
- </a>
- </xsl:if>
- <xsl:text> </xsl:text>
- </td>
-
- <!-- Make parent caption as link -->
- <th width="60%" align="center">
- <xsl:choose>
- <xsl:when test="count($up) > 0
- and generate-id($up) != generate-id($home)
- and $navig.showtitles != 0">
- <a accesskey="u">
- <xsl:attribute name="href">
- <xsl:call-template name="href.target">
- <xsl:with-param name="object" select="$up"/>
- </xsl:call-template>
- </xsl:attribute>
- <xsl:apply-templates select="$up" mode="object.title.markup"/>
- </a>
- </xsl:when>
- <xsl:otherwise> </xsl:otherwise>
- </xsl:choose>
- </th>
-
-
- <td width="20%" align="{$direction.align.end}">
- <xsl:text> </xsl:text>
- <xsl:if test="count($next)>0">
- <a accesskey="n">
- <xsl:attribute name="href">
- <xsl:call-template name="href.target">
- <xsl:with-param name="object" select="$next"/>
- </xsl:call-template>
- </xsl:attribute>
- <xsl:call-template name="navig.content">
- <xsl:with-param name="direction" select="'next'"/>
- </xsl:call-template>
- </a>
- </xsl:if>
- </td>
- </tr>
-
- </xsl:if>
-
- </table>
- </xsl:if>
- <xsl:if test="$header.rule != 0">
- <hr/>
- </xsl:if>
- </div>
- </xsl:if>
- </xsl:template>
-
-</xsl:stylesheet>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/docbook-stylesheets/src/main/resources/stylesheets/pdf.xsl
----------------------------------------------------------------------
diff --git a/docs/docbook/docbook-stylesheets/src/main/resources/stylesheets/pdf.xsl b/docs/docbook/docbook-stylesheets/src/main/resources/stylesheets/pdf.xsl
deleted file mode 100644
index f716411..0000000
--- a/docs/docbook/docbook-stylesheets/src/main/resources/stylesheets/pdf.xsl
+++ /dev/null
@@ -1,505 +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.
--->
-<!--
- This is the XSL FO (PDF) stylesheet for the Cayenne documentation.
--->
-<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
- xmlns:fo="http://www.w3.org/1999/XSL/Format"
- version="1.0">
-
- <xsl:import href="urn:docbkx:stylesheet"/>
- <xsl:include href="common-customizations.xsl"/>
-
- <xsl:template name="border">
- <xsl:param name="side" select="'start'"/>
-
- <xsl:attribute name="border-{$side}-width">
- <xsl:value-of select="$table.cell.border.thickness"/>
- </xsl:attribute>
- <xsl:attribute name="border-{$side}-style">
- <xsl:value-of select="$table.cell.border.style"/>
- </xsl:attribute>
- <xsl:attribute name="border-{$side}-color">
- <xsl:value-of select="$table.cell.border.color"/>
- </xsl:attribute>
- <xsl:attribute name="my-attr">
- <xsl:value-of select="'1'"/>
- </xsl:attribute>
- </xsl:template>
-
- <!-- don't indent the body text -->
- <xsl:param name="body.start.indent">0pt</xsl:param>
-
- <!-- print headers and footers mirrored so double sided printing works -->
- <!--<xsl:param name="fop1.extensions" select="1"/>-->
- <xsl:param name="double.sided" select="0"/>
-
- <xsl:param name="admon.graphics" select="0"/>
- <xsl:param name="admon.graphics.extension">.png</xsl:param>
- <xsl:param name="admon.graphics.path">stylesheets/docbook-xsl-ns/images/</xsl:param>
- <xsl:param name="admon.textlabel" select="1"/>
-
- <xsl:param name="callout.graphics" select="1"/>
- <xsl:param name="callout.graphics.extension">.png</xsl:param>
- <xsl:param name="callout.graphics.path">stylesheets/docbook-xsl-ns/images/callouts/</xsl:param>
-
- <xsl:param name="footer.rule">0</xsl:param>
-
- <!-- Separation between glossary terms and descriptions when glossaries are presented using lists. -->
- <xsl:param name="glossterm.separation">2em</xsl:param>
-
- <!-- This parameter specifies the width reserved for glossary terms when a list presentation is used. -->
- <xsl:param name="glossterm.width">10em</xsl:param>
-
- <!-- Specifies the longest term in variablelists. In variablelists, the listitem is indented to leave room for the term elements. The indent may be computed if it is not specified with a termlength attribute on the variablelist element. The computation counts characters in the term elements in the list to find the longest term. However, some terms are very long and would produce extreme indents. This parameter lets you set a maximum character count. Any terms longer than the maximum would line wrap. The default value is 24. The character counts are converted to physical widths by multiplying by 0.50em. There is some variability in how many characters fit in the space since some characters are wider than others. -->
- <xsl:param name="variablelist.max.termlength">18</xsl:param>
-
- <!-- Custom font settings - preferred truetype font -->
- <xsl:param name="title.font.family">Lucinda Grande,sans-serif</xsl:param>
- <xsl:param name="body.font.family">Times,serif</xsl:param>
- <xsl:param name="sans.font.family">Lucinda Grande,sans-serif</xsl:param>
- <xsl:param name="dingbat.font.family">Lucinda Grande,serif</xsl:param>
- <xsl:param name="monospace.font.family">monospace</xsl:param>
-
- <!-- Specify the default text alignment. The default text alignment is used for most body text. -->
- <xsl:param name="alignment">justify</xsl:param>
-
- <!-- Specifies the default point size for body text. The body font size is specified in two parameters (body.font.master and body.font.size) so that math can be performed on the font size by XSLT. -->
- <xsl:param name="body.font.master">11</xsl:param>
-
- <xsl:param name="hyphenate">true</xsl:param>
-
- <!-- "normal" is 1.6. This value is multiplied by the font size -->
- <xsl:param name="line-height">1.5</xsl:param>
-
- <!-- Specify the spacing required between normal paragraphs. -->
- <xsl:attribute-set name="normal.para.spacing">
- <xsl:attribute name="space-before.optimum">0.8em</xsl:attribute>
- <xsl:attribute name="space-before.minimum">0.6em</xsl:attribute>
- <xsl:attribute name="space-before.maximum">1.0em</xsl:attribute>
- </xsl:attribute-set>
-
- <!-- Tables, examples, figures, and equations don't need to be forced onto onto one page without page breaks. -->
- <xsl:attribute-set name="formal.object.properties">
- <xsl:attribute name="keep-together.within-column">auto</xsl:attribute>
- </xsl:attribute-set>
-
- <!-- The body bottom margin is the distance from the last line of text in the page body to the bottom of the region-after. -->
- <xsl:param name="body.margin.bottom">20mm</xsl:param>
-
- <!-- The body top margin is the distance from the top of the region-before to the first line of text in the page body. -->
- <xsl:param name="body.margin.top">20mm</xsl:param>
-
- <!-- The top page margin is the distance from the physical top of the page to the top of the region-before. -->
- <xsl:param name="page.margin.top">10mm</xsl:param>
-
- <!-- The bottom page margin is the distance from the bottom of the region-after to the physical bottom of the page. -->
- <xsl:param name="page.margin.bottom">10mm</xsl:param>
-
- <!-- The inner page margin. The inner page margin is the distance from binding edge of the page to the first column of text. In the left-to-right, top-to-bottom writing direction, this is the left margin of recto pages. The inner and outer margins are usually the same unless the output is double-sided. -->
- <xsl:param name="page.margin.inner">18mm</xsl:param>
-
- <!-- The outer page margin. The outer page margin is the distance from non-binding edge of the page to the last column of text. In the left-to-right, top-to-bottom writing direction, this is the right margin of recto pages. The inner and outer margins are usually the same unless the output is double-sided. -->
- <xsl:param name="page.margin.outer">18mm</xsl:param>
-
- <!-- Make hyperlinks blue and don't display the underlying URL -->
- <xsl:param name="ulink.show" select="0"/>
-
- <xsl:attribute-set name="xref.properties">
- <xsl:attribute name="color">blue</xsl:attribute>
- </xsl:attribute-set>
-
- <xsl:param name="img.src.path">../</xsl:param>
-
- <!-- Prevent blank pages in output -->
- <xsl:template name="book.titlepage.before.verso">
- </xsl:template>
- <xsl:template name="book.titlepage.verso">
- </xsl:template>
- <xsl:template name="book.titlepage.separator">
- </xsl:template>
-
- <!--###################################################
- Header
- ################################################### -->
-
- <!-- More space in the center header for long text -->
- <xsl:attribute-set name="header.content.properties">
- <xsl:attribute name="font-family">
- <xsl:value-of select="$body.font.family"/>
- </xsl:attribute>
- <xsl:attribute name="margin-left">-5em</xsl:attribute>
- <xsl:attribute name="margin-right">-5em</xsl:attribute>
- </xsl:attribute-set>
-
- <!--###################################################
- Custom Footer
- ################################################### -->
- <xsl:template name="footer.content">
- <xsl:param name="pageclass" select="''"/>
- <xsl:param name="sequence" select="''"/>
- <xsl:param name="position" select="''"/>
- <xsl:param name="gentext-key" select="''"/>
- <xsl:variable name="Version">
- <fo:inline min-width="150mm">v.${cayenne.version.major}</fo:inline>
- </xsl:variable>
- <xsl:choose>
- <xsl:when test="$sequence='blank'">
- <xsl:if test="$position = 'left'">
- <xsl:value-of select="$Version"/>
- </xsl:if>
- </xsl:when>
- <!-- for single sided printing, print all page numbers on the right (of the page) -->
- <xsl:when test="$double.sided = 0">
- <xsl:choose>
- <xsl:when test="$position='left'">
- <xsl:value-of select="$Version"/>
- </xsl:when>
- <xsl:when test="$position='right'">
- <fo:page-number/>
- </xsl:when>
- </xsl:choose>
- </xsl:when>
- </xsl:choose>
- </xsl:template>
-
- <!--###################################################
- Extensions
- ################################################### -->
-
- <!-- These extensions are required for table printing and other stuff -->
- <xsl:param name="use.extensions">1</xsl:param>
- <xsl:param name="tablecolumns.extension">1</xsl:param>
- <xsl:param name="callout.extensions">1</xsl:param>
- <!-- FOP provide only PDF Bookmarks at the moment -->
- <xsl:param name="fop1.extensions">1</xsl:param>
-
- <!-- ###################################################
- Table Of Contents
- ################################################### -->
-
- <!-- Generate the TOCs for named components only -->
- <xsl:param name="generate.toc">
- book toc
- </xsl:param>
-
- <!-- Show only Sections up to level 3 in the TOCs -->
- <!--<xsl:param name="toc.section.depth">2</xsl:param>-->
-
- <!-- Dot and Whitespace as separator in TOC between Label and Title-->
- <xsl:param name="autotoc.label.separator" select="'. '"/>
-
-
- <!-- ###################################################
- Paper & Page Size
- ################################################### -->
-
- <!-- Paper type, no headers on blank pages, no double sided printing -->
- <xsl:param name="paper.type" select="'A4'"/>
- <!--<xsl:param name="double.sided">0</xsl:param>-->
- <xsl:param name="headers.on.blank.pages">0</xsl:param>
- <xsl:param name="footers.on.blank.pages">0</xsl:param>
-
- <!-- Space between paper border and content (chaotic stuff, don't touch) -->
- <!--<xsl:param name="page.margin.top">5mm</xsl:param>-->
- <xsl:param name="region.before.extent">10mm</xsl:param>
- <!--<xsl:param name="body.margin.top">10mm</xsl:param>-->
-
- <!--<xsl:param name="body.margin.bottom">15mm</xsl:param>-->
- <xsl:param name="region.after.extent">10mm</xsl:param>
- <!--<xsl:param name="page.margin.bottom">0mm</xsl:param>-->
-
- <!--<xsl:param name="page.margin.outer">18mm</xsl:param>-->
- <!--<xsl:param name="page.margin.inner">18mm</xsl:param>-->
-
- <!-- No intendation of Titles -->
- <xsl:param name="title.margin.left">0pc</xsl:param>
-
- <!-- ###################################################
- Fonts & Styles
- ################################################### -->
-
- <!-- Left aligned text and no hyphenation -->
- <!--<xsl:param name="alignment">justify</xsl:param>-->
- <!--<xsl:param name="hyphenate">false</xsl:param>-->
-
- <!-- Default Font size -->
- <!--<xsl:param name="body.font.master">11</xsl:param>-->
- <xsl:param name="body.font.small">8</xsl:param>
-
- <!-- ###################################################
- Tables
- ################################################### -->
-
- <!-- The table width should be adapted to the paper size -->
- <xsl:param name="default.table.width">17.4cm</xsl:param>
-
- <!-- Some padding inside tables -->
- <xsl:attribute-set name="table.cell.padding">
- <xsl:attribute name="padding-start">4pt</xsl:attribute>
- <xsl:attribute name="padding-end">4pt</xsl:attribute>
- <xsl:attribute name="padding-top">4pt</xsl:attribute>
- <xsl:attribute name="padding-bottom">4pt</xsl:attribute>
- </xsl:attribute-set>
-
- <!-- Only hairlines as frame and cell borders in tables -->
- <xsl:param name="default.table.frame">all</xsl:param>
- <xsl:param name="default.table.rules">all</xsl:param>
-
- <xsl:param name="table.frame.border.thickness">0.5pt</xsl:param>
- <xsl:param name="table.frame.border.style">solid</xsl:param>
- <xsl:param name="table.frame.border.color">black</xsl:param>
- <xsl:param name="table.cell.border.thickness">0.5pt</xsl:param>
- <xsl:param name="table.cell.border.color">black</xsl:param>
- <xsl:param name="table.cell.border.style">solid</xsl:param>
- <xsl:param name="border-start-style">solid</xsl:param>
- <xsl:param name="border-end-style">solid</xsl:param>
- <xsl:param name="border-top-style">solid</xsl:param>
- <xsl:param name="border-bottom-style">solid</xsl:param>
-
- <!--###################################################
- Labels
- ################################################### -->
-
- <!-- Label Chapters and Sections (numbering) -->
- <xsl:param name="chapter.autolabel">1</xsl:param>
- <xsl:param name="section.autolabel" select="1"/>
- <xsl:param name="section.label.includes.component.label" select="1"/>
-
- <!--###################################################
- Titles
- ################################################### -->
-
- <!-- Chapter title size -->
- <xsl:attribute-set name="chapter.titlepage.recto.style">
- <xsl:attribute name="text-align">left</xsl:attribute>
- <xsl:attribute name="font-weight">bold</xsl:attribute>
- <xsl:attribute name="font-size">
- <xsl:value-of select="$body.font.master * 1.8"/>
- <xsl:text>pt</xsl:text>
- </xsl:attribute>
- </xsl:attribute-set>
-
- <!-- Why is the font-size for chapters hardcoded in the XSL FO templates?
- Let's remove it, so this sucker can use our attribute-set only... -->
- <xsl:template match="title" mode="chapter.titlepage.recto.auto.mode">
- <fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format"
- xsl:use-attribute-sets="chapter.titlepage.recto.style">
- <xsl:call-template name="component.title">
- <xsl:with-param name="node" select="ancestor-or-self::chapter[1]"/>
- </xsl:call-template>
- </fo:block>
- </xsl:template>
-
- <!-- Sections 1, 2 and 3 titles have a small bump factor and padding -->
- <xsl:attribute-set name="section.title.level1.properties">
- <xsl:attribute name="space-before.optimum">0.8em</xsl:attribute>
- <xsl:attribute name="space-before.minimum">0.8em</xsl:attribute>
- <xsl:attribute name="space-before.maximum">0.8em</xsl:attribute>
- <xsl:attribute name="font-size">
- <xsl:value-of select="$body.font.master * 1.5"/>
- <xsl:text>pt</xsl:text>
- </xsl:attribute>
- <xsl:attribute name="space-after.optimum">0.1em</xsl:attribute>
- <xsl:attribute name="space-after.minimum">0.1em</xsl:attribute>
- <xsl:attribute name="space-after.maximum">0.1em</xsl:attribute>
- </xsl:attribute-set>
- <xsl:attribute-set name="section.title.level2.properties">
- <xsl:attribute name="space-before.optimum">0.6em</xsl:attribute>
- <xsl:attribute name="space-before.minimum">0.6em</xsl:attribute>
- <xsl:attribute name="space-before.maximum">0.6em</xsl:attribute>
- <xsl:attribute name="font-size">
- <xsl:value-of select="$body.font.master * 1.25"/>
- <xsl:text>pt</xsl:text>
- </xsl:attribute>
- <xsl:attribute name="space-after.optimum">0.1em</xsl:attribute>
- <xsl:attribute name="space-after.minimum">0.1em</xsl:attribute>
- <xsl:attribute name="space-after.maximum">0.1em</xsl:attribute>
- </xsl:attribute-set>
- <xsl:attribute-set name="section.title.level3.properties">
- <xsl:attribute name="space-before.optimum">0.4em</xsl:attribute>
- <xsl:attribute name="space-before.minimum">0.4em</xsl:attribute>
- <xsl:attribute name="space-before.maximum">0.4em</xsl:attribute>
- <xsl:attribute name="font-size">
- <xsl:value-of select="$body.font.master * 1.0"/>
- <xsl:text>pt</xsl:text>
- </xsl:attribute>
- <xsl:attribute name="space-after.optimum">0.1em</xsl:attribute>
- <xsl:attribute name="space-after.minimum">0.1em</xsl:attribute>
- <xsl:attribute name="space-after.maximum">0.1em</xsl:attribute>
- </xsl:attribute-set>
-
- <!-- Titles of formal objects (tables, examples, ...) -->
- <xsl:attribute-set name="formal.title.properties" use-attribute-sets="normal.para.spacing">
- <xsl:attribute name="font-weight">bold</xsl:attribute>
- <xsl:attribute name="font-size">
- <xsl:value-of select="$body.font.master"/>
- <xsl:text>pt</xsl:text>
- </xsl:attribute>
- <xsl:attribute name="hyphenate">false</xsl:attribute>
- <xsl:attribute name="space-after.minimum">0.4em</xsl:attribute>
- <xsl:attribute name="space-after.optimum">0.6em</xsl:attribute>
- <xsl:attribute name="space-after.maximum">0.8em</xsl:attribute>
- </xsl:attribute-set>
-
- <!--###################################################
- Programlistings
- ################################################### -->
-
- <!-- Verbatim text formatting (<code>) -->
- <xsl:attribute-set name="monospace.properties">
- <xsl:attribute name="font-size">
- <xsl:value-of select="$body.font.small"/>
- <xsl:text>pt</xsl:text>
- </xsl:attribute>
- </xsl:attribute-set>
-
- <!-- Verbatim text formatting (programlistings) -->
- <xsl:attribute-set name="monospace.verbatim.properties">
- <xsl:attribute name="font-size">
- <xsl:value-of select="$body.font.small"/>
- <xsl:text>pt</xsl:text>
- </xsl:attribute>
- </xsl:attribute-set>
-
- <xsl:attribute-set name="verbatim.properties">
- <xsl:attribute name="space-before.minimum">0.9em</xsl:attribute>
- <xsl:attribute name="space-before.optimum">0.9em</xsl:attribute>
- <xsl:attribute name="space-before.maximum">0.9em</xsl:attribute>
- <xsl:attribute name="border-color">#444444</xsl:attribute>
- <xsl:attribute name="border-style">solid</xsl:attribute>
- <xsl:attribute name="border-width">0.1pt</xsl:attribute>
- <xsl:attribute name="padding-top">0.5em</xsl:attribute>
- <xsl:attribute name="padding-left">0.5em</xsl:attribute>
- <xsl:attribute name="padding-right">0.5em</xsl:attribute>
- <xsl:attribute name="padding-bottom">0.5em</xsl:attribute>
- <xsl:attribute name="margin-left">0.5em</xsl:attribute>
- <xsl:attribute name="margin-right">0.5em</xsl:attribute>
- </xsl:attribute-set>
-
- <!-- Shade (background) programlistings -->
- <xsl:param name="shade.verbatim">1</xsl:param>
- <xsl:attribute-set name="shade.verbatim.style">
- <xsl:attribute name="background-color">#F0F0F0</xsl:attribute>
- </xsl:attribute-set>
-
- <!--###################################################
- Callouts
- ################################################### -->
-
- <!-- Use images for callouts instead of (1) (2) (3) -->
- <!--<xsl:param name="callout.graphics">0</xsl:param>-->
- <!--<xsl:param name="callout.unicode">1</xsl:param>-->
-
- <!-- Place callout marks at this column in annotated areas -->
- <xsl:param name="callout.defaultcolumn">90</xsl:param>
-
- <!--###################################################
- Admonitions
- ################################################### -->
-
- <!-- Use nice graphics for admonitions -->
- <!--<xsl:param name="admon.graphics">'1'</xsl:param>-->
- <!-- <xsl:param name="admon.graphics.path">&admon_gfx_path;</xsl:param> -->
-
- <!--###################################################
- Misc
- ################################################### -->
-
- <!-- Placement of titles -->
- <xsl:param name="formal.title.placement">
- figure after
- example before
- equation before
- table before
- procedure before
- </xsl:param>
-
- <!-- Format Variable Lists as Blocks (prevents horizontal overflow) -->
- <xsl:param name="variablelist.as.blocks">1</xsl:param>
-
- <!-- The horrible list spacing problems -->
- <xsl:attribute-set name="list.block.spacing">
- <xsl:attribute name="space-before.optimum">0.8em</xsl:attribute>
- <xsl:attribute name="space-before.minimum">0.8em</xsl:attribute>
- <xsl:attribute name="space-before.maximum">0.8em</xsl:attribute>
- <xsl:attribute name="space-after.optimum">0.1em</xsl:attribute>
- <xsl:attribute name="space-after.minimum">0.1em</xsl:attribute>
- <xsl:attribute name="space-after.maximum">0.1em</xsl:attribute>
- </xsl:attribute-set>
-
- <!--###################################################
- colored and hyphenated links
- ################################################### -->
- <xsl:template match="ulink">
- <fo:basic-link external-destination="{@url}"
- xsl:use-attribute-sets="xref.properties"
- text-decoration="underline"
- color="blue">
- <xsl:choose>
- <xsl:when test="count(child::node())=0">
- <xsl:value-of select="@url"/>
- </xsl:when>
- <xsl:otherwise>
- <xsl:apply-templates/>
- </xsl:otherwise>
- </xsl:choose>
- </fo:basic-link>
- </xsl:template>
-
- <xsl:template name="table.frame">
- <xsl:variable name="frame" select="'all'" />
-
- <xsl:attribute name="border-start-style">
- <xsl:value-of select="$table.frame.border.style"/>
- </xsl:attribute>
- <xsl:attribute name="border-end-style">
- <xsl:value-of select="$table.frame.border.style"/>
- </xsl:attribute>
- <xsl:attribute name="border-top-style">
- <xsl:value-of select="$table.frame.border.style"/>
- </xsl:attribute>
- <xsl:attribute name="border-bottom-style">
- <xsl:value-of select="$table.frame.border.style"/>
- </xsl:attribute>
- <xsl:attribute name="border-start-width">
- <xsl:value-of select="$table.frame.border.thickness"/>
- </xsl:attribute>
- <xsl:attribute name="border-end-width">
- <xsl:value-of select="$table.frame.border.thickness"/>
- </xsl:attribute>
- <xsl:attribute name="border-top-width">
- <xsl:value-of select="$table.frame.border.thickness"/>
- </xsl:attribute>
- <xsl:attribute name="border-bottom-width">
- <xsl:value-of select="$table.frame.border.thickness"/>
- </xsl:attribute>
- <xsl:attribute name="border-start-color">
- <xsl:value-of select="$table.frame.border.color"/>
- </xsl:attribute>
- <xsl:attribute name="border-end-color">
- <xsl:value-of select="$table.frame.border.color"/>
- </xsl:attribute>
- <xsl:attribute name="border-top-color">
- <xsl:value-of select="$table.frame.border.color"/>
- </xsl:attribute>
- <xsl:attribute name="border-bottom-color">
- <xsl:value-of select="$table.frame.border.color"/>
- </xsl:attribute>
- </xsl:template>
-
-</xsl:stylesheet>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/getting-started-rop/pom.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/getting-started-rop/pom.xml b/docs/docbook/getting-started-rop/pom.xml
deleted file mode 100644
index 8972a28..0000000
--- a/docs/docbook/getting-started-rop/pom.xml
+++ /dev/null
@@ -1,39 +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.
--->
-
-<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
- <parent>
- <groupId>org.apache.cayenne.docs</groupId>
- <artifactId>cayenne-docbook</artifactId>
- <version>4.0.B3-SNAPSHOT</version>
- </parent>
- <modelVersion>4.0.0</modelVersion>
- <artifactId>getting-started-rop</artifactId>
- <packaging>jar</packaging>
- <name>getting-started-rop: Docbook - Getting Started with Cayenne ROP</name>
-
- <build>
- <resources>
- <resource>
- <directory>target/site</directory>
- </resource>
- </resources>
- </build>
-</project>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/getting-started-rop/src/docbkx/authentication.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/getting-started-rop/src/docbkx/authentication.xml b/docs/docbook/getting-started-rop/src/docbkx/authentication.xml
deleted file mode 100644
index ebf4241..0000000
--- a/docs/docbook/getting-started-rop/src/docbkx/authentication.xml
+++ /dev/null
@@ -1,128 +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.
--->
-<chapter xmlns="http://docbook.org/ns/docbook"
- xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0">
- <title>Adding BASIC Authentication</title>
- <para>You probably don't want everybody in the world to connect to your service and access (and
- update!) arbitrary data in the database. The first step in securing Cayenne service is
- implementing client authentication. The easiest way to do it is to delegate the
- authentication task to the web container that is running the service. HessianConnection used
- in the previous chapter supports BASIC authentication on the client side, so we'll
- demonstrate how to set it up here.</para>
- <section xml:id="securing-rop-server-app">
- <title>Securing ROP Server Application</title>
- <para>Open web.xml file in the server project and setup security constraints with BASIC
- authentication for the ROP service:</para>
- <programlisting><security-constraint>
- <web-resource-collection>
- <web-resource-name>CayenneService</web-resource-name>
- <url-pattern>/cayenne-service</url-pattern>
- </web-resource-collection>
- <auth-constraint>
- <role-name>cayenne-service-user</role-name>
- </auth-constraint>
-</security-constraint>
-
-<login-config>
- <auth-method>BASIC</auth-method>
- <realm-name>Cayenne Realm</realm-name>
-</login-config>
-
-<security-role>
- <role-name>cayenne-service-user</role-name>
-</security-role></programlisting>
- </section>
- <section xml:id="configuring-jetty">
- <title>Configuring Jetty for BASIC Authentication</title>
-
- <para>
- <note>
- <para>These instructions are specific to Jetty 6. Other
- containers (and versions of Jetty) will have different mechansims to achieve
- the same thing.</para>
- </note>
- </para>
- <para>Open pom.xml in the server project and configure a "userRealm" for the Jetty
- plugin:</para>
- <programlisting><plugin>
- <groupId>org.mortbay.jetty</groupId>
- <artifactId>maven-jetty-plugin</artifactId>
- <version>6.1.22</version>
- <!-- adding configuration below: -->
- <configuration>
- <userRealms>
- <userRealm implementation="org.mortbay.jetty.security.HashUserRealm">
- <!-- this name must match the realm-name in web.xml -->
- <name>Cayenne Realm</name>
- <config>realm.properties</config>
- </userRealm>
- </userRealms>
- </configuration>
- </plugin>
-</plugins></programlisting>
- <para>Now create a new file called {["realm.properties"}} <emphasis role="italic">at the
- root of the server project</emphasis> and put user login/password in there:</para>
- <programlisting>cayenne-user: secret,cayenne-service-user</programlisting>
- <para>.</para>
- <para>Now let's stop the server and start it again. Everything should start as before, but
- if you go to <emphasis role="italic"
- >http://localhost:8080/tutorial/cayenne-service</emphasis>, your browser should pop
- up authentication dialog. Enter "<emphasis role="italic">cayenne-user/secret</emphasis>"
- for user name / password, and you should see "<emphasis role="italic">Hessian Requires
- POST</emphasis>" message. So the server is now secured.</para>
- </section>
- <section xml:id="running-client">
- <title>Running Client with Basic Authentication</title>
- <para>If you run the client without any changes, you'll get the following error:</para>
- <programlisting language="java">Mar 01, 2016 7:25:50 PM org.apache.cayenne.rop.http.HttpROPConnector logConnect
-INFO: Connecting to [cayenne-user@http://localhost:8080/tutorial-rop-server/cayenne-service] - dedicated session.
-Mar 01, 2016 7:25:50 PM org.apache.cayenne.rop.HttpClientConnection connect
-INFO: Server returned HTTP response code: 401 for URL: http://localhost:8080/tutorial-rop-server/cayenne-service
-java.rmi.RemoteException: Server returned HTTP response code: 401 for URL: http://localhost:8080/tutorial-rop-server/cayenne-service
- at org.apache.cayenne.rop.ProxyRemoteService.establishSession(ProxyRemoteService.java:45)
- at org.apache.cayenne.rop.HttpClientConnection.connect(HttpClientConnection.java:85)
- at org.apache.cayenne.rop.HttpClientConnection.getServerEventBridge(HttpClientConnection.java:68)
- at org.apache.cayenne.remote.ClientChannel.setupRemoteChannelListener(ClientChannel.java:279)
- at org.apache.cayenne.remote.ClientChannel.<init>(ClientChannel.java:71)
- at org.apache.cayenne.configuration.rop.client.ClientChannelProvider.get(ClientChannelProvider.java:48)
- at org.apache.cayenne.configuration.rop.client.ClientChannelProvider.get(ClientChannelProvider.java:31)
- at org.apache.cayenne.di.spi.CustomProvidersProvider.get(CustomProvidersProvider.java:39)
- at org.apache.cayenne.di.spi.FieldInjectingProvider.get(FieldInjectingProvider.java:43)
- at org.apache.cayenne.di.spi.DefaultScopeProvider.get(DefaultScopeProvider.java:50)
- at org.apache.cayenne.di.spi.DefaultInjector.getInstance(DefaultInjector.java:139)
- at org.apache.cayenne.di.spi.FieldInjectingProvider.value(FieldInjectingProvider.java:105)
- at org.apache.cayenne.di.spi.FieldInjectingProvider.injectMember(FieldInjectingProvider.java:68)
- at org.apache.cayenne.di.spi.FieldInjectingProvider.injectMembers(FieldInjectingProvider.java:59)
- at org.apache.cayenne.di.spi.FieldInjectingProvider.get(FieldInjectingProvider.java:44)
- at org.apache.cayenne.di.spi.DefaultScopeProvider.get(DefaultScopeProvider.java:50)
- at org.apache.cayenne.di.spi.DefaultInjector.getInstance(DefaultInjector.java:134)
- at org.apache.cayenne.configuration.CayenneRuntime.newContext(CayenneRuntime.java:134)
- at org.apache.cayenne.tutorial.persistent.client.Main.main(Main.java:44)</programlisting>
- <para>Which is exactly what you'd expect, as the client is not authenticating itself. So
- change the line in Main.java where we obtained an ROP connection to this:</para>
- <programlisting language="java">Map<String,String> properties = new HashMap<>();
-properties.put(Constants.ROP_SERVICE_URL_PROPERTY, "http://localhost:8080/tutorial/cayenne-service");
-properties.put(Constants.ROP_SERVICE_USERNAME_PROPERTY, "cayenne-user");
-properties.put(Constants.ROP_SERVICE_PASSWORD_PROPERTY, "secret");
-
-ClientRuntime runtime = new ClientRuntime(properties);</programlisting>
- <para>Try running again, and everything should work as before. Obviously in production
- environment, in addition to authentication you'll need to use HTTPS to access the server
- to prevent third-party eavesdropping on your password and data.</para>
- <para>Congratulations, you are done with the ROP tutorial!</para>
- </section>
-</chapter>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/getting-started-rop/src/docbkx/client-code.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/getting-started-rop/src/docbkx/client-code.xml b/docs/docbook/getting-started-rop/src/docbkx/client-code.xml
deleted file mode 100644
index 76dd9fd..0000000
--- a/docs/docbook/getting-started-rop/src/docbkx/client-code.xml
+++ /dev/null
@@ -1,159 +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.
--->
-<chapter xmlns="http://docbook.org/ns/docbook"
- xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0">
- <title>Porting Existing Code to Connect to a Web Service Instead of a Database</title>
- <section xml:id="starting-command-line-cliet">
- <title>Starting Command Line Client</title>
- <para>One of the benefits of ROP is that the client code is no different from the server
- code - it uses the same ObjectContext interface for access, same query and commit API.
- So the code below will be similar to the code presented in the first Cayenne
- Getting Started Guide, although with a few ROP-specific parts required to bootstrap the
- ObjectContext.</para>
- <para>Let's start by creating an empty Main class with the standard main() method in the
- client project:</para>
- <programlisting language="java">package org.example.cayenne.persistent.client;
-
-public class Main {
-
- public static void main(String[] args) {
-
- }
-}</programlisting>
- <para>Now the part that is actually different from regular Cayenne - establishing the server
- connection and obtaining the ObjectContext:</para>
- <programlisting language="java">Map<String, String> properties = new HashMap<>();
-properties.put(Constants.ROP_SERVICE_URL_PROPERTY, "http://localhost:8080/tutorial/cayenne-service");
-properties.put(Constants.ROP_SERVICE_USERNAME_PROPERTY, "cayenne-user");
-properties.put(Constants.ROP_SERVICE_PASSWORD_PROPERTY, "secret");
-
-ClientRuntime runtime = new ClientRuntime(properties);
-ObjectContext context = runtime.newContext(); </programlisting>
- <para>Note that the "runtime" can be used to create as many peer ObjectContexts as needed
- over the same connection, while ObjectContext is a kind of isolated "persistence
- session", similar to the server-side context. A few more notes. Since we are using
- HTTP(S) to communicate with ROP server, there's no need to explicitly close the
- connection (or channel, or context).</para>
- <para>So now let's do the same persistent operaions that we did in the first tutorial "Main"
- class. Let's start by creating and saving some objects:</para>
- <programlisting language="java">// creating new Artist
-Artist picasso = context.newObject(Artist.class);
-picasso.setName("Pablo Picasso");
-
-// Creating other objects
-Gallery metropolitan = context.newObject(Gallery.class);
-metropolitan.setName("Metropolitan Museum of Art");
-
-Painting girl = context.newObject(Painting.class);
-girl.setName("Girl Reading at a Table");
-
-Painting stein = context.newObject(Painting.class);
-stein.setName("Gertrude Stein");
-
-// connecting objects together via relationships
-picasso.addToPaintings(girl);
-picasso.addToPaintings(stein);
-
-girl.setGallery(metropolitan);
-stein.setGallery(metropolitan);
-
-// saving all the changes above
-context.commitChanges();</programlisting>
- <para>Now let's select them back:</para>
- <programlisting language="java">// ObjectSelect examples
-List<Painting> paintings1 = ObjectSelect.query(Painting.class).select(context);
-
-List<Painting> paintings2 = ObjectSelect.query(Painting.class)
- .where(Painting.NAME.likeIgnoreCase("gi%")).select(context); </programlisting>
- <para>Now, delete:</para>
- <programlisting language="java">// Delete object example
-Artist picasso = ObjectSelect.query(Artist.class).where(Artist.NAME.eq("Pablo Picasso")).selectOne(context);
-
-if (picasso != null) {
- context.deleteObject(picasso);
- context.commitChanges();
-}</programlisting>
- <para>This code is exactly the same as in the first tutorial. So now let's try running the
- client and see what happens. In Eclipse open main class and select "Run > Run As >
- Java Application" from the menu (assuming the ROP server started in the previous step is
- still running). You will some output in both server and client process consoles.
- Client:</para>
- <programlisting>INFO: Connecting to [http://localhost:8080/tutorial/cayenne-service] - dedicated session.
-INFO: === Connected, session: org.apache.cayenne.remote.RemoteSession@26544ec1[sessionId=17uub1h34r9x1] - took 111 ms.
-INFO: --- Message 0: Bootstrap
-INFO: === Message 0: Bootstrap done - took 58 ms.
-INFO: --- Message 1: flush-cascade-sync
-INFO: === Message 1: flush-cascade-sync done - took 1119 ms.
-INFO: --- Message 2: Query
-INFO: === Message 2: Query done - took 48 ms.
-INFO: --- Message 3: Query
-INFO: === Message 3: Query done - took 63 ms.
-INFO: --- Message 4: Query
-INFO: === Message 4: Query done - took 19 ms.
-INFO: --- Message 5: Query
-INFO: === Message 5: Query done - took 7 ms.
-INFO: --- Message 6: Query
-INFO: === Message 6: Query done - took 5 ms.
-INFO: --- Message 7: Query
-INFO: === Message 7: Query done - took 2 ms.
-INFO: --- Message 8: Query
-INFO: === Message 8: Query done - took 4 ms.
-INFO: --- Message 9: flush-cascade-sync
-INFO: === Message 9: flush-cascade-sync done - took 34 ms.</programlisting>
- <para>As you see client prints no SQL statmenets, just a bunch of query and flush messages
- sent to the server. The server side is more verbose, showing the actual client queries
- executed against the database:</para>
- <programlisting>...
-INFO: SELECT NEXT_ID FROM AUTO_PK_SUPPORT WHERE TABLE_NAME = ? FOR UPDATE [bind: 1:'ARTIST']
-INFO: SELECT NEXT_ID FROM AUTO_PK_SUPPORT WHERE TABLE_NAME = ? FOR UPDATE [bind: 1:'GALLERY']
-INFO: SELECT NEXT_ID FROM AUTO_PK_SUPPORT WHERE TABLE_NAME = ? FOR UPDATE [bind: 1:'PAINTING']
-INFO: INSERT INTO ARTIST (DATE_OF_BIRTH, ID, NAME) VALUES (?, ?, ?)
-INFO: [batch bind: 1->DATE_OF_BIRTH:NULL, 2->ID:200, 3->NAME:'Pablo Picasso']
-INFO: === updated 1 row.
-INFO: INSERT INTO GALLERY (ID, NAME) VALUES (?, ?)
-INFO: [batch bind: 1->ID:200, 2->NAME:'Metropolitan Museum of Art']
-INFO: === updated 1 row.
-INFO: INSERT INTO PAINTING (ARTIST_ID, GALLERY_ID, ID, NAME) VALUES (?, ?, ?, ?)
-INFO: [batch bind: 1->ARTIST_ID:200, 2->GALLERY_ID:200, 3->ID:200, 4->NAME:'Girl Reading at a Table']
-INFO: [batch bind: 1->ARTIST_ID:200, 2->GALLERY_ID:200, 3->ID:201, 4->NAME:'Gertrude Stein']
-INFO: === updated 2 rows.
-INFO: +++ transaction committed.
-INFO: --- transaction started.
-INFO: SELECT t0.GALLERY_ID, t0.NAME, t0.ARTIST_ID, t0.ID FROM PAINTING t0
-INFO: === returned 2 rows. - took 14 ms.
-INFO: +++ transaction committed.
-INFO: --- transaction started.
-INFO: SELECT t0.GALLERY_ID, t0.NAME, t0.ARTIST_ID, t0.ID FROM PAINTING t0
- WHERE UPPER(t0.NAME) LIKE UPPER(?) [bind: 1->NAME:'gi%']
-INFO: === returned 1 row. - took 10 ms.
-INFO: +++ transaction committed.
-INFO: --- transaction started.
-INFO: SELECT t0.DATE_OF_BIRTH, t0.NAME, t0.ID FROM ARTIST t0 WHERE t0.NAME = ? [bind: 1->NAME:'Pablo Picasso']
-INFO: === returned 1 row. - took 8 ms.
-INFO: +++ transaction committed.
-INFO: --- transaction started.
-INFO: DELETE FROM PAINTING WHERE ID = ?
-INFO: [batch bind: 1->ID:200]
-INFO: [batch bind: 1->ID:201]
-INFO: === updated 2 rows.
-INFO: DELETE FROM ARTIST WHERE ID = ?
-INFO: [batch bind: 1->ID:200]
-INFO: === updated 1 row.
-INFO: +++ transaction committed.</programlisting>
- <para>You are done with the basic ROP client!</para>
- </section>
-</chapter>
[08/13] cayenne git commit: CAY-2371 Switch documentation from
Docbook to Asciidoctor format
Posted by nt...@apache.org.
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/asciidoc/getting-started-rop/src/docs/asciidoc/_getting-started-rop/part2/starting.adoc
----------------------------------------------------------------------
diff --git a/docs/asciidoc/getting-started-rop/src/docs/asciidoc/_getting-started-rop/part2/starting.adoc b/docs/asciidoc/getting-started-rop/src/docs/asciidoc/_getting-started-rop/part2/starting.adoc
new file mode 100644
index 0000000..60a3f17
--- /dev/null
+++ b/docs/asciidoc/getting-started-rop/src/docs/asciidoc/_getting-started-rop/part2/starting.adoc
@@ -0,0 +1,93 @@
+// 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.
+
+include::../var.adoc[]
+
+=== Starting Client Project
+
+==== Create an ROP Client Project in Eclipse
+
+Creation of a new Eclipse project has been discussed in some details in "Getting Started with Cayenne" guide, so we will omit the screenshots for the common parts.
+
+In Eclipse select "File > New > Other..." and then "Maven > Maven Project". Click "Next". On the following screen check "Create a simple project" checkbox and click "Next" again. In the dialog shown on the screenshot below, enter "org.example.cayenne" for the "Group Id" and "tutorial-rop-client" for the "Artifact Id" (both without the quotes) and click "Finish".
+
+Now you should have a new empty project in the Eclipse workspace. Check that the project Java compiler settings are correct. Rightclick on the "tutorial-rop-client" project, select "Properties > Java Compiler" and ensure that "Compiler compliance level" is at least 1.5 (some versions of Maven plugin seem to be setting it to 1.4 by default).
+
+==== Create Client Java Classes
+
+The client doesn't need the XML ORM mapping, as it is loaded from the server. However it needs the client-side Java classes. Let's generate them from the existing mapping:
+
+* Start CayenneModeler and open cayenne.xml from the "tutorial" project (located under "tutorial/src/main/resources", unless it is already open.
+
+* Select the "datamap" DataMap and check "Allow Client Entities" checkbox.
+
+* Enter "org.example.cayenne.persistent.client" for the "Client Java Package" and click "Update.." button next to the field to refresh the client package of all entities.
+
+image::../images/datamap-enableclient.png[align="center"]
+
+* Select "Tools > Generate Classes" menu.
+
+* For "Type" select "Client Persistent Objects".
+
+* For the "Output Directory" select "tutorial-rop-client/src/main/java" folder (as client classes should go in the client project).
+
+* Click on "Classes" tab and check the "Check All Classes" checkbox (unless it is already checked and reads "Uncheck all Classes").
+
+* Click "Generate".
+
+Now go back to Eclipse, right click on "tutorial-rop-client" project and select "Refresh" - you should see pairs of classes generated for each mapped entity, same as on the server. And again, we see a bunch of errors in those classes. Let's fix it now by adding two dependencies, "cayenne-client" and "resin-hessian", in the bottom of the pom.xml file. We also need to add Caucho M2 repository to pull Hessian jar files. The resulting POM should look like this:
+
+[source, XML,subs="verbatim,attributes"]
+----
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
+ <modelVersion>4.0.0</modelVersion>
+ <groupId>org.example.cayenne</groupId>
+ <artifactId>tutorial-rop-client</artifactId>
+ <version>0.0.1-SNAPSHOT</version>
+
+ <dependencies>
+ <dependency>
+ <groupId>org.apache.cayenne</groupId>
+ <artifactId>cayenne-client</artifactId>
+ <!-- Here specify the version of Cayenne you are actually using -->
+ <version>{version}</version>
+ </dependency>
+ <dependency>
+ <groupId>com.caucho</groupId>
+ <artifactId>hessian</artifactId>
+ <version>4.0.38</version>
+ </dependency>
+ </dependencies>
+
+ <repositories>
+ <repository>
+ <id>caucho</id>
+ <name>Caucho Repository</name>
+ <url>http://caucho.com/m2</url>
+ <layout>default</layout>
+ <snapshots>
+ <enabled>false</enabled>
+ </snapshots>
+ <releases>
+ <enabled>true</enabled>
+ </releases>
+ </repository>
+ </repositories>
+</project>
+----
+
+Your computer must be connected to the internet. Once you save the pom.xml, Eclipse will download the needed jar files and add them to the project build path. After that all the errors should disappear.
+
+Now let's check the entity class pairs. They look almost identical to their server counterparts, although the superclass and the property access code are different. At this point these differences are somewhat academic, so let's go on with the tutorial.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/asciidoc/getting-started-rop/src/docs/asciidoc/_getting-started-rop/var.adoc
----------------------------------------------------------------------
diff --git a/docs/asciidoc/getting-started-rop/src/docs/asciidoc/_getting-started-rop/var.adoc b/docs/asciidoc/getting-started-rop/src/docs/asciidoc/_getting-started-rop/var.adoc
new file mode 100644
index 0000000..e575eda
--- /dev/null
+++ b/docs/asciidoc/getting-started-rop/src/docs/asciidoc/_getting-started-rop/var.adoc
@@ -0,0 +1 @@
+:version: {project-version}
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/asciidoc/getting-started-rop/src/docs/asciidoc/getting-started-rop.adoc
----------------------------------------------------------------------
diff --git a/docs/asciidoc/getting-started-rop/src/docs/asciidoc/getting-started-rop.adoc b/docs/asciidoc/getting-started-rop/src/docs/asciidoc/getting-started-rop.adoc
new file mode 100644
index 0000000..a58024b
--- /dev/null
+++ b/docs/asciidoc/getting-started-rop/src/docs/asciidoc/getting-started-rop.adoc
@@ -0,0 +1,45 @@
+// 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.
+= Getting Started with Cayenne ROP (Remote Object Persistence)
+:revnumber: {project-major-version} ({project-version})
+// enable section numbering, limiting depth to 2
+:sectnums:
+:sectnumlevels: 2
+// use custom header
+:cayenne-header: _getting-started-rop/header.html
+:cayenne-header-position: body
+// customize final layout
+//:linkcss:
+// base path to java code include
+:cayenne-root: {basedir}/../../..
+
+[small]#Copyright © 2011-2017 Apache Software Foundation and individual authors#
+
+.License
+[small]#_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_#
+
+[small]#_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._#
+
+include::_getting-started-rop/part1.adoc[]
+
+include::_getting-started-rop/part2.adoc[]
+
+
+
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/asciidoc/getting-started-rop/src/docs/asciidoc/images/datamap-enableclient.png
----------------------------------------------------------------------
diff --git a/docs/asciidoc/getting-started-rop/src/docs/asciidoc/images/datamap-enableclient.png b/docs/asciidoc/getting-started-rop/src/docs/asciidoc/images/datamap-enableclient.png
new file mode 100644
index 0000000..62a2af2
Binary files /dev/null and b/docs/asciidoc/getting-started-rop/src/docs/asciidoc/images/datamap-enableclient.png differ
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/asciidoc/pom.xml
----------------------------------------------------------------------
diff --git a/docs/asciidoc/pom.xml b/docs/asciidoc/pom.xml
new file mode 100644
index 0000000..2cf01b5
--- /dev/null
+++ b/docs/asciidoc/pom.xml
@@ -0,0 +1,132 @@
+<?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.
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~-->
+
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+
+ <parent>
+ <artifactId>cayenne-docs-parent</artifactId>
+ <groupId>org.apache.cayenne.docs</groupId>
+ <version>4.0.B3-SNAPSHOT</version>
+ </parent>
+
+ <artifactId>cayenne-asciidoc-parent</artifactId>
+ <name>cayenne-asciidoc: Cayenne AsciiDoc Documentation parent</name>
+ <modelVersion>4.0.0</modelVersion>
+ <packaging>pom</packaging>
+
+ <modules>
+ <module>cayenne-asciidoc-extension</module>
+ <module>cayenne-guide</module>
+ <module>getting-started-guide</module>
+ <module>getting-started-rop</module>
+ <module>upgrade-guide</module>
+ </modules>
+
+ <properties>
+ <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+ <asciidoctorj.version>1.5.6</asciidoctorj.version>
+ <asciidoctor.maven.plugin.version>1.5.6</asciidoctor.maven.plugin.version>
+ <asciidoctorj.pdf.version>1.5.0-alpha.16</asciidoctorj.pdf.version>
+ <jruby.version>9.1.14.0</jruby.version>
+ <cayenne.major.version>4.0</cayenne.major.version>
+ </properties>
+
+ <dependencies>
+ <dependency>
+ <groupId>org.apache.cayenne</groupId>
+ <artifactId>cayenne-server</artifactId>
+ <version>${project.version}</version>
+ </dependency>
+ <dependency>
+ <groupId>org.asciidoctor</groupId>
+ <artifactId>asciidoctorj</artifactId>
+ <version>${asciidoctorj.version}</version>
+ </dependency>
+ </dependencies>
+
+ <build>
+ <pluginManagement>
+ <plugins>
+ <plugin>
+ <groupId>org.asciidoctor</groupId>
+ <artifactId>asciidoctor-maven-plugin</artifactId>
+ <version>${asciidoctor.maven.plugin.version}</version>
+ <dependencies>
+ <dependency>
+ <groupId>org.asciidoctor</groupId>
+ <artifactId>asciidoctorj-pdf</artifactId>
+ <version>${asciidoctorj.pdf.version}</version>
+ </dependency>
+ </dependencies>
+ </plugin>
+ </plugins>
+ </pluginManagement>
+
+ <plugins>
+ <plugin>
+ <groupId>org.asciidoctor</groupId>
+ <artifactId>asciidoctor-maven-plugin</artifactId>
+ <configuration>
+ <sourceDirectory>src/docs/asciidoc</sourceDirectory>
+ <doctype>book</doctype>
+ <!-- Attributes common to all output formats -->
+ <attributes>
+ <endpoint-url>http://cayenne.apache.org</endpoint-url>
+
+ <basedir>${project.basedir}</basedir>
+ <sourcedir>${project.build.sourceDirectory}</sourcedir>
+ <project-version>${project.version}</project-version>
+ <project-major-version>${cayenne.major.version}</project-major-version>
+
+ <imagesdir>images</imagesdir>
+ <icons>font</icons>
+
+ <sectanchors>true</sectanchors>
+ <idprefix/> <!-- set the idprefix to blank -->
+ <idseparator>-</idseparator>
+ <!--
+ currently it is not possible to specify header location inside final document, so can't use
+ asciidoc's *-docinfo.html as header, instead we use extension that deal with our header
+ -->
+ <!--<docinfo>private</docinfo1>-->
+ </attributes>
+ </configuration>
+ <dependencies>
+ <dependency>
+ <groupId>org.jruby</groupId>
+ <artifactId>jruby-complete</artifactId>
+ <version>${jruby.version}</version>
+ </dependency>
+ </dependencies>
+ </plugin>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-compiler-plugin</artifactId>
+ <configuration>
+ <source>1.8</source>
+ <target>1.8</target>
+ </configuration>
+ </plugin>
+ </plugins>
+ </build>
+
+</project>
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/asciidoc/upgrade-guide/pom.xml
----------------------------------------------------------------------
diff --git a/docs/asciidoc/upgrade-guide/pom.xml b/docs/asciidoc/upgrade-guide/pom.xml
new file mode 100644
index 0000000..94818a0
--- /dev/null
+++ b/docs/asciidoc/upgrade-guide/pom.xml
@@ -0,0 +1,151 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+ <parent>
+ <artifactId>cayenne-asciidoc-parent</artifactId>
+ <groupId>org.apache.cayenne.docs</groupId>
+ <version>4.0.B3-SNAPSHOT</version>
+ </parent>
+ <modelVersion>4.0.0</modelVersion>
+
+ <artifactId>upgrade-guide</artifactId>
+
+ <packaging>jar</packaging>
+ <name>upgrade-guide: AsciiDoc - 4.0 Features Guide</name>
+
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.asciidoctor</groupId>
+ <artifactId>asciidoctor-maven-plugin</artifactId>
+ <dependencies>
+ <dependency>
+ <groupId>org.apache.cayenne.docs</groupId>
+ <artifactId>cayenne-asciidoc-extension</artifactId>
+ <version>${project.version}</version>
+ </dependency>
+ </dependencies>
+
+ <executions>
+ <!-- generate "embeddable" html content with front matter and without header/footer/styles -->
+ <execution>
+ <id>asciidoctor-html-web</id>
+ <phase>generate-resources</phase>
+ <goals>
+ <goal>process-asciidoc</goal>
+ </goals>
+ <configuration>
+ <backend>html5</backend>
+ <headerFooter>false</headerFooter> <!-- do not generate header and footer -->
+ <outputDirectory>${project.build.directory}/tmp/</outputDirectory>
+ <extensions>
+ <extension>
+ <className>org.apache.cayenne.asciidoc.CayennePostProcessor</className>
+ </extension>
+ </extensions>
+ <attributes>
+ <toc>auto</toc>
+ </attributes>
+ </configuration>
+ </execution>
+ </executions>
+ </plugin>
+
+ <!-- Move images to proper path for site -->
+ <plugin>
+ <artifactId>maven-resources-plugin</artifactId>
+ <executions>
+ <execution>
+ <id>copy docs for site</id>
+ <phase>install</phase>
+ <goals>
+ <goal>copy-resources</goal>
+ </goals>
+
+ <configuration>
+ <outputDirectory>${project.build.directory}/site/</outputDirectory>
+ <resources>
+ <resource>
+ <directory>${project.build.directory}/tmp/</directory>
+ <includes>
+ <include>${project.artifactId}.html</include>
+ <include>${project.artifactId}.toc.html</include>
+ </includes>
+ </resource>
+ </resources>
+ </configuration>
+ </execution>
+
+ <execution>
+ <id>copy images for site</id>
+ <phase>install</phase>
+ <goals>
+ <goal>copy-resources</goal>
+ </goals>
+
+ <configuration>
+ <outputDirectory>${project.build.directory}/site/${project.artifactId}/images/</outputDirectory>
+ <resources>
+ <resource>
+ <directory>${project.build.directory}/tmp/images/</directory>
+ <filtering>true</filtering>
+ </resource>
+ </resources>
+ </configuration>
+ </execution>
+ </executions>
+ </plugin>
+ </plugins>
+ </build>
+
+ <profiles>
+ <profile>
+ <id>assembly</id>
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.asciidoctor</groupId>
+ <artifactId>asciidoctor-maven-plugin</artifactId>
+ <executions>
+ <!-- generate standalone html help -->
+ <execution>
+ <id>asciidoctor-html-standalone</id>
+ <phase>generate-resources</phase>
+ <goals>
+ <goal>process-asciidoc</goal>
+ </goals>
+ <configuration>
+ <backend>html5</backend>
+ <sourceHighlighter>coderay</sourceHighlighter>
+ <embedAssets>true</embedAssets>
+ <attributes>
+ <toc>left</toc>
+ </attributes>
+ </configuration>
+ </execution>
+
+ <!-- generate PDF -->
+ <execution>
+ <id>generate-pdf-doc</id>
+ <phase>generate-resources</phase>
+ <goals>
+ <goal>process-asciidoc</goal>
+ </goals>
+ <configuration>
+ <backend>pdf</backend>
+ <sourceHighlighter>coderay</sourceHighlighter>
+ <attributes>
+ <pagenums/>
+ <toc/>
+ </attributes>
+ </configuration>
+ </execution>
+ </executions>
+ </plugin>
+ </plugins>
+ </build>
+ </profile>
+ </profiles>
+
+</project>
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/asciidoc/upgrade-guide/src/docs/asciidoc/_upgrade_guide/features.adoc
----------------------------------------------------------------------
diff --git a/docs/asciidoc/upgrade-guide/src/docs/asciidoc/_upgrade_guide/features.adoc b/docs/asciidoc/upgrade-guide/src/docs/asciidoc/_upgrade_guide/features.adoc
new file mode 100644
index 0000000..38f6478
--- /dev/null
+++ b/docs/asciidoc/upgrade-guide/src/docs/asciidoc/_upgrade_guide/features.adoc
@@ -0,0 +1,245 @@
+// 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.
+
+== Guide to 4.0 Features
+
+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.
+
+=== Java Version
+
+Minimum required JDK version is 1.7 or newer. Cayenne 4.0 is fully tested with Java 1.7, 1.8.
+
+The examples below often use Java 8 syntax. But those same examples should work without lambdas just as well.
+
+=== Cayenne Configuration
+
+==== ServerRuntimeBuilder
+
+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.:
+
+[source, java]
+----
+ServerRuntime runtime = ServerRuntime.builder("myproject")
+ .addConfigs("cayenne-project1.xml", "cayenne-project2.xml")
+ .addModule(binder -> binder.bind(JdbcEventLogger.class).toInstance(myLogger))
+ .dataSource(myDataSource)
+ .build();
+----
+
+==== Mapping-free ServerRuntime
+
+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.
+
+==== DI Container Decorators
+
+In addition to overriding services in DI container, Cayenne now allows to supply 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:
+
+[source, java]
+----
+public class MyInterfaceDecorator implements MyInterface {
+
+ private MyInterface delegate;
+
+ public MockInterface1_Decorator3(@Inject MyInterface delegate) {
+ this.delegate = delegate;
+ }
+
+ @Override
+ public String getName() {
+ return "<" + delegate.getName() + ">";
+ }
+}
+
+Module module = binder ->
+ binder.decorate(MyInterface.class).before(MyInterfaceDecorator.class);
+----
+
+=== Framework API
+
+==== Fluent Query API
+
+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:
+
+===== ObjectSelect
+
+A "chainable" analog of SelectQuery.
+
+[source, java]
+----
+Artist a = ObjectSelect
+ .query(Artist.class)
+ .where(Artist.ARTIST_NAME.eq("Picasso"))
+ .selectOne(context);
+----
+
+===== ColumnSelect
+
+This query allows you directly access individual properties of Objects and use functions (including aggregate) via type-safe API.
+
+[source, java]
+----
+List<String> names = ObjectSelect
+ .columnQuery(Artist.class, Artist.ARTIST_NAME)
+ .where(Artist.ARTIST_NAME.length().gt(6))
+ .select(context);
+----
+
+===== SQLSelect
+
+A "chainable" analog of SQLTemplate used specifically to run selecting raw SQL:
+
+[source, java]
+----
+List<Long> ids = SQLSelect
+ .scalarQuery(Long.class, "SELECT ARTIST_ID FROM ARTIST ORDER BY ARTIST_ID")
+ .select(context);
+----
+
+===== SelectById
+
+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.) :
+
+[source, java]
+----
+Artist a = SelectById
+ .query(Artist.class, 3)
+ .useLocalCache("g1")
+ .selectOne(context)
+----
+
+==== ObjectContext
+
+===== Callback-based Object Iterator
+
+ObjectContext now features a simpler way to iterate over large result sets, based on callback interface that can be implemented with a lambda:
+
+[source, java]
+----
+SelectQuery<Artist> q = new SelectQuery<Artist>(Artist.class);
+
+context.iterate(q, (Artist a) -> {
+ // do something with the object...
+ ...
+});
+----
+
+==== Generics in Expressions and Queries
+
+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.
+
+==== Property API
+
+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.
+
+==== Positional Parameter Bindings
+
+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:
+
+[source, java]
+----
+// 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);
+----
+
+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.
+
+==== Improved Transaction API
+
+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:
+
+[source, java]
+----
+runtime.performInTransaction(() -> {
+ // ... do some changes
+ context.commitChanges();
+
+ // ... do more changes
+ context.commitChanges();
+
+ return true;
+});
+----
+
+==== Transparent Database Cryptography with "cayenne-crypto" Module
+
+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:
+
+[source, java]
+----
+Module cryptoExtensions = CryptoModule.extend()
+ .keyStore("file:///mykeystore", "keystorepassword".toCharArray(), "keyalias")
+ .compress()
+ .module();
+----
+
+=== CayenneModeler
+
+==== Improved UI
+
+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.
+
+==== Dropped Support for Mapping Listeners
+
+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:
+
+[source, java]
+----
+runtime.getDataDomain().addListener(myListener);
+----
+
+or via DI:
+
+[source, java]
+----
+Module module = binder -> ServerModule.contributeDomainListeners(myListener);
+----
+
+Entity callbacks on the other hand are managed in the Modeler as before.
+
+=== Build Tools
+
+==== cdbimport
+
+"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.
+
+==== cgen
+
+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".
+
+==== Gradle Plugin
+
+Cayenne now provides it's own Gradle Plugin that allows you easily integrate cdbimport and cgen tools into your build process. Here is example of it's usage:
+
+[source, Groovy]
+----
+buildscript {
+ repositories {
+ mavenCentral()
+ }
+ dependencies {
+ classpath group: 'org.apache.cayenne.plugins', name: 'cayenne-gradle-plugin', version: '4.0.B2'
+ }
+}
+
+apply plugin: 'org.apache.cayenne'
+
+cayenne.defaultDataMap 'datamap.map.xml'
+
+dependencies {
+ compile cayenne.dependency('server')
+ compile cayenne.dependency('java8')
+}
+----
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/asciidoc/upgrade-guide/src/docs/asciidoc/_upgrade_guide/header.html
----------------------------------------------------------------------
diff --git a/docs/asciidoc/upgrade-guide/src/docs/asciidoc/_upgrade_guide/header.html b/docs/asciidoc/upgrade-guide/src/docs/asciidoc/_upgrade_guide/header.html
new file mode 100644
index 0000000..be3bea3
--- /dev/null
+++ b/docs/asciidoc/upgrade-guide/src/docs/asciidoc/_upgrade_guide/header.html
@@ -0,0 +1,24 @@
+---
+# 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.
+
+title: "Guide to 4.0 Features"
+description: "This guide highlights the new features and changes introduced in Apache Cayenne 4.0"
+cayenneVersion: "4.0"
+docsMenuTitle: "Upgrade Guide"
+weight: 50
+---
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/asciidoc/upgrade-guide/src/docs/asciidoc/upgrade-guide.adoc
----------------------------------------------------------------------
diff --git a/docs/asciidoc/upgrade-guide/src/docs/asciidoc/upgrade-guide.adoc b/docs/asciidoc/upgrade-guide/src/docs/asciidoc/upgrade-guide.adoc
new file mode 100644
index 0000000..e511cb3
--- /dev/null
+++ b/docs/asciidoc/upgrade-guide/src/docs/asciidoc/upgrade-guide.adoc
@@ -0,0 +1,44 @@
+// 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.
+= Cayenne 4.0 New Features and Upgrade Guide
+:revnumber: {project-major-version} ({project-version})
+// enable section numbering, limiting depth to 2
+:sectnums:
+:sectnumlevels: 2
+// use custom header
+:cayenne-header: _upgrade_guide/header.html
+:cayenne-header-position: body
+// customize final layout
+//:linkcss:
+// base path to java code include
+:cayenne-root: {basedir}/../../..
+
+[small]#Copyright © 2011-2017 Apache Software Foundation and individual authors#
+
+.License
+[small]#_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_#
+
+[small]#_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._#
+
+include::_upgrade_guide/features.adoc[]
+
+
+
+
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/cayenne-guide/pom.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/cayenne-guide/pom.xml b/docs/docbook/cayenne-guide/pom.xml
deleted file mode 100644
index 1327a67..0000000
--- a/docs/docbook/cayenne-guide/pom.xml
+++ /dev/null
@@ -1,31 +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.
--->
-
-<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
- <parent>
- <groupId>org.apache.cayenne.docs</groupId>
- <artifactId>cayenne-docbook</artifactId>
- <version>4.0.B3-SNAPSHOT</version>
- </parent>
-
- <modelVersion>4.0.0</modelVersion>
- <artifactId>cayenne-guide</artifactId>
- <name>cayenne-guide: Docbook - Cayenne Guide</name>
-</project>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/cayenne-guide/src/docbkx/appendix-a.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/cayenne-guide/src/docbkx/appendix-a.xml b/docs/docbook/cayenne-guide/src/docbkx/appendix-a.xml
deleted file mode 100644
index f75ba15..0000000
--- a/docs/docbook/cayenne-guide/src/docbkx/appendix-a.xml
+++ /dev/null
@@ -1,190 +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.
--->
-<appendix xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
- version="5.0" xml:id="configuration-properties">
- <title>Configuration Properties</title>
- <para>Note that the property names below are defined as constants in
- <code>org.apache.cayenne.configuration.Constants</code> interface. </para>
- <para>
- <table frame="void">
- <caption>Configuration Properties Recognized by ServerRuntime and/or ClientRuntime</caption>
- <col width="67%"/>
- <col width="15%"/>
- <col width="18%"/>
- <thead>
- <tr>
- <th>Property</th>
- <th>Possible Values</th>
- <th>Default Value</th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td><code>cayenne.jdbc.driver[.domain_name.node_name]</code> - defines a JDBC driver class to
- use when creating a DataSource. If domain name and optionally - node name
- are specified, the setting overrides DataSource info just for this
- domain/node. Otherwise the override is applied to all domains/nodes in the
- system.</td>
- <td/>
- <td>none, project DataNode configuration is used</td>
- </tr>
- <tr>
- <td><code>cayenne.jdbc.url[.domain_name.node_name] </code>- defines a DB URL to use when
- creating a DataSource. If domain name and optionally - node name are
- specified, the setting overrides DataSource info just for this domain/node.
- Otherwise the override is applied to all domains/nodes in the system.</td>
- <td/>
- <td>none, project DataNode configuration is used</td>
- </tr>
- <tr>
- <td><code>cayenne.jdbc.username[.domain_name.node_name] </code>- defines a DB user name to use
- when creating a DataSource. If domain name and optionally - node name are
- specified, the setting overrides DataSource info just for this domain/node.
- Otherwise the override is applied to all domains/nodes in the system.</td>
- <td/>
- <td>none, project DataNode configuration is used</td>
- </tr>
- <tr>
- <td><code>cayenne.jdbc.password[.domain_name.node_name]</code> - defines a DB password to use
- when creating a DataSource. If domain name and optionally - node name are
- specified, the setting overrides DataSource info just for this domain/node.
- Otherwise the override is applied to all domains/nodes in the system</td>
- <td/>
- <td>none, project DataNode configuration is used</td>
- </tr>
- <tr>
- <td><code>cayenne.jdbc.min_connections[.domain_name.node_name]</code> - defines the DB
- connection pool minimal size. If domain name and optionally - node name are
- specified, the setting overrides DataSource info just for this domain/node.
- Otherwise the override is applied to all domains/nodes in the system</td>
- <td/>
- <td>none, project DataNode configuration is used</td>
- </tr>
- <tr>
- <td><code>cayenne.jdbc.max_connections[.domain_name.node_name]</code> - defines the DB
- connection pool maximum size. If domain name and optionally - node name are
- specified, the setting overrides DataSource info just for this domain/node.
- Otherwise the override is applied to all domains/nodes in the system</td>
- <td/>
- <td>none, project DataNode configuration is used</td>
- </tr>
- <tr>
- <td><code>cayenne.querycache.size</code> - An integer defining the maximum number of entries in
- the query cache. Note that not all QueryCache providers may respect this
- property. MapQueryCache uses it, but the rest would use alternative
- configuration methods.</td>
- <td>any positive int value</td>
- <td>2000</td>
- </tr>
- <tr>
- <td><code>cayenne.server.contexts_sync_strategy</code> - defines whether peer ObjectContexts
- should receive snapshot events after commits from other contexts. If true
- (default), the contexts would automatically synchronize their state with
- peers.</td>
- <td>true, false</td>
- <td>true</td>
- </tr>
- <tr>
- <td><code>cayenne.server.object_retain_strategy</code> - defines fetched objects retain
- strategy for ObjectContexts. When weak or soft strategy is used, objects
- retained by ObjectContext that have no local changes can potetially get
- garbage collected when JVM feels like doing it.</td>
- <td>weak, soft, hard</td>
- <td>weak</td>
- </tr>
- <tr>
- <td><code>cayenne.server.max_id_qualifier_size</code> - defines a maximum number of ID
- qualifiers in the WHERE clause of queries that are generated for paginated
- queries and for DISJOINT_BY_ID prefetch processing. This is needed to avoid
- hitting WHERE clause size limitations and memory usage efficiency.</td>
- <td>any positive int</td>
- <td>10000</td>
- </tr>
- <tr>
- <td><code>cayenne.server.external_tx</code> - defines whether runtime should use
- external transactions.</td>
- <td>true, false</td>
- <td>false</td>
- </tr>
- <tr>
- <td><code>cayenne.rop.service_url</code> - defines the URL of the ROP server</td>
- <td/>
- <td/>
- </tr>
- <tr>
- <td><code>cayenne.rop.service_username</code> - defines the user name for an ROP client to
- login to an ROP server.</td>
- <td/>
- <td/>
- </tr>
- <tr>
- <td><code>cayenne.rop.service_password</code> - defines the password for an ROP client to login
- to an ROP server.</td>
- <td/>
- <td/>
- </tr>
- <tr>
- <td><code>cayenne.rop.shared_session_name</code>- defines the name of the shared session that
- an ROP client wants to join on an ROP server. If omitted, a dedicated
- session is created.</td>
- <td/>
- <td/>
- </tr>
- <tr>
- <td><code>cayenne.rop.service.timeout</code> - a value in milliseconds for the
- ROP client-server connection read operation timeout</td>
- <td>any positive long value</td>
- <td/>
- </tr>
- <tr>
- <td><code>cayenne.rop.channel_events</code> - defines whether client-side DataChannel should
- dispatch events to child ObjectContexts. If set to true, ObjectContexts will
- receive commit events and merge changes committed by peer contexts that
- passed through the common client DataChannel.</td>
- <td>true, false</td>
- <td>false</td>
- </tr>
- <tr>
- <td><code>cayenne.rop.context_change_events</code>- defines whether object property changes in
- the client context result in firing events. Client UI components can listen
- to these events and update the UI. Disabled by default.</td>
- <td>true, false</td>
- <td>false</td>
- </tr>
- <tr>
- <td><code>cayenne.rop.context_lifecycle_events</code> - defines whether object commit and
- rollback operations in the client context result in firing events. Client UI
- components can listen to these events and update the UI. Disabled by
- default.</td>
- <td>true,false</td>
- <td>false</td>
- </tr>
- <tr>
- <td><code>cayenne.server.rop_event_bridge_factory</code> - defines the name of
- the org.apache.cayenne.event.EventBridgeFactory that is passed from the ROP
- server to the client. I.e. server DI would provide a name of the factory,
- passing this name to the client via the wire. The client would instantiate
- it to receive events from the server. Note that this property is stored in
- "cayenne.server.rop_event_bridge_properties" map, not in the main
- "cayenne.properties".</td>
- <td/>
- <td/>
- </tr>
- </tbody>
- </table>
- </para>
-</appendix>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/cayenne-guide/src/docbkx/appendix-b.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/cayenne-guide/src/docbkx/appendix-b.xml b/docs/docbook/cayenne-guide/src/docbkx/appendix-b.xml
deleted file mode 100644
index cf0f035..0000000
--- a/docs/docbook/cayenne-guide/src/docbkx/appendix-b.xml
+++ /dev/null
@@ -1,100 +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.
--->
-<appendix xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
- version="5.0" xml:id="service-collections">
- <title>Service Collections</title>
- <para>Note that the collection keys below are
- defined as constants in <code>org.apache.cayenne.configuration.Constants</code>
- interface.</para>
- <para>
- <table frame="void">
- <caption>Service Collection Keys Present in ServerRuntime and/or ClientRuntime</caption>
- <col width="42%"/>
- <col width="25%"/>
- <col width="33%"/>
- <thead>
- <tr>
- <th>Collection Property</th>
- <th>Type</th>
- <th>Description</th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td><code>cayenne.properties</code></td>
- <td><code>Map<String,String></code></td>
- <td>Properties used by built-in
- Cayenne services. The keys in this map are the property names from the table
- in Appendix A. Separate copies of this map exist on the server and ROP
- client.</td>
- </tr>
- <tr>
- <td><code>cayenne.server.adapter_detectors</code></td>
- <td><code>List<DbAdapterDetector></code></td>
- <td>Contains
- objects that can discover the type of current database and install the
- correct DbAdapter in runtime.</td>
- </tr>
- <tr>
- <td><code>cayenne.server.domain_filters</code></td>
- <td><code>List<DataChannelFilter></code></td>
- <td>Stores DataDomain filters.</td>
- </tr>
- <tr>
- <td><code>cayenne.server.project_locations</code></td>
- <td><code>List<String></code></td>
- <td>Stores locations of the one of more project configuration files.</td>
- </tr>
- <tr>
- <td><code>cayenne.server.default_types</code></td>
- <td><code>List<ExtendedType></code></td>
- <td>Stores default adapter-agnostic ExtendedTypes. Default ExtendedTypes can be
- overridden / extended by DB-specific DbAdapters as well as by user-provided
- types configured in another colltecion (see
- <code>"cayenne.server.user_types"</code>).</td>
- </tr>
- <tr>
- <td><code>cayenne.server.user_types</code></td>
- <td><code>List<ExtendedType></code></td>
- <td>Stores a
- user-provided ExtendedTypes. This collection will be merged into a full list
- of ExtendedTypes and would override any ExtendedTypes defined in a default
- list, or by a DbAdapter.</td>
- </tr>
- <tr>
- <td><code>cayenne.server.type_factories</code></td>
- <td><code>List<ExtendedTypeFactory></code></td>
- <td>Stores default and user-provided ExtendedTypeFactories. ExtendedTypeFactory
- allows to define ExtendedTypes dynamically for the whole group of Java
- classes. E.g. Cayenne supplies a factory to map all Enums regardless of
- their type.</td>
- </tr>
- <tr>
- <td><code>cayenne.server.rop_event_bridge_properties</code></td>
- <td><code>Map<String, String></code></td>
- <td>Stores event bridge properties passed to the ROP client on
- bootstrap. This means that the map is configured by server DI, and passed to
- the client via the wire. The properties in this map are specific to
- EventBridgeFactory implementation (e.g JMS or XMPP connection prameters).
- One common property is <code>"cayenne.server.rop_event_bridge_factory"</code> that
- defines the type of the factory.</td>
- </tr>
- </tbody>
- </table>
- </para>
-
-</appendix>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/cayenne-guide/src/docbkx/appendix-c.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/cayenne-guide/src/docbkx/appendix-c.xml b/docs/docbook/cayenne-guide/src/docbkx/appendix-c.xml
deleted file mode 100644
index 8b036af..0000000
--- a/docs/docbook/cayenne-guide/src/docbkx/appendix-c.xml
+++ /dev/null
@@ -1,147 +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.
--->
-<appendix xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
- version="5.0" xml:id="expressions-bnf">
- <title>Expressions BNF</title>
- <para>
- <programlisting>
-TOKENS
-<DEFAULT> SKIP : {
-" "
-| "\t"
-| "\n"
-| "\r"
-}
-
-<DEFAULT> TOKEN : {
-<NULL: "null" | "NULL">
-| <TRUE: "true" | "TRUE">
-| <FALSE: "false" | "FALSE">
-}
-
-<DEFAULT> TOKEN : {
-<PROPERTY_PATH: <IDENTIFIER> ("." <IDENTIFIER>)*>
-}
-
-<DEFAULT> TOKEN : {
-<IDENTIFIER: <LETTER> (<LETTER> | <DIGIT>)* (["+"])?>
-| <#LETTER: ["_","a"-"z","A"-"Z"]>
-| <#DIGIT: ["0"-"9"]>
-}
-
-/**
- * Quoted Strings, whose object value is stored in the token manager's
- * "literalValue" field. Both single and double qoutes are allowed
- */<DEFAULT> MORE : {
-"\'" : WithinSingleQuoteLiteral
-| "\"" : WithinDoubleQuoteLiteral
-}
-
-<WithinSingleQuoteLiteral> MORE : {
-<ESC: "\\" (["n","r","t","b","f","\\","\'","`","\""] | (["0"-"3"])? ["0"-"7"] (["0"-"7"])?)> : {
-| <~["\'","\\"]> : {
-}
-
-<WithinSingleQuoteLiteral> TOKEN : {
-<SINGLE_QUOTED_STRING: "\'"> : DEFAULT
-}
-
-<WithinDoubleQuoteLiteral> MORE : {
-<STRING_ESC: <ESC>> : {
-| <~["\"","\\"]> : {
-}
-
-<WithinDoubleQuoteLiteral> TOKEN : {
-<DOUBLE_QUOTED_STRING: "\""> : DEFAULT
-}
-
-/**
- * Integer or real Numeric literal, whose object value is stored in the token manager's
- * "literalValue" field.
- */<DEFAULT> TOKEN : {
-<INT_LITERAL: ("0" (["0"-"7"])* | ["1"-"9"] (["0"-"9"])* | "0" ["x","X"] (["0"-"9","a"-"f","A"-"F"])+)
- (["l","L","h","H"])?> : {
-| <FLOAT_LITERAL: <DEC_FLT> (<EXPONENT>)? (<FLT_SUFF>)? | <DEC_DIGITS> <EXPONENT> (<FLT_SUFF>)?
-| <DEC_DIGITS> <FLT_SUFF>> : {
-| <#DEC_FLT: (["0"-"9"])+ "." (["0"-"9"])* | "." (["0"-"9"])+>
-| <#DEC_DIGITS: (["0"-"9"])+>
-| <#EXPONENT: ["e","E"] (["+","-"])? (["0"-"9"])+>
-| <#FLT_SUFF: ["d","D","f","F","b","B"]>
-}
-
-NON-TERMINALS
- expression := orCondition <EOF>
- orCondition := andCondition ( "or" andCondition )*
- andCondition := notCondition ( "and" notCondition )*
- notCondition := ( "not" | "!" ) simpleCondition
- | simpleCondition
- simpleCondition := <TRUE>
- | <FALSE>
- | scalarConditionExpression
- ( simpleNotCondition
- | ( "=" | "==" ) scalarExpression
- | ( "!=" | "<>" ) scalarExpression
- | "<=" scalarExpression
- | "<" scalarExpression | ">" scalarExpression
- | ">=" scalarExpression
- | "like" scalarExpression
- | "likeIgnoreCase" scalarExpression
- | "in" ( namedParameter | "(" scalarCommaList ")" )
- | "between" scalarExpression "and" scalarExpression
- )?
- simpleNotCondition := ( "not" | "!" )
- ( "like" scalarExpression
- | "likeIgnoreCase" scalarExpression
- | "in" ( namedParameter | "(" scalarCommaList ")" )
- | "between" scalarExpression "and" scalarExpression
- )
- scalarCommaList := ( scalarConstExpression ( "," scalarConstExpression )* )
- scalarConditionExpression := scalarNumericExpression
- | <SINGLE_QUOTED_STRING>
- | <DOUBLE_QUOTED_STRING>
- | <NULL>
- scalarExpression := scalarConditionExpression
- | <TRUE>
- | <FALSE>
- scalarConstExpression := <SINGLE_QUOTED_STRING>
- | <DOUBLE_QUOTED_STRING>
- | namedParameter
- | <INT_LITERAL>
- | <FLOAT_LITERAL>
- | <TRUE>
- | <FALSE>
- scalarNumericExpression := multiplySubtractExp
- ( "+" multiplySubtractExp | "-" multiplySubtractExp )*
- multiplySubtractExp := numericTerm ( "*" numericTerm | "/" numericTerm )*
- numericTerm := ( "+" )? numericPrimary
- | "-" numericPrimary
- numericPrimary := "(" orCondition ")"
- | pathExpression
- | namedParameter
- | <INT_LITERAL>
- | <FLOAT_LITERAL>
- namedParameter := "$" <PROPERTY_PATH>
- pathExpression := ( <PROPERTY_PATH>
- | "obj:" <PROPERTY_PATH>
- | "db:" <PROPERTY_PATH>
- | "enum:" <PROPERTY_PATH> )
-
-</programlisting>
- </para>
-
-
-</appendix>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/cayenne-guide/src/docbkx/cayenne-mapping-structure.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/cayenne-guide/src/docbkx/cayenne-mapping-structure.xml b/docs/docbook/cayenne-guide/src/docbkx/cayenne-mapping-structure.xml
deleted file mode 100644
index 6d76ef2..0000000
--- a/docs/docbook/cayenne-guide/src/docbkx/cayenne-mapping-structure.xml
+++ /dev/null
@@ -1,95 +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.
--->
-<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
- version="5.0" xml:id="cayenne-mapping-structure">
- <title>Cayenne Mapping Structure</title>
- <section xml:id="cayenne-project">
- <title>Cayenne Project</title>
- <para>A Cayenne project is an XML representation of a model connecting database schema with
- Java classes. A project is normally created and manipulated via CayenneModeler GUI and
- then used to initialize Cayenne runtime. A project is made of one or more files. There's
- always a root project descriptor file in any valid project. It is normally called
- <code>cayenne-xyz.xml</code>, where "xyz" is the name of the project.</para>
- <para>Project descriptor can reference DataMap files, one per DataMap. DataMap files are
- normally called <code>xyz.map.xml</code>, where "xyz" is the name of the DataMap. For
- legacy reasons this naming convention is different from the convention for the root
- project descriptor above, and we may align it in the future versions. Here is how a
- typical project might look on the file
- system:<screen><prompt>$</prompt> <userinput>ls -l</userinput>
-total 24
--rw-r--r-- 1 cayenne staff 491 Jan 28 18:25 cayenne-project.xml
--rw-r--r-- 1 cayenne staff 313 Jan 28 18:25 datamap.map.xml</screen></para>
- <para>DataMap are referenced by name in the root
- descriptor:<programlisting language="xml"><map name="datamap"/></programlisting></para>
- <para>Map files are resolved by Cayenne by appending "<code>.map.xml</code>" extension to the
- map name, and resolving the resulting string relative to the root descriptor URI. The
- following sections discuss varios ORM model objects, without regards to their XML
- representation. XML format details are really unimportant to the Cayenne users.</para>
- </section>
- <section xml:id="datamap">
- <title>DataMap</title>
- <para>DataMap is a container of persistent entities and other object-relational metadata.
- DataMap provides developers with a scope to organize their entities, but it does not
- provide a namespace for entities. In fact all DataMaps present in runtime are combined
- in a single namespace. Each DataMap must be associated with a DataNode. This is how
- Cayenne knows which database to use when running a query.</para>
- </section>
- <section xml:id="datanode">
- <title>DataNode</title>
- <para>DataNode is model of a database. It is actually pretty simple. It has an arbitrary
- user-provided name and information needed to create or locate a JDBC DataSource. Most
- projects only have one DataNode, though there may be any number of nodes if
- needed.</para>
- </section>
- <section xml:id="dbentity">
- <title>DbEntity</title>
- <para>DbEntity is a model of a single DB table or view. DbEntity is made of DbAttributes
- that correspond to columns, and DbRelationships that map PK/FK pairs. DbRelationships
- are not strictly tied to FK constraints in DB, and should be mapped for all logical
- "relationships" between the tables.</para>
- </section>
- <section xml:id="objentity">
- <title>ObjEntity</title>
- <para>ObjEntity is a model of a single persistent Java class. ObjEntity is made of
- ObjAttributes and ObjRelationships. Both correspond to entity class properties. However
- ObjAttributes represent "simple" properties (normally things like String, numbers,
- dates, etc.), while ObjRelationships correspond to properties that have a type of
- another entity. </para>
- <para>ObjEntity maps to one or more DbEntities. There's always one "root" DbEntity for each
- ObjEntity. ObjAttribiute maps to a DbAttribute or an Embeddable. Most often mapped
- DbAttribute is from the root DbEntity. Sometimes mapping is done to a DbAttribute from
- another DbEntity somehow related to the root DbEntity. Such ObjAttribute is called
- "flattened". Similarly ObjRelationship maps either to a single DbRelationship, or to a
- chain of DbRelationships ("flattened" ObjRelationship).</para>
- <para>ObjEntities may also contain mapping of their lifecycle callback methods.</para>
- </section>
- <section xml:id="embeddable">
- <title>Embeddable</title>
- <para>Embeddable is a model of a Java class that acts as a single attribute of an ObjEntity,
- but maps to multiple columns in the database.</para>
- </section>
- <section xml:id="procedure">
- <title>Procedure</title>
- <para>A model of a stored procedure in the database.</para>
- </section>
- <section xml:id="query">
- <title>Query</title>
- <para>A model of a query. Cayenne allows queries to be mapped in Cayenne project, or created
- in the code. Depending on the circumstances the users may take one or the other
- approach.</para>
- </section>
-</chapter>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/cayenne-guide/src/docbkx/cayennemodeler-application.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/cayenne-guide/src/docbkx/cayennemodeler-application.xml b/docs/docbook/cayenne-guide/src/docbkx/cayennemodeler-application.xml
deleted file mode 100644
index 4c6b9ae..0000000
--- a/docs/docbook/cayenne-guide/src/docbkx/cayennemodeler-application.xml
+++ /dev/null
@@ -1,116 +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.
--->
-<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
- version="5.0" xml:id="cayennemodeler-application">
- <title>CayenneModeler Application</title>
- <section xml:id="working-with-mapping-projects">
- <title>Working with Mapping Projects</title>
- <para></para>
- </section>
- <section xml:id="reverse-engineering-database">
- <title>Reverse Engineering Database</title>
- <para>
- See chapter <link linkend="re-modeler">Reverse Engineering in Cayenne Modeler</link>
- </para>
- </section>
- <section xml:id="generating-database-schema">
- <title>Generating Database Schema</title>
- <para>
- With Cayenne Modeler you can create simple database schemas without any additional database tools.
- This is a good option for initial database setup if you completely created you model with the Modeler.
- You can start SQL schema generation by selecting menu
- <emphasis role="strong">
- <guimenu>Tools</guimenu> > <guimenuitem>Generate Database Schema</guimenuitem>
- </emphasis>
- </para>
- <para>
- You can select what database parts should be generated and what tables you want
- </para>
- </section>
- <section xml:id="migrations">
- <title>Migrations</title>
- <para> </para>
- </section>
- <section xml:id="generating-java-classes">
- <title>Generating Java Classes</title>
- <para>
- Before using Cayenne in you code you need to generate java source code for persistent objects.
- This can be done with Modeler GUI or via <link linkend="mvn-cgen">cgen</link> maven/ant plugin.
- </para>
- <para>
- To generate classes in the modeler use
- <emphasis role="strong">
- <guimenu>Tools</guimenu> > <guimenuitem>Generate Classes</guimenuitem>
- </emphasis>
- </para>
- <para>
- There is three default types of code generation
- <itemizedlist>
- <listitem>
- <para><emphasis role="strong">Standard Persistent Objects</emphasis></para>
- <para>
- Default type of generation suitable for almost all cases.
- Use this type unless you now what exactly you need to customize.
- </para>
- </listitem>
- <listitem>
- <para><emphasis role="strong">Client Persistent Objects</emphasis></para>
- <para>
-
- </para>
- </listitem>
- <listitem>
- <para><emphasis role="strong">Advanced.</emphasis></para>
- <para>
- In advanced mode you can control almost all aspects of code generation including custom templates for java code.
- See default Cayenne templates on
- <link xlink:href="https://github.com/apache/cayenne/tree/master/cayenne-tools/src/main/resources/templates/v1_2">GitHub</link>
- as an example
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </section>
- <section xml:id="modeling-inheritance">
- <title>Modeling Inheritance</title>
- <para> </para>
- </section>
- <section xml:id="modeling-generic-persistence-classes">
- <title>Modeling Generic Persistent Classes</title>
- <para>Normally each ObjEntity is mapped to a specific Java class (such as Artist or
- Painting) that explicitly declare all entity properties as pairs of getters and setters.
- However Cayenne allows to map a completly generic class to any number of entities. The
- only expectation is that a generic class implements
- <emphasis>org.apache.cayenne.DataObject</emphasis>. So an ideal candidate for a
- generic class is CayenneDataObject, or some custom subclass of CayenneDataObject.</para>
- <para>If you don't enter anything for Java Class of an ObjEntity, Cayenne assumes generic
- mapping and uses the following implicit rules to determine a class of a generic object.
- If DataMap "Custom Superclass" is set, runtime uses this class to instantiate new
- objects. If not, org.apache.cayenne.CayenneDataObject is used.</para>
- <para>Class generation procedures (either done in the Modeler or with Ant or Maven) would
- skip entities that are mapped to CayenneDataObject explicitly or have no class
- mapping.</para>
- </section>
- <section xml:id="mapping-objattributes-to-custom-classes">
- <title>Mapping ObjAttributes to Custom Classes</title>
- <para> </para>
- </section>
- <section xml:id="modeling-pk-generation-strategy">
- <title>Modeling Primary Key Generation Strategy</title>
- <para> </para>
- </section>
-</chapter>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/docbook/cayenne-guide/src/docbkx/current-limitations.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/cayenne-guide/src/docbkx/current-limitations.xml b/docs/docbook/cayenne-guide/src/docbkx/current-limitations.xml
deleted file mode 100644
index 4b69324..0000000
--- a/docs/docbook/cayenne-guide/src/docbkx/current-limitations.xml
+++ /dev/null
@@ -1,20 +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.
--->
-<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
- version="5.0" xml:id="current-limitations">
- <title>Current Limitations</title>
-</chapter>
[10/13] cayenne git commit: CAY-2371 Switch documentation from
Docbook to Asciidoctor format
Posted by nt...@apache.org.
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part3/rop.adoc
----------------------------------------------------------------------
diff --git a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part3/rop.adoc b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part3/rop.adoc
new file mode 100644
index 0000000..f69f98a
--- /dev/null
+++ b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part3/rop.adoc
@@ -0,0 +1,54 @@
+// 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.
+
+[[rop]]
+=== Introduction to ROP
+
+==== What is ROP
+
+"Remote Object Persistence" is a low-overhead web services-based technology that provides lightweight object persistence and query functionality to 'remote' applications. In other words it provides familiar Cayenne API to applications that do not have direct access to the database. Instead such applications would access Cayenne Web Service (CWS). A single abstract data model (expressed as Cayenne XML DataMap) is used on the server and on the client, while execution logic can be partitioned between the tiers.The following picture compares a regular Cayenne web application and a rich client application that uses remote object persistence technology:
+
+image::../images/remote-object-persistence.jpg[align="center"]
+
+Persistence stack above consists of the following parts:
+
+- ORM Tier: a server-side Cayenne Java application that directly connects to the database via JDBC.
+
+- CWS (Cayenne Web Service): A wrapper around an ORM tier that makes it accessible to remote CWS clients.
+
+- Remote Tier (aka Client Tier): A Java application that has no direct DB connection and persists its objects by connecting to remote Cayenne Web Service (CWS). Note that CWS Client doesn't have to be a desktop application. It can be another server-side application. The word "client" means a client of Cayenne Web Service.
+
+==== Main Features
+
+- Unified approach to lightweight object persistence across multiple tiers of a distributed system.
+
+- Same abstract object model on the server and on the client.
+
+- Client can "bootstrap" from the server by dynamically loading persistence metadata.
+
+- An ability to define client objects differently than the server ones, and still have seamless persistence.
+
+- Generic web service interface that doesn't change when object model changes.
+
+- An ability to work in two modes: dedicated session mode or shared ("chat") mode when multiple remote clients collaboratively work on the same data.
+
+- Lazy object and collection faulting.
+
+- Full context lifecycle
+
+- Queries, expressions, local query caching, paginated queries.
+
+- Validation
+
+- Delete Rules
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part3/ropDeployment.adoc
----------------------------------------------------------------------
diff --git a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part3/ropDeployment.adoc b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part3/ropDeployment.adoc
new file mode 100644
index 0000000..6aa4388
--- /dev/null
+++ b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part3/ropDeployment.adoc
@@ -0,0 +1,34 @@
+// 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.
+
+=== ROP Deployment
+
+==== Deploying ROP Server
+
+NOTE: Recent versions of Tomcat and Jetty containers (e.g. Tomcat 6 and 7, Jetty 8) contain code addressing a security concern related to "session fixation problem" by resetting the existing session ID of any request that requires BASIC authentcaition. If ROP service is protected with declarative security (see the ROP tutorial and the following chapters on security), this feature prevents the ROP client from attaching to its session, resulting in MissingSessionExceptions. To solve that you will need to either switch to an alternative security mechanism, or disable "session fixation problem" protections of the container. E.g. the later can be achieved in Tomcat 7 by adding the following context.xml file to the webapp's META-INF/ directory:
+
+[source, XML]
+----
+<Context>
+ <Valve className="org.apache.catalina.authenticator.BasicAuthenticator"
+ changeSessionIdOnAuthentication="false" />
+</Context>
+----
+
+(The <Valve> tag can also be placed within the <Context> in any other locations used by Tomcat to load context configurations)
+
+==== Deploying ROP Client
+
+==== Security
+
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part3/ropSetup.adoc
----------------------------------------------------------------------
diff --git a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part3/ropSetup.adoc b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part3/ropSetup.adoc
new file mode 100644
index 0000000..0307dfb
--- /dev/null
+++ b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part3/ropSetup.adoc
@@ -0,0 +1,20 @@
+// 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.
+
+=== Implementing ROP Client
+
+==== System Requirements
+
+==== Jar Files and Dependencies
+
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part3/serverImpl.adoc
----------------------------------------------------------------------
diff --git a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part3/serverImpl.adoc b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part3/serverImpl.adoc
new file mode 100644
index 0000000..67e09e2
--- /dev/null
+++ b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part3/serverImpl.adoc
@@ -0,0 +1,16 @@
+// 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.
+
+=== Implementing ROP Server
+
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part4.adoc
----------------------------------------------------------------------
diff --git a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part4.adoc b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part4.adoc
new file mode 100644
index 0000000..a5c722b
--- /dev/null
+++ b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part4.adoc
@@ -0,0 +1,25 @@
+// 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.
+
+== DB-First Flow
+
+include::part4/introduction.adoc[]
+
+include::part4/filtering.adoc[]
+
+include::part4/otherSettings.adoc[]
+
+include::part4/revEngineering.adoc[]
+
+
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part4/filtering.adoc
----------------------------------------------------------------------
diff --git a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part4/filtering.adoc b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part4/filtering.adoc
new file mode 100644
index 0000000..12d1484
--- /dev/null
+++ b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part4/filtering.adoc
@@ -0,0 +1,369 @@
+// 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.
+
+=== Filtering
+
+The first thing you usually want to control during reverse engineering is what exactly should be loaded from database and what not. One of the most common cases is excluding system tables, as you usually don't want to map them.
+
+Briefly, you are able to include/exclude tables, columns and procedures and do it at several levels: default, catalog, schema. Although everything defined at the top level (default rules) will be applied for the nested elements, all rules from the most specific areas will override general rules (i.e. rules from schemas override rules from catalogs and even more override default rules).
+
+The following use-cases will provide you a better understanding of how filtering works and how you could use it.
+
+==== Process everything from schema/catalog
+
+The simplest example of reverse engineering is processing tables from one schema of catalog and there are several options to do this. Basic syntax is described below:
+
+[source, XML]
+----
+<dbimport>
+ <!-- Ant/Maven in case you only want to specify the schema to import -->
+ <schema>SCHEMA_NAME</schema>
+
+ <!-- Maven way in case you have nested elements in the schema -->
+ <schema>
+ <name>SCHEMA_NAME</name>
+ ...
+ </schema>
+
+ <!-- Ant way in case you have nested elements in the schema -->
+ <schema name="SCHEMA_NAME">
+ ...
+ </schema>
+</dbimport>
+----
+
+The same options are available for catalogs:
+
+[source, XML]
+----
+<dbimport>
+ <!-- Ant/Maven in case you only want to specify the catalog to import -->
+ <catalog>CATALOG_NAME</catalog>
+
+ <!-- Maven way in case you have nested elements in the catalog -->
+ <catalog>
+ <name>CATALOG_NAME</name>
+ ...
+ </catalog>
+
+ <!-- Ant way in case you have nested elements in the catalog -->
+ <catalog name="CATALOG_NAME">
+ ...
+ </catalog>
+</dbimport>
+----
+
+===== Note
+
+Current version of reverse engineering doesn't support catalog filtering for Postgres database.
+
+==== Combine Schema and Catalog filters
+
+Cayenne supports combination of different schemas and catalogs, and it filters data according to your requirements. You could achieve this by the following example of reverse engineering configuration:
+
+[source, XML]
+----
+<dbimport>
+
+ <catalog>
+ <name>shop_01</name>
+ <schema>schema-name-01</schema>
+ <schema>schema-name-02</schema>
+ <schema>schema-name-03</schema>
+ </catalog>
+
+ <catalog>
+ <name>shop_02</name>
+ <schema>schema-name-01</schema>
+ </catalog>
+
+ <catalog>
+ <name>shop_03</name>
+ <schema>schema-name-01</schema>
+ <schema>schema-name-02</schema>
+ <schema>schema-name-03</schema>
+ </catalog>
+
+</dbimport>
+----
+
+In the example above, Cayenne reverse engineering process contains three catalogs named as shop_01, shop_02 and shop_03, each of wich has their own schemas. Cayenne will load all data only from the declared catalogs and schemas.
+
+If you want to load everything from database, you could simply declare catalog specification alone.
+
+[source, XML]
+----
+<dbimport>
+
+ <catalog>shop_01</catalog>
+ <catalog>shop_02</catalog>
+ <catalog>shop_03</catalog>
+
+</dbimport>
+----
+
+If you want to do reverse engineering for specific schemas, just remove unwanted schemas from the catalog section. For example, if you want to process schema-name-01 and schema-name-03 schemas only, then you should change reverse engineering section like this.
+
+[source, XML]
+----
+<dbimport>
+
+ <catalog>
+ <name>shop_01</name>
+ <schema>schema-name-01</schema>
+ <schema>schema-name-03</schema>
+ </catalog>
+
+ <catalog>
+ <name>shop_02</name>
+ <schema>schema-name-01</schema>
+ </catalog>
+
+ <catalog>
+ <name>shop_03</name>
+ <schema>schema-name-01</schema>
+ <schema>schema-name-03</schema>
+ </catalog>
+
+</dbimport>
+----
+
+==== Including and Excluding tables, columns and procedures
+
+Cayenne reverse engineering let you fine tune table, columns and stored procedures names that you need to import to your model file. In every filter you can use regexp syntax. Here is some examples of configuration for common tasks.
+
+1) Include tables with ‘CRM_’ prefix if you are working in that domain of application:
+
+[source, XML]
+----
+<includeTable>CRM_.*</includeTable>
+----
+
+2) Include tables with ‘_LOOKUP’ suffix
+
+[source, XML]
+----
+<includeTable>
+ <pattern>.*_LOOKUP</pattern>
+</includeTable>
+----
+
+3) Exclude tables with ‘CRM_’ prefix if you are not working only in that domain of application:
+
+[source, XML]
+----
+<excludeTable>CRM_.*</excludeTable>
+----
+
+4) Include only specific columns that follows specific naming convention:
+
+[source, XML]
+----
+<includeColumn>includeColumn01</includeColumn>
+<includeColumn>includeColumn03</includeColumn>
+----
+
+5) Exclude system or obsolete columns:
+
+[source, XML]
+----
+<excludeColumn>excludeColumn01</excludeColumn>
+<excludeColumn>excludeColumn03</excludeColumn>
+----
+
+6) Include/Exclude columns for particular table or group of tables:
+
+[source, XML]
+----
+<includeTable>
+ <pattern>table pattern</pattern>
+ <includeColumn>includeColumn01</includeColumn>
+ <excludeColumn>excludeColumn01</excludeColumn>
+</includeTable>
+----
+
+7) Include stored procedures:
+
+[source, XML]
+----
+<includeProcedure>includeProcedure01</includeProcedure>
+<includeProcedure>
+ <pattern>includeProcedure03</pattern>
+</includeProcedure>
+----
+
+8) Exclude stored procedures by pattern:
+
+[source, XML]
+----
+<excludeProcedure>excludeProcedure01</excludeProcedure>
+<excludeProcedure>
+ <pattern>excludeProcedure03</pattern>
+</excludeProcedure>
+----
+
+All filtering tags `<includeTable>`, `<excludeTable>`, `<includeColumn>`, `<excludeColumn>`, `<includeProcedure>` and `<excludeProcedure>` have 2 ways to pass filtering RegExp.
+
+1) text inside tag
+
+[source, XML]
+----
+ <includeTable>CRM_.*</includeTable>
+----
+
+2) pattern inner tag
+
+[source, XML]
+----
+ <includeTable>
+ <pattern>.*_LOOKUP</pattern>
+ </includeTable>
+----
+
+All filtering tags can be placed inside schema and catalog tags, but also inside `<dbimport>` tag. It means that filtering rules will be applied for all schemas and catalogs.
+
+==== Complete filtering example
+
+Initially, let’s make a small sample. Consider the following reverse engineering configuration.
+
+[source, XML]
+----
+<dbimport>
+ <catalog>shop-01</catalog>
+</dbimport>
+----
+
+In this case reverse engineering will not filter anything from the shop-01 catalog. If you really want to filter database columns, tables, stored procedures and relationships, you could do it in the following way.
+
+[source, XML]
+----
+<dbimport>
+ <catalog>shop-01</catalog>
+ <catalog>
+ <name>shop-02</name>
+ <includeTable>includeTable-01</includeTable>
+ </catalog>
+</dbimport>
+----
+
+Then Cayenne will do reverse engineering for both shop-01 and shop-02 catalogs. First catalog will not be processed for filtering, but the second catalog will be processed with “includeTable-01” filter.
+
+Let’s assume you have a lot of table prefixes with the same names. Cayenne allows you to mention a pattern as regular expression. Using regular expressions is easier way to handle a big amount of database entities than writing filter config for each use-case. They make your configuration more readable, understandable and straightforward. There is not complex. Let’s see how to use patterns in reverse engineering configuration with complete example.
+
+[source, XML]
+----
+<dbimport>
+
+ <catalog>shop-01</catalog>
+
+ <catalog>
+ <name>shop-02</name>
+ </catalog>
+
+ <catalog>
+ <name>shop-03</name>
+ <includeTable>includeTable-01</includeTable>
+
+ <includeTable>
+ <pattern>includeTable-02</pattern>
+ </includeTable>
+
+ <includeTable>
+ <pattern>includeTable-03</pattern>
+ <includeColumn>includeColumn-01</includeColumn>
+ <excludeColumn>excludeColumn-01</excludeColumn>
+ </includeTable>
+
+ <excludeTable>excludeTable-01</excludeTable>
+
+ <excludeTable>
+ <pattern>excludeTable-02</pattern>
+ </excludeTable>
+
+ <includeColumn>includeColumn-01</includeColumn>
+
+ <includeColumn>
+ <pattern>includeColumn-02</pattern>
+ </includeColumn>
+
+ <excludeColumn>excludeColumn-01</excludeColumn>
+
+ <excludeColumn>
+ <pattern>excludeColumn-02</pattern>
+ </excludeColumn>
+
+ <includeProcedure>includeProcedure-01</includeProcedure>
+
+ <includeProcedure>
+ <pattern>includeProcedure-02</pattern>
+ </includeProcedure>
+
+ <excludeProcedure>excludeProcedure-01</excludeProcedure>
+
+ <excludeProcedure>
+ <pattern>excludeProcedure-02</pattern>
+ </excludeProcedure>
+
+ </catalog>
+</dbimport>
+----
+
+The example above should provide you more idea about how to use filtering and patterns in Cayenne reverse engineering. You could notice that this example demonstrates you the "name" and "pattern" configurations. Yes, you could use these as separates xml element and xml attributes.
+
+The cdbimport will execute reverse engineering task for all entities from “shop-01” and “shop-02”, including tables, views, stored procedures and table columns. As “shop-03” has variety filter tags, entities from this catalog will be filtered by cdbimport.
+
+==== Ant configuration example
+
+Here is config sample for `Ant` task:
+
+[source, XML]
+----
+<!-- inside <cdbimport> tag -->
+<catalog>shop-01</catalog>
+
+<catalog name="shop-02"/>
+
+<catalog name="shop-03">
+
+ <includeTable>includeTable-01</includeTable>
+ <includeTable pattern="includeTable-02"/>
+
+ <includeTable pattern="includeTable-03">
+ <includeColumn>includeColumn-01</includeColumn>
+ <excludeColumn>excludeColumn-01</excludeColumn>
+ </includeTable>
+
+ <excludeTable>excludeTable-01</excludeTable>
+ <excludeTable pattern="excludeTable-02"/>
+
+ <includeColumn>includeColumn-01</includeColumn>
+ <includeColumn pattern="includeColumn-02"/>
+
+ <excludeColumn>excludeColumn-01</excludeColumn>
+ <excludeColumn pattern="excludeColumn-02"/>
+
+ <includeProcedure>includeProcedure-01</includeProcedure>
+ <includeProcedure pattern="includeProcedure-02"/>
+
+ <excludeProcedure>excludeProcedure-01</excludeProcedure>
+ <excludeProcedure pattern="excludeProcedure-02"/>
+
+</catalog>
+----
+
+NOTE: In Ant task configuration all filter tags located inside root tag `<cdbimport>` as there is no `<dbimport>` tag.
+
+
+
+
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part4/introduction.adoc
----------------------------------------------------------------------
diff --git a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part4/introduction.adoc b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part4/introduction.adoc
new file mode 100644
index 0000000..9fbd3a2
--- /dev/null
+++ b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part4/introduction.adoc
@@ -0,0 +1,75 @@
+// 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.
+
+include::../var.adoc[]
+
+[[dbFirstFlow]]
+=== Introduction
+
+[[cImp]]
+==== "DB-first" Flow
+
+An ORM system consists of three parts: database, OR mapping and persistent Java classes. These parts always need to be kept in sync with each other for the application to work. "DB-first" flow is a common and practical approach to synchronization that assumes the database to be the master source of the metadata, with other two parts synchronized from the DB as the schema evolves. Cayenne provides a number of tools to automate and control it. Here is how "DB-first" flow is typically implemented:
+
+- A SQL migrations framework is used to bring a local DB to a certain version. This is outside of the scope of Cayenne and is done with a third-party tool, such as Liquibase or Flyway.
+
+- OR mapping model (Cayenne XML files) are synchronized with the state of the database using `"cdbimport"` tool provdied by Cayenne.
+
+- Object layer of the OR mapping model is customized to the developer liking, usually via CayenneModeler. Subsequent runs of `"cdbimport"` will not override any customizations that you make.
+
+- Java classes are generated using `"cgen"` tool provided by Cayenne.
+
+"cgen" and "cdbimport" tools can be invoked from Maven or Ant as discussed in the "Including Cayenne in a Project" chapter or run from CayenneModeler. This chapter will mostly focus on "cdbimport".
+
+Here is simple maven configuration to start with:
+
+==== Introduction to "cdbimport"
+
+Here is a simple Maven configuration of "cdbimport" (for details see xref:mavenCdbimort[cayenne-maven-plugin] documentation)
+
+[source, XML,subs="verbatim,attributes"]
+----
+<plugin>
+ <groupId>org.apache.cayenne.plugins</groupId>
+ <artifactId>cayenne-maven-plugin</artifactId>
+ <version>{version}</version>
+
+ <configuration>
+ <map>${project.basedir}/src/main/resources/datamap.map.xml</map>
+ <dataSource>
+ <url><!-- jdbc url --></url>
+ <driver><!-- jdbc driver class --></driver>
+ <username>username</username>
+ <password>password</password>
+ </dataSource>
+ <dbimport>
+ <defaultPackage>com.example.package</defaultPackage>
+ <includeTable>.*</includeTable>
+ </dbimport>
+ </configuration>
+ <dependencies>
+ <!-- jdbc driver dependency -->
+ </dependencies>
+</plugin>
+----
+In the next chapters we will discuss various filtering and other reverse-engineering options.
+
+
+
+
+
+
+
+
+
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part4/otherSettings.adoc
----------------------------------------------------------------------
diff --git a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part4/otherSettings.adoc b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part4/otherSettings.adoc
new file mode 100644
index 0000000..2315ba3
--- /dev/null
+++ b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part4/otherSettings.adoc
@@ -0,0 +1,64 @@
+// 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.
+
+=== Other Settings
+
+In databases relations are defined via foreign keys and there are a lot of different politics according to the level of relationships and ways how those relationships could be modeled in database. Anyway, cdbimport is able to recognize basic patterns of relationships, such as OneToMany, OneToOne and ManyToMany.
+
+==== Skip Relationships Loading
+
+You are able to skip relationships loading by the `<skipRelationshipsLoading>` element.
+
+[source, XML]
+----
+<dbimport>
+ <skipRelationshipsLoading>true</skipRelationshipsLoading>
+</dbimport>
+----
+
+==== Skip Primary Keys Loading
+
+Another useful Cayenne reverse engineering property is `<skipPrimaryKeyLoading>`. If you decide to support all relationships at the application layer and avoid their management in database, you’ll find useful to turn off primary keys synchronization at all.
+
+[source, XML]
+----
+ <dbimport>
+ <skipPrimaryKeyLoading>true</skipPrimaryKeyLoading>
+ </dbimport>
+----
+
+==== Table Types
+
+By default, cdbimport imports tables and views. Some databases may support other table-like objects, e.g. `SYSTEM TABLE, GLOBAL TEMPORARY, LOCAL TEMPORARY, ALIAS, SYNONYM`, etc. To control which types should be included `<tableType></tableType>` element is used. Some examples:
+
+Import tables only (skip views and others and other types):
+
+[source, XML]
+----
+<dbimport>
+ <tableType>TABLE</tableType>
+</dbimport>
+----
+
+Tables and views (the default option):
+
+[source, XML]
+----
+ <dbimport>
+ <tableType>TABLE</tableType>
+ <tableType>VIEWS</tableType>
+</dbimport>
+----
+
+
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part4/revEngineering.adoc
----------------------------------------------------------------------
diff --git a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part4/revEngineering.adoc b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part4/revEngineering.adoc
new file mode 100644
index 0000000..0dafaac
--- /dev/null
+++ b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part4/revEngineering.adoc
@@ -0,0 +1,57 @@
+// 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.
+
+[[reverse]]
+=== Reverse Engineering in Cayenne Modeler
+
+Alternative aproach to using xref:cImp[cdbimport] is doing reverse engineering from xref:runModeler[Cayenne Modeler]. Currently modeler GUI doesn't support all features of ant/maven tasks but it suffice for general DB import. Especially it's a good place to quickly start working on your data model.
+
+You can find reverse engineering tool in main modeler menu *Tools > Reengineer Database Schema*
+
+==== DataSource selection
+
+First you should select DataSource. If you don't have any DataSource yet you can create one from this menu.
+
+image::../images/re-modeler-datasource-select.png[align="center"]
+
+Datasource selection dialog.
+
+==== Reverse engineering options
+
+Once DataSource is selected you can proceed to reverse engineering options.
+
+image::../images/re-modeler-reverseengineering-dialog.png[align="center"]
+
+Reverse Engineering dialog.
+
+Here is a list of options to tune what will be processed by reverse engineering:
+
+- *Select Catalog*: catalog to process
+
+NOTE: You can only select one catalog. If you need to import multiple catalogs you need to run process several times.
+
+- *Table Name Pattern*: RegExp to filter tables. Default pattern .* includes all tables.
+
+- *Procedure Name Pattern*: RegExp to filter procedures. Default pattern .* includes all stored procedures.
+
+- *Naming Strategy*: Currently there is only one naming strategy available. See ant/maven tools xref:reverse[documentation] for details about naming strategy.
+
+- *Tables with Meaningful PK Pattern*: Comma separated list of RegExp's for tables that you want to have meaningful primary keys. By default no meaningful PKs are created.
+
+- *Use Java primitive types*: Use primitive types (e.g. *int*) or Object types (e.g. *java.lang.Integer*).
+
+- *Use old java.util.Date type*: Use *java.util.Date* for all columns with *DATE/TIME/TIMESTAMP* types. By default *java.time.* types will be used.
+
+
+
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5.adoc
----------------------------------------------------------------------
diff --git a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5.adoc b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5.adoc
new file mode 100644
index 0000000..c9dda30
--- /dev/null
+++ b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5.adoc
@@ -0,0 +1,30 @@
+// 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.
+
+== Cayenne Additional Modules
+
+include::part5/cacheInvalidation.adoc[]
+
+include::part5/commitLog.adoc[]
+
+include::part5/crypto.adoc[]
+
+include::part5/dbcpIntegration.adoc[]
+
+include::part5/java8.adoc[]
+
+include::part5/jCache.adoc[]
+
+include::part5/jodaTime.adoc[]
+
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/cacheInvalidation.adoc
----------------------------------------------------------------------
diff --git a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/cacheInvalidation.adoc b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/cacheInvalidation.adoc
new file mode 100644
index 0000000..7577238
--- /dev/null
+++ b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/cacheInvalidation.adoc
@@ -0,0 +1,95 @@
+// 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.
+
+include::../var.adoc[]
+
+[[cacheInvalidation]]
+=== Cache invalidation extension
+
+==== Description
+
+Cache invalidation module is an extension that allows to define cache invalidation policy programmatically.
+
+==== Including in a project
+
+===== Maven
+
+[source, XML,subs="verbatim,attributes"]
+----
+<dependency>
+ <groupId>org.apache.cayenne</groupId>
+ <artifactId>cayenne-cache-invalidation</artifactId>
+ <version>{version}</version>
+</dependency>
+----
+
+===== Gradle
+
+[source, Groovy, subs="verbatim,attributes"]
+----
+compile 'org.apache.cayenne:cayenne-cache-invalidation:{version}'
+----
+
+==== Usage
+
+Module supports autoloading mechanism, so no other actions required to enable it. Just mark your entities with @CacheGroups annotation and you are ready to use it:
+
+[source, java]
+----
+@CacheGroups("some-group")
+public class MyEntity extends _MyEntity {
+ // ...
+}
+----
+
+After any modification of `MyEntity` objects cache group `"some-group"` will be dropped from cache automatically.
+
+===== Note
+
+You can read more about cache and cache groups in corresponding xref:caching[chapter] of this documentation.
+
+In case you need some complex logic of cache invalidation you can disable default behaviour and provide your own.
+
+To do so you need to implement `org.apache.cayenne.cache.invalidation.InvalidationHandler` interface and setup Cache Invalidation module to use it. Let's use implementation class called `CustomInvalidationHandler` that will simply match all entities' types with `"custom-group"` cache group regardless of any annotations:
+
+[source, java]
+----
+public class CustomInvalidationHandler implements InvalidationHandler {
+ @Override
+ public InvalidationFunction canHandle(Class<? extends Persistent> type) {
+ return p -> Collections.singleton(new CacheGroupDescriptor("custom-group"));
+ }
+}
+----
+
+Now we'll set up it's usage by `ServerRuntime`:
+
+[source, java]
+----
+ServerRuntime.builder()
+ .addModule(CacheInvalidationModule.extend()
+ // this will disable default handler based on @CacheGroups, and this is optional
+ .noCacheGroupsHandler()
+ .addHandler(CustomInvalidationHandler.class)
+ .module())
+----
+
+NOTE: You can combine as many invalidation handlers as you need.
+
+
+
+
+
+
+
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/commitLog.adoc
----------------------------------------------------------------------
diff --git a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/commitLog.adoc b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/commitLog.adoc
new file mode 100644
index 0000000..7501a42
--- /dev/null
+++ b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/commitLog.adoc
@@ -0,0 +1,83 @@
+// 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.
+
+include::../var.adoc[]
+
+=== Commit log extension
+
+==== Description
+
+The goal of this module is to capture commit changes and present them to interested parties in an easy-to-process format.
+
+==== Including in a project
+
+===== Maven
+
+[source, XML,subs="verbatim,attributes"]
+----
+<dependency>
+ <groupId>org.apache.cayenne</groupId>
+ <artifactId>cayenne-commitlog</artifactId>
+ <version>{version}</version>
+</dependency>
+----
+
+===== Gradle
+
+[source, Groovy, subs="verbatim,attributes"]
+----
+compile 'org.apache.cayenne:cayenne-commitlog:{version}'
+----
+
+==== Usage
+
+In order to use `commitlog` module you need to perform three steps:
+
+1) Mark all entities which changes you are interested in with `@org.apache.cayenne.commitlog.CommitLog` annotation
+
+[source, Java]
+----
+@CommitLog(ignoredProperties = {"somePrivatePropertyToSkip"})
+public class MyEntity extends _MyEntity {
+ // ...
+}
+----
+
+2) Implement `CommitLogListener` interface.
+
+[source, java]
+----
+ CommitLogListener {
+ @Override
+ public void onPostCommit(ObjectContext originatingContext, ChangeMap changes) {
+ // ChangeMap will contain all information about changes happened in performed commit
+ // this particular example will 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));
+ }
+}
+----
+
+3) Inject your listener into `ServerRuntime`
+
+[source, java]
+----
+ServerRuntime.builder()
+ .addModule(CommitLogModule.extend()
+ .addListener(MyCommitLogListener.class)
+ .module())
+----
+
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/crypto.adoc
----------------------------------------------------------------------
diff --git a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/crypto.adoc b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/crypto.adoc
new file mode 100644
index 0000000..a2f91ca
--- /dev/null
+++ b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/crypto.adoc
@@ -0,0 +1,116 @@
+// 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.
+
+include::../var.adoc[]
+
+=== Crypto extension
+
+==== Description
+
+Crypto module allows encrypt and decrypt values stored in DB transparently to your Java app.
+
+==== Including in a project
+
+===== Maven
+
+[source, XML,subs="verbatim,attributes"]
+----
+<dependency>
+ <groupId>org.apache.cayenne</groupId>
+ <artifactId>cayenne-crypto</artifactId>
+ <version>{version}</version>
+</dependency>
+----
+
+===== Gradle
+
+[source, Groovy, subs="verbatim,attributes"]
+----
+compile 'org.apache.cayenne:cayenne-crypto:{version}'
+----
+
+==== Usage
+
+===== Setup your model and DB
+
+To use crypto module you must prepare your database to allow `byte[]` storage and properly name columns that will contain encrypted values.
+
+Currently supported SQL types that can be used to store encrypted data are:
+
+. Binary types: `BINARY, BLOB, VARBINARY, LONGVARBINARY`. These types are preferred.
+
+. Character types, that will store `base64` encoded value: `CHAR, NCHAR, CLOB, NCLOB, LONGVARCHAR, LONGNVARCHAR, VARCHAR, NVARCHAR`.
+
+====== Note
+
+Not all data types may be supported by your database.
+
+Default naming strategy that doesn't require additional setup suggests using "CRYPTO_" prefix. You can change this default strategy by injecting you own implementation of `org.apache.cayenne.crypto.map.ColumnMapper` interface.
+
+[source, java]
+----
+ServerRuntime.builder()
+ .addModule(CryptoModule.extend()
+ .columnMapper(MyColumnMapper.class)
+ .module())
+----
+
+Here is an example of how `ObjEntity` with two encrypted and two unencrypted properties can look like:
+
+image::../images/ext-crypto-obj-entity.png[align="left"]
+
+===== Setup keystore
+
+To perform encryption you must provide `KEYSTORE_URL` and `KEY_PASSWORD`. Currently crypto module supports only Java "jceks" KeyStore.
+
+[source, java]
+----
+ServerRuntime.builder()
+ .addModule(CryptoModule.extend()
+ .keyStore(this.getClass().getResource("keystore.jcek"), "my-password".toCharArray(), "my-key-alias")
+ .module())
+----
+
+===== Additional settings
+
+Additionally to `ColumnMapper` mentioned above you can customize other parts of `crypto module`. You can enable `gzip` compression and `HMAC` usage (later will ensure integrity of data).
+
+[source, java]
+----
+ServerRuntime.builder()
+ .addModule(CryptoModule.extend()
+ .compress()
+ .useHMAC()
+ .module())
+----
+
+Another useful extension point is support for custom Java value types. To add support for your data type you need to implement `org.apache.cayenne.crypto.transformer.value.BytesConverter` interface that will convert required type to and from `byte[]`.
+
+[source, java]
+----
+ServerRuntime.builder()
+ .addModule(CryptoModule.extend()
+ .objectToBytesConverter(MyClass.class, new MyClassBytesConverter())
+ .module())
+----
+
+NOTE: In addition to Java primitive types (and their object counterparts), `crypto module` supports encryption only of `java.util.Date, java.math.BigInteger` and `java.math.BigDecimal` types.
+
+
+
+
+
+
+
+
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/dbcpIntegration.adoc
----------------------------------------------------------------------
diff --git a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/dbcpIntegration.adoc b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/dbcpIntegration.adoc
new file mode 100644
index 0000000..3bf6182
--- /dev/null
+++ b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/dbcpIntegration.adoc
@@ -0,0 +1,47 @@
+// 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.
+
+include::../var.adoc[]
+
+=== Apache Commons DBCP integration
+
+==== Description
+
+This module enables usage of Apache Commons DBCP2 connection pool.
+
+==== Including in a project
+
+===== Maven
+
+[source, XML,subs="verbatim,attributes"]
+----
+<dependency>
+ <groupId>org.apache.cayenne</groupId>
+ <artifactId>cayenne-dbcp2</artifactId>
+ <version>{version}</version>
+</dependency>
+----
+
+===== Gradle
+
+[source, Groovy, subs="verbatim,attributes"]
+----
+compile 'org.apache.cayenne:cayenne-dbcp2:{version}'
+----
+
+==== Usage
+
+To use DBCP2 pool you need to setup it in DataNode settings in Cayenne Modeler:
+
+image::../images/ext-dbcp-setup.png[align="center"]
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/jCache.adoc
----------------------------------------------------------------------
diff --git a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/jCache.adoc b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/jCache.adoc
new file mode 100644
index 0000000..04c09d0
--- /dev/null
+++ b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/jCache.adoc
@@ -0,0 +1,51 @@
+// 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.
+
+include::../var.adoc[]
+
+=== JCache integration
+
+==== Description
+
+This module allows to integrate any JCache (JSR 107) compatible caching provider with Cayenne.
+
+==== Including in a project
+
+===== Maven
+
+[source, XML,subs="verbatim,attributes"]
+----
+<dependency>
+ <groupId>org.apache.cayenne</groupId>
+ <artifactId>cayenne-jcache</artifactId>
+ <version>{version}</version>
+</dependency>
+----
+
+===== Gradle
+
+[source, Groovy, subs="verbatim,attributes"]
+----
+compile 'org.apache.cayenne:cayenne-jcache:{version}'
+----
+
+==== Usage
+
+To use JCache provider in your app you need to include this module and caching provider libs (e.g. Ehcache). You can provide own implementation of `org.apache.cayenne.jcache.JCacheConfigurationFactory` to customize cache configuration if required.
+
+For advanced configuration and management please use provider specific options and tools.
+
+NOTE: You can read about using cache in Cayenne in xref:caching[this] chapter.
+
+You may else be interested in xref:cacheInvalidation[cache invalidation] extension.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/java8.adoc
----------------------------------------------------------------------
diff --git a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/java8.adoc b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/java8.adoc
new file mode 100644
index 0000000..be7e9a7
--- /dev/null
+++ b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/java8.adoc
@@ -0,0 +1,45 @@
+// 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.
+
+include::../var.adoc[]
+
+=== Java 8 extension
+
+==== Description
+
+Java 8 module allows to use `java.time.LocalTime, java.time.LocalDate` and `java.time.LocalDateTime` types for entity attributes
+
+==== Including in a project
+
+===== Maven
+
+[source, XML,subs="verbatim,attributes"]
+----
+<dependency>
+ <groupId>org.apache.cayenne</groupId>
+ <artifactId>cayenne-java8</artifactId>
+ <version>{version}</version>
+</dependency>
+----
+
+===== Gradle
+
+[source, Groovy, subs="verbatim,attributes"]
+----
+compile 'org.apache.cayenne:cayenne-java8:{version}'
+----
+
+==== Usage
+
+This module doesn't require any additional setup, you can just use new data types in your model.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/jodaTime.adoc
----------------------------------------------------------------------
diff --git a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/jodaTime.adoc b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/jodaTime.adoc
new file mode 100644
index 0000000..5510f77
--- /dev/null
+++ b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/jodaTime.adoc
@@ -0,0 +1,46 @@
+// 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.
+
+include::../var.adoc[]
+
+=== Joda time extension
+
+==== Description
+
+Joda time module allows to use `org.joda.time.LocalTime`, `org.joda.time.LocalDate`, `org.joda.time.LocalDateTime` and `org.joda.time.DateTime` types for entity attributes.
+
+==== Including in a project
+
+===== Maven
+
+[source, XML,subs="verbatim,attributes"]
+----
+<dependency>
+ <groupId>org.apache.cayenne</groupId>
+ <artifactId>cayenne-joda</artifactId>
+ <version>{version}</version>
+</dependency>
+----
+
+===== Gradle
+
+[source, Groovy, subs="verbatim,attributes"]
+----
+compile 'org.apache.cayenne:cayenne-joda:{version}'
+----
+
+==== Usage
+
+This module doesn't require any additional setup, you can just use new data types in your model.
+
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/serviceCollections.adoc
----------------------------------------------------------------------
diff --git a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/serviceCollections.adoc b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/serviceCollections.adoc
new file mode 100644
index 0000000..d234723
--- /dev/null
+++ b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/serviceCollections.adoc
@@ -0,0 +1,62 @@
+// 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.
+
+== Appendix B. Service Collections
+
+Note that the collection keys below are defined as constants in `org.apache.cayenne.configuration.Constants` interface.
+
+[#serviceCollections.table.table-bordered]
+.Service Collection Keys Present in ServerRuntime and/or ClientRuntime
+[cols="3,2,3"]
+|===
+|Collection Property |Type |Description
+
+.^|`cayenne.properties`
+.^|`Map<String,String>`
+.^|Properties used by built-in Cayenne services. The keys in this map are the property names from the table in Appendix A. Separate copies of this map exist on the server and ROP client.
+
+.^|`cayenne.server.adapter_detectors`
+.^|`List<DbAdapterDetector>`
+.^|Contains objects that can discover the type of current database and install the correct DbAdapter in runtime.
+
+.^|`cayenne.server.domain_filters`
+.^|`List<DataChannelFilter>`
+.^|Stores DataDomain filters.
+
+
+.^|`cayenne.server.project_locations`
+.^|`List<String>`
+.^|Stores locations of the one of more project configuration files.
+
+
+.^|`cayenne.server.default_types`
+.^|`List<ExtendedType>`
+.^|Stores default adapter-agnostic ExtendedTypes. Default ExtendedTypes can be overridden / extended by DB-specific DbAdapters as well as by user-provided types configured in another colltecion (see `"cayenne.server.user_types"`).
+
+
+.^|`cayenne.server.user_types`
+.^|`List<ExtendedType>`
+.^|Stores a user-provided ExtendedTypes. This collection will be merged into a full list of ExtendedTypes and would override any ExtendedTypes defined in a default list, or by a DbAdapter.
+
+
+.^|`cayenne.server.type_factories`
+.^|`List<ExtendedTypeFactory>`
+.^|Stores default and user-provided ExtendedTypeFactories. ExtendedTypeFactory allows to define ExtendedTypes dynamically for the whole group of Java classes. E.g. Cayenne supplies a factory to map all Enums regardless of their type.
+
+
+.^|`cayenne.server.rop_event_bridge_properties`
+.^|`Map<String, String>`
+.^|Stores event bridge properties passed to the ROP client on bootstrap. This means that the map is configured by server DI, and passed to the client via the wire. The properties in this map are specific to EventBridgeFactory implementation (e.g JMS or XMPP connection prameters). One common property is `"cayenne.server.rop_event_bridge_factory"` that defines the type of the factory.
+
+|===
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/var.adoc
----------------------------------------------------------------------
diff --git a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/var.adoc b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/var.adoc
new file mode 100644
index 0000000..e575eda
--- /dev/null
+++ b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/var.adoc
@@ -0,0 +1 @@
+:version: {project-version}
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/cayenne-guide.adoc
----------------------------------------------------------------------
diff --git a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/cayenne-guide.adoc b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/cayenne-guide.adoc
new file mode 100644
index 0000000..b058ec4
--- /dev/null
+++ b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/cayenne-guide.adoc
@@ -0,0 +1,56 @@
+// 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.
+= Cayenne Guide
+:revnumber: {project-major-version} ({project-version})
+// enable section numbering, limiting depth to 2
+:sectnums:
+:sectnumlevels: 2
+// use custom header
+:cayenne-header: _cayenne-guide/header.html
+:cayenne-header-position: body
+// customize final layout
+//:linkcss:
+// base path to java code include
+:cayenne-root: {basedir}/../../..
+
+[small]#Copyright © 2011-2017 Apache Software Foundation and individual authors#
+
+.License
+[small]#_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_#
+
+[small]#_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._#
+
+include::_cayenne-guide/part1.adoc[]
+
+include::_cayenne-guide/part2.adoc[]
+
+include::_cayenne-guide/part3.adoc[]
+
+include::_cayenne-guide/part4.adoc[]
+
+include::_cayenne-guide/part5.adoc[]
+
+include::_cayenne-guide/configurationProperties.adoc[]
+
+include::_cayenne-guide/serviceCollections.adoc[]
+
+include::_cayenne-guide/expressionsBNF.adoc[]
+
+include::_cayenne-guide/listOfTables.adoc[]
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/images/ext-crypto-obj-entity.png
----------------------------------------------------------------------
diff --git a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/images/ext-crypto-obj-entity.png b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/images/ext-crypto-obj-entity.png
new file mode 100644
index 0000000..2d8c32a
Binary files /dev/null and b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/images/ext-crypto-obj-entity.png differ
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/images/ext-dbcp-setup.png
----------------------------------------------------------------------
diff --git a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/images/ext-dbcp-setup.png b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/images/ext-dbcp-setup.png
new file mode 100644
index 0000000..f681b9d
Binary files /dev/null and b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/images/ext-dbcp-setup.png differ
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/images/re-modeler-datasource-select.png
----------------------------------------------------------------------
diff --git a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/images/re-modeler-datasource-select.png b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/images/re-modeler-datasource-select.png
new file mode 100644
index 0000000..79ada1c
Binary files /dev/null and b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/images/re-modeler-datasource-select.png differ
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/images/re-modeler-reverseengineering-dialog.png
----------------------------------------------------------------------
diff --git a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/images/re-modeler-reverseengineering-dialog.png b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/images/re-modeler-reverseengineering-dialog.png
new file mode 100644
index 0000000..8b09d07
Binary files /dev/null and b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/images/re-modeler-reverseengineering-dialog.png differ
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/images/remote-object-persistence.jpg
----------------------------------------------------------------------
diff --git a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/images/remote-object-persistence.jpg b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/images/remote-object-persistence.jpg
new file mode 100644
index 0000000..43f820d
Binary files /dev/null and b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/images/remote-object-persistence.jpg differ
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/asciidoc/getting-started-guide/pom.xml
----------------------------------------------------------------------
diff --git a/docs/asciidoc/getting-started-guide/pom.xml b/docs/asciidoc/getting-started-guide/pom.xml
new file mode 100644
index 0000000..6222c81
--- /dev/null
+++ b/docs/asciidoc/getting-started-guide/pom.xml
@@ -0,0 +1,170 @@
+<?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.
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~-->
+
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+ <parent>
+ <artifactId>cayenne-asciidoc-parent</artifactId>
+ <groupId>org.apache.cayenne.docs</groupId>
+ <version>4.0.B3-SNAPSHOT</version>
+ </parent>
+ <modelVersion>4.0.0</modelVersion>
+
+ <artifactId>getting-started-guide</artifactId>
+
+ <packaging>jar</packaging>
+ <name>getting-started-guide: AsciiDoc - Getting Started with Cayenne</name>
+
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.asciidoctor</groupId>
+ <artifactId>asciidoctor-maven-plugin</artifactId>
+ <dependencies>
+ <dependency>
+ <groupId>org.apache.cayenne.docs</groupId>
+ <artifactId>cayenne-asciidoc-extension</artifactId>
+ <version>${project.version}</version>
+ </dependency>
+ </dependencies>
+
+ <executions>
+ <!-- generate "embeddable" html content with front matter and without header/footer/styles -->
+ <execution>
+ <id>asciidoctor-html-web</id>
+ <phase>generate-resources</phase>
+ <goals>
+ <goal>process-asciidoc</goal>
+ </goals>
+ <configuration>
+ <backend>html5</backend>
+ <headerFooter>false</headerFooter> <!-- do not generate header and footer -->
+ <outputDirectory>${project.build.directory}/tmp/</outputDirectory>
+ <extensions>
+ <extension>
+ <className>org.apache.cayenne.asciidoc.CayennePostProcessor</className>
+ </extension>
+ </extensions>
+ <attributes>
+ <toc>auto</toc>
+ </attributes>
+ </configuration>
+ </execution>
+ </executions>
+ </plugin>
+
+ <!-- Move images to proper path for site -->
+ <plugin>
+ <artifactId>maven-resources-plugin</artifactId>
+ <executions>
+ <execution>
+ <id>copy docs for site</id>
+ <phase>install</phase>
+ <goals>
+ <goal>copy-resources</goal>
+ </goals>
+
+ <configuration>
+ <outputDirectory>${project.build.directory}/site/</outputDirectory>
+ <resources>
+ <resource>
+ <directory>${project.build.directory}/tmp/</directory>
+ <includes>
+ <include>${project.artifactId}.html</include>
+ <include>${project.artifactId}.toc.html</include>
+ </includes>
+ </resource>
+ </resources>
+ </configuration>
+ </execution>
+
+ <execution>
+ <id>copy images for site</id>
+ <phase>install</phase>
+ <goals>
+ <goal>copy-resources</goal>
+ </goals>
+
+ <configuration>
+ <outputDirectory>${project.build.directory}/site/${project.artifactId}/images/</outputDirectory>
+ <resources>
+ <resource>
+ <directory>${project.build.directory}/tmp/images/</directory>
+ <filtering>true</filtering>
+ </resource>
+ </resources>
+ </configuration>
+ </execution>
+ </executions>
+ </plugin>
+ </plugins>
+ </build>
+
+ <profiles>
+ <profile>
+ <id>assembly</id>
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.asciidoctor</groupId>
+ <artifactId>asciidoctor-maven-plugin</artifactId>
+ <executions>
+ <!-- generate standalone html help -->
+ <execution>
+ <id>asciidoctor-html-standalone</id>
+ <phase>generate-resources</phase>
+ <goals>
+ <goal>process-asciidoc</goal>
+ </goals>
+ <configuration>
+ <backend>html5</backend>
+ <sourceHighlighter>coderay</sourceHighlighter>
+ <embedAssets>true</embedAssets>
+ <attributes>
+ <toc>left</toc>
+ </attributes>
+ </configuration>
+ </execution>
+
+ <!-- generate PDF -->
+ <execution>
+ <id>generate-pdf-doc</id>
+ <phase>generate-resources</phase>
+ <goals>
+ <goal>process-asciidoc</goal>
+ </goals>
+ <configuration>
+ <backend>pdf</backend>
+ <sourceHighlighter>coderay</sourceHighlighter>
+ <attributes>
+ <pagenums/>
+ <toc/>
+ </attributes>
+ </configuration>
+ </execution>
+ </executions>
+ </plugin>
+ </plugins>
+ </build>
+ </profile>
+ </profiles>
+
+</project>
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/_getting-started-guide/delete.adoc
----------------------------------------------------------------------
diff --git a/docs/asciidoc/getting-started-guide/src/docs/asciidoc/_getting-started-guide/delete.adoc b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/_getting-started-guide/delete.adoc
new file mode 100644
index 0000000..533c933
--- /dev/null
+++ b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/_getting-started-guide/delete.adoc
@@ -0,0 +1,72 @@
+// 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.
+=== Deleting Objects
+This chapter explains how to model relationship delete rules and how to delete individual
+objects as well as sets of objects. Also demonstrated the use of Cayenne class to run a
+query.
+
+==== Setting Up Delete Rules
+Before we discuss the API for object deletion, lets go back to CayenneModeler and set
+up some delete rules. Doing this is optional but will simplify correct handling of the
+objects related to deleted objects.
+In the Modeler go to "Artist" ObjEntity, "Relationships" tab and select "Cascade" for
+the "paintings" relationship delete rule:
+
+image::modeler-deleterule.png[]
+
+Repeat this step for other relationships:
+
+- For Gallery set "paintings" relationship to be "Nullify", as a painting can exist without being displayed in a gallery.
+- For Painting set both relationships rules to "Nullify".
+
+Now save the mapping.
+
+==== Deleting Objects
+While deleting objects is possible via SQL, qualifying a delete on one or more IDs, a
+more common way in Cayenne (or ORM in general) is to get a hold of the object first, and
+then delete it via the context. Let's use utility class Cayenne to find an
+artist:
+
+[source, java]
+----
+Artist picasso = ObjectSelect.query(Artist.class)
+ .where(Artist.NAME.eq("Pablo Picasso")).selectOne(context);
+----
+
+Now let's delete the artist:
+
+[source, java]
+----
+if (picasso != null) {
+ context.deleteObject(picasso);
+ context.commitChanges();
+}
+----
+Since we set up "Cascade" delete rule for the Artist.paintings relationships, Cayenne
+will automatically delete all paintings of this artist. So when your run the app you'll
+see this output:
+
+ INFO: SELECT t0.DATE_OF_BIRTH, t0.NAME, t0.ID FROM ARTIST t0
+ WHERE t0.NAME = ? [bind: 1->NAME:'Pablo Picasso'] - prepared in 6 ms.
+ INFO: === returned 1 row. - took 18 ms.
+ INFO: +++ transaction committed.
+ INFO: --- transaction started.
+ INFO: DELETE FROM PAINTING WHERE ID = ?
+ INFO: [batch bind: 1->ID:200]
+ INFO: [batch bind: 1->ID:201]
+ INFO: === updated 2 rows.
+ INFO: DELETE FROM ARTIST WHERE ID = ?
+ INFO: [batch bind: 1->ID:200]
+ INFO: === updated 1 row.
+ INFO: +++ transaction committed.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/_getting-started-guide/header.html
----------------------------------------------------------------------
diff --git a/docs/asciidoc/getting-started-guide/src/docs/asciidoc/_getting-started-guide/header.html b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/_getting-started-guide/header.html
new file mode 100644
index 0000000..12c8b12
--- /dev/null
+++ b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/_getting-started-guide/header.html
@@ -0,0 +1,29 @@
+---
+# 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.
+
+title: "Cayenne Getting Started Guide"
+description: "Tutorial how to quick start new Cayenne project"
+weight: 20
+docsMenuTitle: "Getting Started"
+cayenneVersion: "4.0"
+menu:
+ footer:
+ weight: 5
+ parent: docs
+ name: "Getting Started (4.0)"
+---
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/_getting-started-guide/java-classes.adoc
----------------------------------------------------------------------
diff --git a/docs/asciidoc/getting-started-guide/src/docs/asciidoc/_getting-started-guide/java-classes.adoc b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/_getting-started-guide/java-classes.adoc
new file mode 100644
index 0000000..02babea
--- /dev/null
+++ b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/_getting-started-guide/java-classes.adoc
@@ -0,0 +1,113 @@
+// 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.
+
+include::../var.adoc[]
+
+=== Creating Java Classes
+Here we'll generate the Java classes from the model that was created in the previous
+section. CayenneModeler can be used to also generate the database schema, but since we
+specified "`CreateIfNoSchemaStrategy`" earlier when we created a DataNode, we'll skip the
+database schema step. Still be aware that you can do it if you need to via "Tools >
+Create Database Schema".
+
+==== Creating Java Classes
+- Select "Tools > Generate Classes" menu.
+- For "Type" select "Standard Persistent Objects", if it is not already selected.
+- For the "Output Directory" select "`src/main/java`" folder under your IDEA
+project folder (this is a "peer" location to the `cayenne-*.xml` location we
+selected before).
+- Click on "Classes" tab and check the "Check All Classes" checkbox
+(unless it is already checked and reads "Uncheck all Classes").
+- Click "Generate"
+
+Now go back to IDEA - you
+should see pairs of classes generated for each mapped entity. You probably also see that
+there's a bunch of red squiggles next to the newly generated Java classes in IDEA.
+This is because our project does not include Cayenne as a Maven dependency yet. Let's
+fix it now by adding "cayenne-server" and "cayenne-java8" artifacts in the bottom of the `pom.xml` file.
+Also we should tell Maven compile plugin that our project needs Java 8.
+The resulting POM should look like this:
+
+[source,xml,subs="verbatim,attributes"]
+----
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
+ <modelVersion>4.0.0</modelVersion>
+ <groupId>org.example.cayenne</groupId>
+ <artifactId>tutorial</artifactId>
+ <version>0.0.1-SNAPSHOT</version><!--1-->
+
+ <dependencies>
+ <dependency>
+ <groupId>org.apache.cayenne</groupId>
+ <artifactId>cayenne-server</artifactId>
+ <!-- Here specify the version of Cayenne you are actually using -->
+ <version>{version}</version>
+ </dependency>
+ <!-- For java.time.* types you need to use this dependency-->
+ <dependency>
+ <groupId>org.apache.cayenne</groupId>
+ <artifactId>cayenne-java8</artifactId>
+ <version>{version}</version>
+ </dependency>
+ <dependency>
+ <groupId>org.slf4j</groupId>
+ <artifactId>slf4j-simple</artifactId>
+ <version>1.7.25</version>
+ </dependency>
+ </dependencies>
+
+ <build>
+ <plugins>
+ <!-- Tell maven to support Java 8 -->
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-compiler-plugin</artifactId>
+ <version>3.6.1</version>
+ <configuration>
+ <source>1.8</source>
+ <target>1.8</target>
+ </configuration>
+ </plugin>
+ </plugins>
+ </build>
+</project>
+----
+<1> Here you can specify the version of Cayenne you are actually using
+
+Your computer must be connected to the internet. Once you edit the `pom.xml`, IDEA
+will download the needed Cayenne jar file and add it to the project build path. As a
+result, all the errors should disappear. In tutorial for console output we use slf4j-simple logger
+implementation. Due to use SLF4J logger in Apache Cayenne, you can use your custom logger (e.g. log4j
+or commons-logging) through bridges.
+
+image::idea-generated-classes.png[align="center"]
+
+Now let's check the entity class pairs. Each one is made of a superclass (e.g. `\_Artist`)
+and a subclass (e.g. `Artist`). You *should not* modify the
+superclasses whose names start with "_" (underscore), as they will be replaced on
+subsequent generator runs. Instead all custom logic should be placed in the subclasses
+in `org.example.cayenne.persistent` package - those will never be overwritten by the
+class generator.
+
+[TIP]
+.Class Generation Hint
+====
+Often you'd start by generating classes from the
+Modeler, but at the later stages of the project the generation is usually
+automated either via Ant cgen task or Maven cgen mojo. All three methods are
+interchangeable, however Ant and Maven methods would ensure that you never
+forget to regenerate classes on mapping changes, as they are integrated into
+the build cycle.
+====
http://git-wip-us.apache.org/repos/asf/cayenne/blob/cde78f0b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/_getting-started-guide/object-context.adoc
----------------------------------------------------------------------
diff --git a/docs/asciidoc/getting-started-guide/src/docs/asciidoc/_getting-started-guide/object-context.adoc b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/_getting-started-guide/object-context.adoc
new file mode 100644
index 0000000..0d02b18
--- /dev/null
+++ b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/_getting-started-guide/object-context.adoc
@@ -0,0 +1,89 @@
+// 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.
+=== Getting started with ObjectContext
+In this section we'll write a simple main class to run our application, and get a brief
+introduction to Cayenne ObjectContext.
+
+==== Creating the Main Class
+
+- In IDEA create a new class called "`Main`" in the "`org.example.cayenne`" package.
+- Create a standard "main" method to make it a runnable class:
+
+[source,java]
+----
+package org.example.cayenne;
+
+public class Main {
+
+ public static void main(String[] args) {
+ }
+}
+----
+- The first thing you need to be able to access the database is to create a
+`ServerRuntime` object (which is essentially a wrapper around Cayenne stack) and
+use it to obtain an instance of an
+`ObjectContext`.
+
+[source,java]
+----
+package org.example.cayenne;
+
+import org.apache.cayenne.ObjectContext;
+import org.apache.cayenne.configuration.server.ServerRuntime;
+
+public class Main {
+
+ public static void main(String[] args) {
+ ServerRuntime cayenneRuntime = ServerRuntime.builder()
+ .addConfig("cayenne-project.xml")
+ .build();
+ ObjectContext context = cayenneRuntime.newContext();
+ }
+}
+----
+`ObjectContext` is an isolated "session" in Cayenne that provides all needed API
+to work with data. ObjectContext has methods to execute queries and manage
+persistent objects. We'll discuss them in the following sections. When the first
+ObjectContext is created in the application, Cayenne loads XML mapping files and
+creates a shared access stack that is later reused by other ObjectContexts.
+
+==== Running Application
+Let's check what happens when you run the application. But before we do that we need
+to add another dependency to the `pom.xml` - Apache Derby, our embedded database engine.
+The following piece of XML needs to be added to the
+`<dependencies>...</dependencies>` section, where we already have Cayenne
+jars:
+[source,xml]
+----
+<dependency>
+ <groupId>org.apache.derby</groupId>
+ <artifactId>derby</artifactId>
+ <version>10.13.1.1</version>
+</dependency>
+----
+Now we are ready to run. Right click the "Main" class in IDEA and select "Run 'Main.main()'".
+
+image::idea-file-run-menu.png[align="center"]
+
+In the console you'll see output similar to this, indicating that Cayenne stack has been started:
+
+ INFO: Loading XML configuration resource from file:/.../cayenne-project.xml
+ INFO: Loading XML DataMap resource from file:/.../datamap.map.xml
+ INFO: loading user name and password.
+ INFO: Connecting to 'jdbc:derby:memory:testdb;create=true' as 'null'
+ INFO: +++ Connecting: SUCCESS.
+ INFO: setting DataNode 'datanode' as default, used by all unlinked DataMaps</screen>
+
+==== How to Configure Cayenne Logging
+Follow the instructions in the logging chapter to tweak verbosity of the logging output.
\ No newline at end of file