cayenne-commits mailing list archives

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


Mime
View raw message