cayenne-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ntimof...@apache.org
Subject [11/14] cayenne git commit: Switch documentation from Docbook to Asciidoctor format
Date Thu, 04 Jan 2018 16:01:25 GMT
http://git-wip-us.apache.org/repos/asf/cayenne/blob/df1324e4/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/df1324e4/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/df1324e4/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/df1324e4/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/df1324e4/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/df1324e4/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..7ca6eab
--- /dev/null
+++ b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part4/filtering.adoc
@@ -0,0 +1,367 @@
+// 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/df1324e4/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/df1324e4/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/df1324e4/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/df1324e4/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..2003dc5
--- /dev/null
+++ b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5.adoc
@@ -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.
+
+== Cayenne Additional Modules
+
+include::part5/cacheInvalidation.adoc[]
+
+include::part5/commitLog.adoc[]
+
+include::part5/crypto.adoc[]
+
+include::part5/jCache.adoc[]
+
+include::part5/jodaTime.adoc[]
+
+include::part5/projectCompatibility.adoc[]
+
+include::part5/apacheVelocity.adoc[]
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/cayenne/blob/df1324e4/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/apacheVelocity.adoc
----------------------------------------------------------------------
diff --git a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/apacheVelocity.adoc b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/apacheVelocity.adoc
new file mode 100644
index 0000000..f69d933
--- /dev/null
+++ b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/apacheVelocity.adoc
@@ -0,0 +1,70 @@
+// 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[]
+
+[[velocity]]
+=== Apache Velocity extension
+
+==== Description
+
+This module enables usage of full featured Apache Velocity templates in `org.apache.cayenne.query.SQLTemplate` queries.
+
+==== Including in a project
+
+===== Maven
+
+[source, XML,subs="verbatim,attributes"]
+----
+<dependency>
+    <groupId>org.apache.cayenne</groupId>
+    <artifactId>cayenne-velocity</artifactId>
+    <version>{version}</version>
+</dependency>
+----
+
+===== Gradle
+
+[source, Groovy, subs="verbatim,attributes"]
+----
+compile 'org.apache.cayenne:cayenne-velocity:{version}'
+----
+
+==== Usage
+
+This module doesn't require any additional setup.
+
+In addition of directives mentioned in xref:directives[this chapter], this module enables `#chain` and `#chunk` directives.
+
+`#chain` and `#chunk` directives are used for conditional inclusion of SQL code. They are used together with `#chain` wrapping multiple `#chunks`. 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.
+
+Semantics:
+
+[source]
+----
+#chain(operator) ... #end
+#chain(operator prefix) ... #end
+#chunk() ... #end
+#chunk(param) ... #end
+----
+
+Full example:
+
+[source]
+----
+#chain('OR' 'WHERE')
+    #chunk($name) NAME LIKE #bind($name) #end
+    #chunk($id) ARTIST_ID > #bind($id) #end
+#end"
+----

http://git-wip-us.apache.org/repos/asf/cayenne/blob/df1324e4/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..865a91b
--- /dev/null
+++ b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/cacheInvalidation.adoc
@@ -0,0 +1,96 @@
+// 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 `o.a.c.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/df1324e4/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..e70d8de
--- /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/df1324e4/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..a0d5d98
--- /dev/null
+++ b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/crypto.adoc
@@ -0,0 +1,119 @@
+// 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 `o.a.c.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 `o.a.c.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/df1324e4/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..a45e104
--- /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/df1324e4/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..d32c638
--- /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/df1324e4/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/projectCompatibility.adoc
----------------------------------------------------------------------
diff --git a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/projectCompatibility.adoc b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/projectCompatibility.adoc
new file mode 100644
index 0000000..ecafee5
--- /dev/null
+++ b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/projectCompatibility.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.
+
+include::../var.adoc[]
+
+=== Project compatibility extension
+
+==== Description
+
+Since version 4.1 Cayenne doesn't allow to load project XML files from previous versions as this can lead to unexpected errors in runtime. This module allows to use project files from older versions performing their upgrade on the fly (without modifying files). This can be useful when using Cayenne models from third-party libraries in your app.
+
+NOTE: You should prefer explicit project upgrade via Cayenne Modeler.
+
+==== Including in a project
+
+===== Maven
+
+[source, XML,subs="verbatim,attributes"]
+----
+<dependency>
+    <groupId>org.apache.cayenne</groupId>
+    <artifactId>cayenne-project-compatibility</artifactId>
+    <version>{version}</version>
+</dependency>
+----
+
+===== Gradle
+
+[source, Groovy,subs="verbatim,attributes"]
+----
+compile 'org.apache.cayenne:cayenne-project-compatibility:{version}'
+----
+
+==== Usage
+
+This module doesn't require any additional setup.
+

http://git-wip-us.apache.org/repos/asf/cayenne/blob/df1324e4/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/df1324e4/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/df1324e4/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..1d37f79
--- /dev/null
+++ b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/cayenne-guide.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.
+= 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[]
+

http://git-wip-us.apache.org/repos/asf/cayenne/blob/df1324e4/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/df1324e4/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/df1324e4/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/df1324e4/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/df1324e4/docs/asciidoc/getting-started-db-first/pom.xml
----------------------------------------------------------------------
diff --git a/docs/asciidoc/getting-started-db-first/pom.xml b/docs/asciidoc/getting-started-db-first/pom.xml
new file mode 100644
index 0000000..4102dab
--- /dev/null
+++ b/docs/asciidoc/getting-started-db-first/pom.xml
@@ -0,0 +1,172 @@
+<?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.1.M2-SNAPSHOT</version>
+    </parent>
+    <modelVersion>4.0.0</modelVersion>
+
+    <artifactId>getting-started-db-first</artifactId>
+
+    <packaging>jar</packaging>
+    <name>getting-started-db-first: AsciiDoc - Cayenne Database First tutorial</name>
+
+    <build>
+        <plugins>
+            <plugin>
+                <groupId>org.asciidoctor</groupId>
+                <artifactId>asciidoctor-maven-plugin</artifactId>
+                <dependencies>
+                    <!-- Using own extension to inject custom headers -->
+                    <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>
+                            <!-- this will inject header with "front-matter" markup -->
+                            <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/df1324e4/docs/asciidoc/getting-started-db-first/src/docs/asciidoc/_getting-started-db-first/header.html
----------------------------------------------------------------------
diff --git a/docs/asciidoc/getting-started-db-first/src/docs/asciidoc/_getting-started-db-first/header.html b/docs/asciidoc/getting-started-db-first/src/docs/asciidoc/_getting-started-db-first/header.html
new file mode 100644
index 0000000..843b641
--- /dev/null
+++ b/docs/asciidoc/getting-started-db-first/src/docs/asciidoc/_getting-started-db-first/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 Database First tutorial"
+description: "Tutorial how to quick start new Cayenne project from existing database"
+cayenneVersion: "4.1"
+docsMenuTitle: "Database First Tutorial"
+weight: 30
+menu:
+    footer:
+        weight: 30
+        parent: docs
+        name: "Database First tutorial (4.1)"
+---

http://git-wip-us.apache.org/repos/asf/cayenne/blob/df1324e4/docs/asciidoc/getting-started-db-first/src/docs/asciidoc/_getting-started-db-first/part1-maven-project.adoc
----------------------------------------------------------------------
diff --git a/docs/asciidoc/getting-started-db-first/src/docs/asciidoc/_getting-started-db-first/part1-maven-project.adoc b/docs/asciidoc/getting-started-db-first/src/docs/asciidoc/_getting-started-db-first/part1-maven-project.adoc
new file mode 100644
index 0000000..1dd7890
--- /dev/null
+++ b/docs/asciidoc/getting-started-db-first/src/docs/asciidoc/_getting-started-db-first/part1-maven-project.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.
+[[_getting_started_db_first_part1_maven_project]]
+=== Maven Project
+
+
+The goal of this chapter is to create a new Java project in IntelliJ IDEA and to setup Maven Cayenne plugin
+
+[[_new_maven_project]]
+==== Create a new Project in IntelliJ IDEA
+
+In IntelliJ IDEA select menu: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.
+
+[[_maven_plugin]]
+==== Plugin setup
+
+Next step is setting up Cayenne plugin in `pom.xml` file.
+For the convenience let's define Cayenne version that we will use across project file: 
+[source,xml,subs="verbatim,attributes"]
+----
+<properties>
+    <cayenne.version>{project-version}</cayenne.version>
+</properties>
+----
+
+Next step is to include plugin.
+Here is code snippet that enable `cayenne-maven-plugin` in our demo project: 
+[source,xml]
+----
+<build>
+    <plugins>
+        <plugin>
+            <groupId>org.apache.cayenne.plugins</groupId>
+            <artifactId>cayenne-maven-plugin</artifactId>
+            <version>${cayenne.version}</version>
+        </plugin>
+    </plugins>
+</build>
+----
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/cayenne/blob/df1324e4/docs/asciidoc/getting-started-db-first/src/docs/asciidoc/_getting-started-db-first/part1-setup.adoc
----------------------------------------------------------------------
diff --git a/docs/asciidoc/getting-started-db-first/src/docs/asciidoc/_getting-started-db-first/part1-setup.adoc b/docs/asciidoc/getting-started-db-first/src/docs/asciidoc/_getting-started-db-first/part1-setup.adoc
new file mode 100644
index 0000000..3c77b0c
--- /dev/null
+++ b/docs/asciidoc/getting-started-db-first/src/docs/asciidoc/_getting-started-db-first/part1-setup.adoc
@@ -0,0 +1,65 @@
+// 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_db_first_part1_prerequisites]]
+=== Prerequisites
+
+
+You can start with this tutorial, or you can do "Getting Started with Cayenne" first and then continue with this tutorial.
+
+This chapter lists the recommended software used in the tutorial.
+
+[[_install_java]]
+==== Java
+
+
+Cayenne 4.0 requires JDK 1.7 or newer.
+
+[[_install_idea]]
+==== IntelliJ IDEA IDE
+
+
+Download and install the free IntelliJ IDEA Community Edition IDE.
+This tutorial uses version 2017.1, but any recent IntelliJ IDEA version and edition will do. 
+
+[[_install_maven]]
+==== Maven
+
+
+Two Maven plugins are used:
+
+* *cayenne-maven-plugin* - among other things, allows to reverse-engineer the Cayenne model from the database and to update the model after the database has been changed.
+* *cayenne-modeler-maven-plugin* - provides a convenient way of starting the Cayenne Modeler
+
+
+[[_install_mysql]]
+==== MySQL
+
+
+MySQL database server is used for demonstrating Cayenne's ability to read the DB schema and to build/update the Cayenne model from it.
+
+You can create test database with any tools you comfortable with, here is full DB schema that will be used in this tutorial: 
+[source,sql]
+----
+CREATE SCHEMA IF NOT EXISTS cayenne_demo; USE cayenne_demo;
+CREATE TABLE ARTIST (DATE_OF_BIRTH DATE NULL, ID INT NOT NULL AUTO_INCREMENT, NAME VARCHAR(200) NULL, PRIMARY KEY (ID)) ENGINE=InnoDB;
+CREATE TABLE GALLERY (ID INT NOT NULL AUTO_INCREMENT, NAME VARCHAR(200) NULL, PRIMARY KEY (ID)) ENGINE=InnoDB;
+CREATE TABLE PAINTING (ARTIST_ID INT NULL, GALLERY_ID INT NULL, ID INT NOT NULL AUTO_INCREMENT, NAME VARCHAR(200) NULL, PRIMARY KEY (ID)) ENGINE=InnoDB;
+ALTER TABLE PAINTING ADD FOREIGN KEY (ARTIST_ID) REFERENCES ARTIST (ID) ON DELETE CASCADE;
+ALTER TABLE PAINTING ADD FOREIGN KEY (GALLERY_ID) REFERENCES GALLERY (ID) ON DELETE CASCADE;
+----
+
+You can save it to `cayenne_demo.sql` file and import to your database with following command: 
+----
+$ mysql < cayenne_demo.sql
+----
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/cayenne/blob/df1324e4/docs/asciidoc/getting-started-db-first/src/docs/asciidoc/_getting-started-db-first/part1.adoc
----------------------------------------------------------------------
diff --git a/docs/asciidoc/getting-started-db-first/src/docs/asciidoc/_getting-started-db-first/part1.adoc b/docs/asciidoc/getting-started-db-first/src/docs/asciidoc/_getting-started-db-first/part1.adoc
new file mode 100644
index 0000000..86dc7e1
--- /dev/null
+++ b/docs/asciidoc/getting-started-db-first/src/docs/asciidoc/_getting-started-db-first/part1.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.
+[[_getting_started_db_first_part1]]
+== Setup
+
+include::part1-setup.adoc[]
+include::part1-maven-project.adoc[]
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/cayenne/blob/df1324e4/docs/asciidoc/getting-started-db-first/src/docs/asciidoc/_getting-started-db-first/part2-project-setup.adoc
----------------------------------------------------------------------
diff --git a/docs/asciidoc/getting-started-db-first/src/docs/asciidoc/_getting-started-db-first/part2-project-setup.adoc b/docs/asciidoc/getting-started-db-first/src/docs/asciidoc/_getting-started-db-first/part2-project-setup.adoc
new file mode 100644
index 0000000..b906263
--- /dev/null
+++ b/docs/asciidoc/getting-started-db-first/src/docs/asciidoc/_getting-started-db-first/part2-project-setup.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.
+[[_getting_started_db_first_part2_project_setup]]
+=== Creating project
+
+
+Now we also need to create project file, currently this should be done manually via Cayenne Modeler. 
+
+==== Setup Modeler Maven plugin
+
+
+To launch Modeler we'll use ``cayenne-modeler-maven-plugin``.
+To use it just include it in `pom.xml` like we did with ``cayenne-maven-plugin``: 
+[source,xml]
+----
+<plugin>
+    <groupId>org.apache.cayenne.plugins</groupId>
+    <artifactId>cayenne-modeler-maven-plugin</artifactId>
+    <version>${cayenne.version}</version>
+</plugin>
+----
+
+To launch it simple use console: 
+----
+$ mvn cayenne-modeler:run
+----
+
+==== Create project
+
+
+In Modeler start new project and select `File` > ``Import DataMap``.
+In File Select dialog select created `datamap.map.xml` file and click ``Select DataMap``.
+Now all we need is to save project, click `Save` and select same folder where `datamap.map.xml` file is (it should be selected by default). That's all, you should see now `cayenne-project.xml` file in IDEA: 
+
+image:tutorial-cayenne-project.png[align="center"]
+
+To use newly created project in Modeler later let's configure plugin to open it automatically: 
+[source,xml]
+----
+<plugin>
+    ...
+    <configuration>
+        <modelFile>${project.basedir}/src/main/resources/cayenne-project.xml</modelFile>
+    </configuration>
+----
\ No newline at end of file


Mime
View raw message