cayenne-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ntimof...@apache.org
Subject [10/14] cayenne git commit: Switch documentation from Docbook to Asciidoctor format
Date Thu, 04 Jan 2018 16:01:24 GMT
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-rr-setup.adoc
----------------------------------------------------------------------
diff --git a/docs/asciidoc/getting-started-db-first/src/docs/asciidoc/_getting-started-db-first/part2-rr-setup.adoc b/docs/asciidoc/getting-started-db-first/src/docs/asciidoc/_getting-started-db-first/part2-rr-setup.adoc
new file mode 100644
index 0000000..2cc431f
--- /dev/null
+++ b/docs/asciidoc/getting-started-db-first/src/docs/asciidoc/_getting-started-db-first/part2-rr-setup.adoc
@@ -0,0 +1,115 @@
+// 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_rr_setup]]
+=== Reverse engineering database
+
+
+Now we have everything ready and can proceed to importing Cayenne model from our Mysql database
+
+==== Configuring plugin
+
+
+To let Cayenne plugin to its job we must tell it what to import and where it should get data.
+So let's begin, here is sample settings for the data source: 
+[source,xml]
+----
+<plugin>
+    ...
+    <configuration>
+        <dataSource>
+            <driver>com.mysql.jdbc.Driver</driver>
+            <url>jdbc:mysql://127.0.0.1:3306/cayenne_demo</url>
+            <username>root</username>
+            <password>your-mysql-password</password>
+        </dataSource>
+    </configuration>
+    <dependencies>
+        <dependency>
+            <groupId>mysql</groupId>
+            <artifactId>mysql-connector-java</artifactId>
+            <version>6.0.5</version>
+        </dependency>
+    </dependencies>
+----
+
+[NOTE]
+====
+Don't forget to set your actual MySQL login and password
+====
+
+We have told plugin where it should load data from, now let's set where it should store Cayenne model: 
+[source,xml]
+----
+<configuration>
+    ...
+    </dataSource>
+    <map>${project.basedir}/src/main/resources/datamap.map.xml</map>
+----
+
+And a last small step we need set default package where our model classes will be and catalog where our tables are: 
+[source,xml]
+----
+<configuration>
+    ...</map>
+    <dbImport>
+        <defaultPackage>org.apache.cayenne.tutorial.persistent</defaultPackage>
+        <catalog>cayenne_demo</catalog>
+    </dbImport>
+----
+
+==== Running plugin
+
+
+Finally we can run db import, it is as easy as just running this command in terminal: 
+----
+$ mvn cayenne:cdbimport
+----
+
+If everything was setup properly you should see output like this: 
+----
+...
+[INFO] +++ Connecting: SUCCESS.
+[INFO] Detected and installed adapter: org.apache.cayenne.dba.mysql.MySQLAdapter
+[INFO]   Table: cayenne_demo.ARTIST
+[INFO]   Table: cayenne_demo.GALLERY
+[INFO]   Table: cayenne_demo.PAINTING
+[INFO]     Db Relationship : toOne  (PAINTING.GALLERY_ID, GALLERY.ID)
+[INFO]     Db Relationship : toMany (GALLERY.ID, PAINTING.GALLERY_ID)
+[INFO]     Db Relationship : toOne  (PAINTING.ARTIST_ID, ARTIST.ID)
+[INFO]     Db Relationship : toMany (ARTIST.ID, PAINTING.ARTIST_ID)
+[INFO]
+[INFO] Map file does not exist. Loaded db model will be saved into '~/work/cayenne/db-first-tutorial/src/main/resources/datamap.map.xml'
+[INFO]
+[INFO] Detected changes:
+[INFO]     Create Table         ARTIST
+[INFO]     Create Table         PAINTING
+[INFO]     Create Table         GALLERY
+[INFO]
+[WARNING] Can't find ObjEntity for PAINTING
+[WARNING] Db Relationship (Db Relationship : toMany (ARTIST.ID, PAINTING.ARTIST_ID)) will have GUESSED Obj Relationship reflection.
+[WARNING] Can't find ObjEntity for GALLERY
+[WARNING] Db Relationship (Db Relationship : toOne  (PAINTING.GALLERY_ID, GALLERY.ID)) will have GUESSED Obj Relationship reflection.
+[INFO] Migration Complete Successfully.
+----
+
+You can open created `datamap.map.xml` file and check it's content in IDEA: 
+
+image:tutorial-new-datamap.png[align="center"]
+
+Great! We now have Cayenne DataMap file that describe model from our database.
+
+[NOTE]
+====
+If you have some problems with configuration you can always delete `datamap.map.xml` file and try again.
+====
\ 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.adoc
----------------------------------------------------------------------
diff --git a/docs/asciidoc/getting-started-db-first/src/docs/asciidoc/_getting-started-db-first/part2.adoc b/docs/asciidoc/getting-started-db-first/src/docs/asciidoc/_getting-started-db-first/part2.adoc
new file mode 100644
index 0000000..d38c852
--- /dev/null
+++ b/docs/asciidoc/getting-started-db-first/src/docs/asciidoc/_getting-started-db-first/part2.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_part2]]
+== Importing database
+
+include::part2-rr-setup.adoc[]
+include::part2-project-setup.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/part3-filtering.adoc
----------------------------------------------------------------------
diff --git a/docs/asciidoc/getting-started-db-first/src/docs/asciidoc/_getting-started-db-first/part3-filtering.adoc b/docs/asciidoc/getting-started-db-first/src/docs/asciidoc/_getting-started-db-first/part3-filtering.adoc
new file mode 100644
index 0000000..4bf714c
--- /dev/null
+++ b/docs/asciidoc/getting-started-db-first/src/docs/asciidoc/_getting-started-db-first/part3-filtering.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.
+[[_getting_started_db_first_part3_filtering]]
+=== Advanced filtering
+
+
+Final part of our tutorial is about fine-tuning what you load from DB into your model. 
+
+==== Update schema
+
+
+Let's add some information to our database, that we don't need in our model: 
+[source,sql]
+----
+CREATE TABLE cayenne_demo.LEGACY_PAINTING_INFO (ID INT NOT NULL AUTO_INCREMENT, INFO VARCHAR(255) NULL, PAINTING_ID INT NOT NULL, PRIMARY KEY (ID)) ENGINE=InnoDB;
+ALTER TABLE cayenne_demo.ARTIST ADD COLUMN __service_column INT;
+ALTER TABLE cayenne_demo.GALLERY ADD COLUMN __service_column INT;
+ALTER TABLE cayenne_demo.PAINTING ADD COLUMN __service_column INT;
+----
+
+==== Configure filtering
+
+
+Now we need to tell `cdbimport` what we don't need in our model, for that we'll just can add following into ``<configuration>``: 
+[source,xml]
+----
+<excludeTable>LEGACY_PAINTING_INFO</excludeTable>
+<excludeColumn>__service_column</excludeColumn>
+----
+
+After runing 
+----
+$ mvn cayenne:cdbimport
+----
+
+we still don't get any changes, exactly as expected: 
+----
+...
+[INFO] Detected changes: No changes to import.
+----
\ 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/part3-updating-model.adoc
----------------------------------------------------------------------
diff --git a/docs/asciidoc/getting-started-db-first/src/docs/asciidoc/_getting-started-db-first/part3-updating-model.adoc b/docs/asciidoc/getting-started-db-first/src/docs/asciidoc/_getting-started-db-first/part3-updating-model.adoc
new file mode 100644
index 0000000..2e6a18b
--- /dev/null
+++ b/docs/asciidoc/getting-started-db-first/src/docs/asciidoc/_getting-started-db-first/part3-updating-model.adoc
@@ -0,0 +1,94 @@
+// 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_part3_updating_model]]
+=== Updating model
+
+
+We now have everything we need, let's try some more features of plugin. 
+
+==== Update DDL
+
+
+To show next feature let's imagine that over some time our database schema has evolved and we need to synchronize it with our model, no problem we can simply run `cdbimport` again and all changes will be loaded to model.
+We use following SQL script to alter our demo database: 
+[source,sql]
+----
+CREATE TABLE cayenne_demo.PAINTING_INFO (INFO VARCHAR(255) NULL, PAINTING_ID INT NOT NULL, PRIMARY KEY (PAINTING_ID)) ENGINE=InnoDB;
+ALTER TABLE cayenne_demo.GALLERY ADD COLUMN FOUNDED_DATE DATE;
+ALTER TABLE cayenne_demo.PAINTING_INFO ADD FOREIGN KEY (PAINTING_ID) REFERENCES cayenne_demo.PAINTING (ID);
+----
+
+==== Run cdbimport
+
+
+Now we can simply run again 
+----
+$ mvn cayenne:cdbimport
+----
+
+You should see output similar to this: 
+----
+...
+[INFO]   Table: cayenne_demo.ARTIST
+[INFO]   Table: cayenne_demo.GALLERY
+[INFO]   Table: cayenne_demo.PAINTING
+[INFO]   Table: cayenne_demo.PAINTING_INFO
+[INFO]     Db Relationship : toOne  (PAINTING_INFO.PAINTING_ID, PAINTING.ID)
+[INFO]     Db Relationship : toOne  (PAINTING.ID, PAINTING_INFO.PAINTING_ID)
+[INFO]     Db Relationship : toOne  (PAINTING.GALLERY_ID, GALLERY.ID)
+[INFO]     Db Relationship : toMany (GALLERY.ID, PAINTING.GALLERY_ID)
+[INFO]     Db Relationship : toOne  (PAINTING.ARTIST_ID, ARTIST.ID)
+[INFO]     Db Relationship : toMany (ARTIST.ID, PAINTING.ARTIST_ID)
+[INFO]
+[INFO] Detected changes:
+[INFO]     Create Table         PAINTING_INFO
+[INFO]     Add Column           GALLERY.FOUNDED_DATE
+[INFO]     Add Relationship     paintingInfo PAINTING->PAINTING_INFO.PAINTING_ID
+[INFO]
+[INFO] Migration Complete Successfully.
+----
+
+Let's run Modeler and check that all changes are present in our model: 
+----
+$ mvn cayenne-modeler:run
+----
+
+image:tutorial-update-model.png[align="center"]
+
+Great! New table and ObjEntity are in place, as well as a new field.
+
+==== Customizing Model
+
+
+There is often a need to customize model to better fit it to your application requirements, such customization can be simple removal of toMany part of a relationship between two objects.
+Let's do it, in a Modeler just select and remove relationship `paintings` in Artist object: 
+
+image:tutorial-drop-relationship.png[align="center"]
+
+Now if you run 
+----
+$ mvn cayenne:cdbimport
+----
+
+it still find nothing to do: 
+----
+...
+[INFO] Detected changes: No changes to import.
+----
+
+[NOTE]
+====
+`cdbimport` will skip only modifications in Object layer (e.g.
+ObjEntities, ObjAttributes and ObjRelationships), if you modify Db layer your changes will be overridden by next run of ``cdbimport``. 
+====
\ 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/part3.adoc
----------------------------------------------------------------------
diff --git a/docs/asciidoc/getting-started-db-first/src/docs/asciidoc/_getting-started-db-first/part3.adoc b/docs/asciidoc/getting-started-db-first/src/docs/asciidoc/_getting-started-db-first/part3.adoc
new file mode 100644
index 0000000..3b50587
--- /dev/null
+++ b/docs/asciidoc/getting-started-db-first/src/docs/asciidoc/_getting-started-db-first/part3.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_part3]]
+== Advanced usage of cdbimport
+
+include::part3-updating-model.adoc[]
+include::part3-filtering.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/part4-java-classes.adoc
----------------------------------------------------------------------
diff --git a/docs/asciidoc/getting-started-db-first/src/docs/asciidoc/_getting-started-db-first/part4-java-classes.adoc b/docs/asciidoc/getting-started-db-first/src/docs/asciidoc/_getting-started-db-first/part4-java-classes.adoc
new file mode 100644
index 0000000..98d34be
--- /dev/null
+++ b/docs/asciidoc/getting-started-db-first/src/docs/asciidoc/_getting-started-db-first/part4-java-classes.adoc
@@ -0,0 +1,84 @@
+// 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_part4_java_classes]]
+=== Generating Java classes
+
+
+Now as we have our model ready let's generate Java code that actually will be used in application.
+In order to do that we'' use same maven plugin, but different goal, namely ``cgen``.
+It has many options to configure but default values will do for base case, so we can just call it: 
+----
+$ mvn cayenne:cgen
+----
+
+You should see output telling that everything is done, like this: 
+----
+[INFO] Generating superclass file: .../src/main/java/org/apache/cayenne/tutorial/persistent/auto/_Artist.java
+[INFO] Generating class file: .../src/main/java/org/apache/cayenne/tutorial/persistent/Artist.java
+[INFO] Generating superclass file: .../src/main/java/org/apache/cayenne/tutorial/persistent/auto/_Gallery.java
+[INFO] Generating class file: .../src/main/java/org/apache/cayenne/tutorial/persistent/Gallery.java
+[INFO] Generating superclass file: .../src/main/java/org/apache/cayenne/tutorial/persistent/auto/_Painting.java
+[INFO] Generating class file: .../src/main/java/org/apache/cayenne/tutorial/persistent/Painting.java
+[INFO] Generating superclass file: .../src/main/java/org/apache/cayenne/tutorial/persistent/auto/_PaintingInfo.java
+[INFO] Generating class file: .../src/main/java/org/apache/cayenne/tutorial/persistent/PaintingInfo.java
+[INFO] ------------------------------------------------------------------------
+[INFO] BUILD SUCCESS
+[INFO] ------------------------------------------------------------------------
+----
+
+In IDEA you should be able to see these newly generated classes:
+
+image:tutorial-java-classes.png[align="center"]
+
+Note that Cayenne code is unrecognized, that's because we need to include Cayenne as dependency, let's do this in `pom.xml` file: 
+[source,xml]
+----
+<project>
+    ...
+    <dependencies>
+        <dependency>
+            <groupId>org.apache.cayenne</groupId>
+            <artifactId>cayenne-server</artifactId>
+            <version>${cayenne.version}</version>
+        </dependency>
+        <dependency>
+            <groupId>org.apache.cayenne</groupId>
+            <artifactId>cayenne-java8</artifactId>
+            <version>${cayenne.version}</version>
+        </dependency>
+    </dependencies>
+----
+
+[NOTE]
+====
+`cayenne-java8` module required to support Java 8 date/time types.
+====
+
+Additionally we need to tell `Maven compiler plugin` that our code uses Java 8: 
+[source,xml]
+----
+<build>
+    <plugins>
+    ...
+        <plugin>
+            <artifactId>maven-compiler-plugin</artifactId>
+            <configuration>
+                <source>1.8</source>
+                <target>1.8</target>
+            </configuration>
+        </plugin>
+    ...
+----
+
+If all done right your code now shouldn't have any errors. 
\ 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/part4-java-code.adoc
----------------------------------------------------------------------
diff --git a/docs/asciidoc/getting-started-db-first/src/docs/asciidoc/_getting-started-db-first/part4-java-code.adoc b/docs/asciidoc/getting-started-db-first/src/docs/asciidoc/_getting-started-db-first/part4-java-code.adoc
new file mode 100644
index 0000000..4d768a3
--- /dev/null
+++ b/docs/asciidoc/getting-started-db-first/src/docs/asciidoc/_getting-started-db-first/part4-java-code.adoc
@@ -0,0 +1,115 @@
+// 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_part4_java_code]]
+=== 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_main_class]]
+==== Creating the Main Class
+
+* In IDEA create a new class called "``Main``" in the "``org.apache.cayenne.tutorial``" package.
+* Create a standard "main" method to make it a runnable class:
++
+[source,java]
+----
+package org.apache.cayenne.tutorial;
+
+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.apache.cayenne.tutorial;
+
+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()
+            .dataSource(DataSourceBuilder
+                    .url("jdbc:mysql://127.0.0.1:3306/cayenne_demo")
+                    .driver("com.mysql.cj.jdbc.Driver")
+                    .userName("root") // TODO: change to your actual username and password
+                    .password("your-password").build())
+            .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. 
+* Let's now add some code that will create persistent object: 
++
+[source,java]
+----
+Artist artist = context.newObject(Artist.class);
+artist.setName("Picasso");
+context.commitChanges();
+----
+
+
+[[_runnning_app]]
+==== Running Application
+
+
+Let's check what happens when you run the application.
+But before we do that we need to add another dependencies to the `pom.xml` - MySQL Jdbc driver and simple logger.
+The following piece of XML needs to be added to the `<dependencies>...</dependencies>` section, where we already have Cayenne jars:
+[source,xml]
+----
+<dependency>
+    <groupId>mysql</groupId>
+    <artifactId>mysql-connector-java</artifactId>
+    <version>6.0.5</version>
+</dependency>
+<dependency>
+    <groupId>org.slf4j</groupId>
+    <artifactId>slf4j-simple</artifactId>
+    <version>1.7.25</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: 
+----
+[main] INFO: Loading XML configuration resource from file:/.../cayenne-project.xml
+[main] INFO: Loading XML DataMap resource from file:/.../datamap.map.xml
+...
+[main] INFO org.apache.cayenne.datasource.DriverDataSource - +++ Connecting: SUCCESS.
+[main] INFO org.apache.cayenne.log.JdbcEventLogger - --- transaction started.
+[main] INFO org.apache.cayenne.log.JdbcEventLogger - INSERT INTO cayenne_demo.ARTIST (DATE_OF_BIRTH, NAME) VALUES (?, ?)
+[main] INFO org.apache.cayenne.log.JdbcEventLogger - [bind: 1->DATE_OF_BIRTH:NULL, 2->NAME:'Picasso']
+[main] INFO org.apache.cayenne.log.JdbcEventLogger - Generated PK: ARTIST.ID = 2
+[main] INFO org.apache.cayenne.log.JdbcEventLogger - === updated 1 row.
+[main] INFO org.apache.cayenne.log.JdbcEventLogger - +++ transaction committed.
+----
\ 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/part4.adoc
----------------------------------------------------------------------
diff --git a/docs/asciidoc/getting-started-db-first/src/docs/asciidoc/_getting-started-db-first/part4.adoc b/docs/asciidoc/getting-started-db-first/src/docs/asciidoc/_getting-started-db-first/part4.adoc
new file mode 100644
index 0000000..4f9c21a
--- /dev/null
+++ b/docs/asciidoc/getting-started-db-first/src/docs/asciidoc/_getting-started-db-first/part4.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_part4]]
+== Java code
+
+include::part4-java-classes.adoc[]
+include::part4-java-code.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/part5.adoc
----------------------------------------------------------------------
diff --git a/docs/asciidoc/getting-started-db-first/src/docs/asciidoc/_getting-started-db-first/part5.adoc b/docs/asciidoc/getting-started-db-first/src/docs/asciidoc/_getting-started-db-first/part5.adoc
new file mode 100644
index 0000000..412aeb9
--- /dev/null
+++ b/docs/asciidoc/getting-started-db-first/src/docs/asciidoc/_getting-started-db-first/part5.adoc
@@ -0,0 +1,22 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with
+// this work for additional information regarding copyright ownership.
+// The ASF licenses this file to you under the Apache License, Version
+// 2.0 (the "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0 Unless required by
+// applicable law or agreed to in writing, software distributed under the
+// License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+// CONDITIONS OF ANY KIND, either express or implied. See the License for
+// the specific language governing permissions and limitations under the
+// License.
+[[_getting_started_db_first_part5]]
+== What's next
+
+That's all for this tutorial! Now you know how to setup and use ``cayenne-maven-plugin``. 
+
+Next step will be creating your first application with Cayenne.
+If you not passed yet, you can try out http://cayenne.apache.org/docs/4.0/tutorial/index.html[getting-started] tutorial. 
+
+You can find detailed information about configuring this plugin in http://cayenne.apache.org/docs/4.0/cayenne-guide/including-cayenne-in-project.html#maven-projects[documentation] available on Cayenne site. 
\ 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.adoc
----------------------------------------------------------------------
diff --git a/docs/asciidoc/getting-started-db-first/src/docs/asciidoc/getting-started-db-first.adoc b/docs/asciidoc/getting-started-db-first/src/docs/asciidoc/getting-started-db-first.adoc
new file mode 100644
index 0000000..6fa9b46
--- /dev/null
+++ b/docs/asciidoc/getting-started-db-first/src/docs/asciidoc/getting-started-db-first.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.
+= Cayenne Database First tutorial
+:revnumber: {project-major-version} ({project-version})
+:experimental:
+// enable section numbering, limiting depth to 2
+:sectnums:
+:sectnumlevels: 2
+// use custom header
+:cayenne-header: _getting-started-db-first/header.html
+:cayenne-header-position: body
+// base path to java code include
+:cayenne-root: {basedir}/../../..
+:java-include-dir: {cayenne-root}/tutorials/tutorial/src/main/java/org/apache/cayenne/tutorial
+:web-include-dir: {cayenne-root}/tutorials/tutorial/src/main/java/org/apache/cayenne/tutorial
+
+[small]#Copyright © 2011-2017 Apache Software Foundation and individual authors#
+
+.License
+[small]#_Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements.
+See the NOTICE file distributed with this work for additional information regarding copyright ownership.
+The ASF licenses this file to you under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License. You may obtain
+a copy of the License at http://www.apache.org/licenses/LICENSE-2.0_#
+
+[small]#_Unless required by applicable law or agreed to in writing, software distributed under the License
+is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and limitations under the License._#
+
+include::_getting-started-db-first/part1.adoc[]
+include::_getting-started-db-first/part2.adoc[]
+include::_getting-started-db-first/part3.adoc[]
+include::_getting-started-db-first/part4.adoc[]
+include::_getting-started-db-first/part5.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/images/idea-file-run-menu.png
----------------------------------------------------------------------
diff --git a/docs/asciidoc/getting-started-db-first/src/docs/asciidoc/images/idea-file-run-menu.png b/docs/asciidoc/getting-started-db-first/src/docs/asciidoc/images/idea-file-run-menu.png
new file mode 100644
index 0000000..30cf05e
Binary files /dev/null and b/docs/asciidoc/getting-started-db-first/src/docs/asciidoc/images/idea-file-run-menu.png differ

http://git-wip-us.apache.org/repos/asf/cayenne/blob/df1324e4/docs/asciidoc/getting-started-db-first/src/docs/asciidoc/images/tutorial-cayenne-project.png
----------------------------------------------------------------------
diff --git a/docs/asciidoc/getting-started-db-first/src/docs/asciidoc/images/tutorial-cayenne-project.png b/docs/asciidoc/getting-started-db-first/src/docs/asciidoc/images/tutorial-cayenne-project.png
new file mode 100644
index 0000000..dc03d32
Binary files /dev/null and b/docs/asciidoc/getting-started-db-first/src/docs/asciidoc/images/tutorial-cayenne-project.png differ

http://git-wip-us.apache.org/repos/asf/cayenne/blob/df1324e4/docs/asciidoc/getting-started-db-first/src/docs/asciidoc/images/tutorial-drop-relationship.png
----------------------------------------------------------------------
diff --git a/docs/asciidoc/getting-started-db-first/src/docs/asciidoc/images/tutorial-drop-relationship.png b/docs/asciidoc/getting-started-db-first/src/docs/asciidoc/images/tutorial-drop-relationship.png
new file mode 100644
index 0000000..d4a8971
Binary files /dev/null and b/docs/asciidoc/getting-started-db-first/src/docs/asciidoc/images/tutorial-drop-relationship.png differ

http://git-wip-us.apache.org/repos/asf/cayenne/blob/df1324e4/docs/asciidoc/getting-started-db-first/src/docs/asciidoc/images/tutorial-idea-project.png
----------------------------------------------------------------------
diff --git a/docs/asciidoc/getting-started-db-first/src/docs/asciidoc/images/tutorial-idea-project.png b/docs/asciidoc/getting-started-db-first/src/docs/asciidoc/images/tutorial-idea-project.png
new file mode 100644
index 0000000..3fa072f
Binary files /dev/null and b/docs/asciidoc/getting-started-db-first/src/docs/asciidoc/images/tutorial-idea-project.png differ

http://git-wip-us.apache.org/repos/asf/cayenne/blob/df1324e4/docs/asciidoc/getting-started-db-first/src/docs/asciidoc/images/tutorial-java-classes.png
----------------------------------------------------------------------
diff --git a/docs/asciidoc/getting-started-db-first/src/docs/asciidoc/images/tutorial-java-classes.png b/docs/asciidoc/getting-started-db-first/src/docs/asciidoc/images/tutorial-java-classes.png
new file mode 100644
index 0000000..500e93c
Binary files /dev/null and b/docs/asciidoc/getting-started-db-first/src/docs/asciidoc/images/tutorial-java-classes.png differ

http://git-wip-us.apache.org/repos/asf/cayenne/blob/df1324e4/docs/asciidoc/getting-started-db-first/src/docs/asciidoc/images/tutorial-new-datamap.png
----------------------------------------------------------------------
diff --git a/docs/asciidoc/getting-started-db-first/src/docs/asciidoc/images/tutorial-new-datamap.png b/docs/asciidoc/getting-started-db-first/src/docs/asciidoc/images/tutorial-new-datamap.png
new file mode 100644
index 0000000..e152a02
Binary files /dev/null and b/docs/asciidoc/getting-started-db-first/src/docs/asciidoc/images/tutorial-new-datamap.png differ

http://git-wip-us.apache.org/repos/asf/cayenne/blob/df1324e4/docs/asciidoc/getting-started-db-first/src/docs/asciidoc/images/tutorial-update-model.png
----------------------------------------------------------------------
diff --git a/docs/asciidoc/getting-started-db-first/src/docs/asciidoc/images/tutorial-update-model.png b/docs/asciidoc/getting-started-db-first/src/docs/asciidoc/images/tutorial-update-model.png
new file mode 100644
index 0000000..9c14b1e
Binary files /dev/null and b/docs/asciidoc/getting-started-db-first/src/docs/asciidoc/images/tutorial-update-model.png differ

http://git-wip-us.apache.org/repos/asf/cayenne/blob/df1324e4/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..b4f1f3b
--- /dev/null
+++ b/docs/asciidoc/getting-started-guide/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-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>
+                    <!-- 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-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/df1324e4/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..9a63df5
--- /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.1"
+menu:
+    footer:
+        weight: 10
+        parent: docs
+        name: "Getting Started (4.1)"
+---

http://git-wip-us.apache.org/repos/asf/cayenne/blob/df1324e4/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..456c7c5
--- /dev/null
+++ b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/_getting-started-guide/java-classes.adoc
@@ -0,0 +1,110 @@
+//    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.
+=== 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>
+    <cayenne.version>{project-version}</version> <!--1-->
+
+    <dependencies>
+        <dependency>
+            <groupId>org.apache.cayenne</groupId>
+            <artifactId>cayenne-server</artifactId>
+            <version>${cayenne.version}</version>
+        </dependency>
+        <!--  For java.time.* types you need to use this dependency-->
+        <dependency>
+            <groupId>org.apache.cayenne</groupId>
+            <artifactId>cayenne-java8</artifactId>
+            <version>${cayenne.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/df1324e4/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

http://git-wip-us.apache.org/repos/asf/cayenne/blob/df1324e4/docs/asciidoc/getting-started-guide/src/docs/asciidoc/_getting-started-guide/object-relational-mapping.adoc
----------------------------------------------------------------------
diff --git a/docs/asciidoc/getting-started-guide/src/docs/asciidoc/_getting-started-guide/object-relational-mapping.adoc b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/_getting-started-guide/object-relational-mapping.adoc
new file mode 100644
index 0000000..89a5260
--- /dev/null
+++ b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/_getting-started-guide/object-relational-mapping.adoc
@@ -0,0 +1,109 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with
+// this work for additional information regarding copyright ownership.
+// The ASF licenses this file to you under the Apache License, Version
+// 2.0 (the "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0 Unless required by
+// applicable law or agreed to in writing, software distributed under the
+// License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+// CONDITIONS OF ANY KIND, either express or implied. See the License for
+// the specific language governing permissions and limitations under the
+// License.
+=== Getting started with Object Relational Mapping (ORM)
+The goal of this section is to learn how to create a simple Object-Relational model with
+CayenneModeler. We will create a complete ORM model for the following database
+schema:
+
+image::cayenne-tutorial-model.png[align="center"]
+
+NOTE: Very often you'd have an existing database already, and
+    it can be quickly imported in Cayenne via "Tools &gt; Reengineer Database
+    Schema". This will save you lots of time compared to manual mapping. However
+    understanding how to create the mapping by hand is important, so we are showing
+    the "manual" approach below.
+
+==== Mapping Database Tables and Columns
+Lets go back to CayenneModeler where we have the newly created project open and start
+by adding the ARTIST table. Database tables are called *DbEntities*
+in Cayenne mapping (those can be actual tables or database views).
+
+Select "datamap" on the left-hand side project tree and click "Create DbEntity" button image:icon-dbentity.png[]
+(or use "Project &gt; Create DbEntity" menu). A new DbEntity is created. In "DbEntity
+Name" field enter "ARTIST". Then click on "Create Attribute" button image:icon-attribute.png[]
+on the entity toolbar. This action changes the view to the "Attribute"
+tab and adds a new attribute (attribute means a "table column" in this case) called
+"untitledAttr". Let's rename it to ID, make it an `INTEGER` and make it a PK:
+
+image::modeler-artistid.png[align="center"]
+
+Similarly add NAME `VARCHAR(200)` and DATE_OF_BIRTH `DATE` attributes. After that repeat
+this procedure for PAINTING and GALLERY entities to match DB schema shown above.
+
+==== Mapping Database Relationships
+
+Now we need to specify relationships between ARTIST, PAINTING and GALLERY tables.
+Start by creating a one-to-many ARTIST/PAINTING relationship:
+
+- Select the ARTIST DbEntity on the left and click on the "Properties" tab.
+
+- Click on "Create Relationship" button on the entity toolbar image:icon-relationship.png[] - a relationship
+called "untitledRel" is created.
+
+- Choose the "Target" to be "Painting".
+
+- Click on the "Database Mapping" button image:icon-edit.png[] - relationship
+configuration dialog is presented. Here you can assign a name to the
+relationship and also its complimentary reverse relationship. This name can be
+anything (this is really a symbolic name of the database referential
+constraint), but it is recommended to use a valid Java identifier, as this will
+save some typing later. We'll call the relationship "paintings" and reverse
+relationship "artist".
+
+- Click on "Add" button on the right to add a join
+
+- Select "ID" column for the "Source" and "ARTIST_ID" column for the target.
+
+- Relationship information should now look like this:
+
+image::modeler-dbrelationship.png[align="center"]
+
+- Click "Done" to confirm the changes and close the dialog.
+
+- Two complimentary relationships have been created - from ARTIST to PAINTING
+and back. Still you may have noticed one thing is missing - "paintings"
+relationship should be to-many, but "To Many" checkbox is not checked. Let's
+change that - check the checkbox for "paintings" relationship, and then click on
+PAINTING DbEntity, and uncheck "artist" relationship "To Many" to make the
+reverse relationship "to-one" as it should be.
+
+- Repeat the steps above to create a many-to-one relationship from PAINTING to GALLERY, calling the relationships pair
+"gallery" and "paintings".
+
+==== Mapping Java Classes
+
+Now that the database schema mapping is complete, CayenneModeler can create mappings
+of Java classes (aka "ObjEntities") by deriving everything from DbEntities. At present
+there is no way to do it for the entire DataMap in one click, so we'll do it for each
+table individually.
+
+- Select "ARTIST" DbEntity and click on "Create ObjEntity" button image:icon-new_objentity.png[]
+either on the entity toolbar or on the main toolbar. An ObjEntity called
+"Artist" is created with a Java class field set to
+`org.example.cayenne.persistent.Artist`. The modeler transformed the database
+names to the Java-friendly names (e.g., if you click on the "Attributes" tab,
+you'll see that "DATE_OF_BIRTH" column was converted to "dateOfBirth" Java class
+attribute).
+
+- Select "GALLERY" DbEntity and click on "Create ObjEntity" button again - you'll see a "Gallery" ObjEntity created.
+- Finally, do the same thing for "PAINTING".
+
+Now you need to synchronize relationships. Artist and Gallery entities were created
+when there was no related "Painting" entity, so their relationships were not set.
+
+- Click on the "Artist" ObjEntity. Now click on "Sync ObjEntity with DbEntity" button on
+the toolbar image:icon-sync.png[] - you will see the "paintings" relationship appear.
+- Do the same for the "Gallery" entity.
+
+Unless you want to customize the Java class and property names (which you can do easily) the mapping is complete.

http://git-wip-us.apache.org/repos/asf/cayenne/blob/df1324e4/docs/asciidoc/getting-started-guide/src/docs/asciidoc/_getting-started-guide/part2.adoc
----------------------------------------------------------------------
diff --git a/docs/asciidoc/getting-started-guide/src/docs/asciidoc/_getting-started-guide/part2.adoc b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/_getting-started-guide/part2.adoc
new file mode 100644
index 0000000..e12d0f0
--- /dev/null
+++ b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/_getting-started-guide/part2.adoc
@@ -0,0 +1,20 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with
+// this work for additional information regarding copyright ownership.
+// The ASF licenses this file to you under the Apache License, Version
+// 2.0 (the "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0 Unless required by
+// applicable law or agreed to in writing, software distributed under the
+// License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+// CONDITIONS OF ANY KIND, either express or implied. See the License for
+// the specific language governing permissions and limitations under the
+// License.
+== Learning mapping basics
+
+include::starting-project.adoc[]
+
+include::object-relational-mapping.adoc[]
+
+include::java-classes.adoc[]
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/cayenne/blob/df1324e4/docs/asciidoc/getting-started-guide/src/docs/asciidoc/_getting-started-guide/part3.adoc
----------------------------------------------------------------------
diff --git a/docs/asciidoc/getting-started-guide/src/docs/asciidoc/_getting-started-guide/part3.adoc b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/_getting-started-guide/part3.adoc
new file mode 100644
index 0000000..cd31060
--- /dev/null
+++ b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/_getting-started-guide/part3.adoc
@@ -0,0 +1,22 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with
+// this work for additional information regarding copyright ownership.
+// The ASF licenses this file to you under the Apache License, Version
+// 2.0 (the "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0 Unless required by
+// applicable law or agreed to in writing, software distributed under the
+// License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+// CONDITIONS OF ANY KIND, either express or implied. See the License for
+// the specific language governing permissions and limitations under the
+// License.
+== Learning Cayenne API
+
+include::object-context.adoc[]
+
+include::persistent-objects.adoc[]
+
+include::select-query.adoc[]
+
+include::delete.adoc[]

http://git-wip-us.apache.org/repos/asf/cayenne/blob/df1324e4/docs/asciidoc/getting-started-guide/src/docs/asciidoc/_getting-started-guide/persistent-objects.adoc
----------------------------------------------------------------------
diff --git a/docs/asciidoc/getting-started-guide/src/docs/asciidoc/_getting-started-guide/persistent-objects.adoc b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/_getting-started-guide/persistent-objects.adoc
new file mode 100644
index 0000000..16d4f2a
--- /dev/null
+++ b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/_getting-started-guide/persistent-objects.adoc
@@ -0,0 +1,111 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with
+// this work for additional information regarding copyright ownership.
+// The ASF licenses this file to you under the Apache License, Version
+// 2.0 (the "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0 Unless required by
+// applicable law or agreed to in writing, software distributed under the
+// License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+// CONDITIONS OF ANY KIND, either express or implied. See the License for
+// the specific language governing permissions and limitations under the
+// License.
+=== Getting started with persistent objects
+In this chapter we'll learn about persistent objects, how to customize them and how to
+create and save them in DB.
+
+==== Inspecting and Customizing Persistent Objects
+Persistent classes in Cayenne implement a DataObject interface. If you inspect any of
+the classes generated earlier in this tutorial (e.g.
+`org.example.cayenne.persistent.Artist`), you'll see that it extends a class with the name
+that starts with underscore (`org.example.cayenne.persistent.auto._Artist`), which in turn
+extends from `org.apache.cayenne.CayenneDataObject`. Splitting each persistent class into
+user-customizable subclass (`Xyz`) and a generated superclass (`_Xyz`) is a useful technique
+to avoid overwriting the custom code when refreshing classes from the mapping
+model.
+
+Let's for instance add a utility method to the Artist class that sets Artist date of
+birth, taking a string argument for the date. It will be preserved even if the model
+changes later:
+
+[source,java]
+----
+include::{java-include-dir}/persistent/Artist.java[tag=content]
+----
+
+==== Create New Objects
+Now we'll create a bunch of objects and save them to the database. An object is
+created and registered with `ObjectContext` using "`newObject`" method. Objects *must* be registered
+with `DataContext` to be persisted and to allow setting relationships with other objects.
+Add this code to the "main" method of the Main class:
+
+[source,java,indent=0]
+----
+include::{java-include-dir}/Main.java[tag=new-artist]
+----
+
+Note that at this point "picasso" object is only stored in memory and is not saved in
+the database. Let's continue by adding a Metropolitan Museum "`Gallery`" object and a few
+Picasso "Paintings":
+
+[source,java,indent=0]
+----
+include::{java-include-dir}/Main.java[tag=new-painting]
+----
+
+Now we can link the objects together, establishing relationships. Note that in each
+case below relationships are automatically established in both directions (e.g.
+`picasso.addToPaintings(girl)` has exactly the same effect as
+`girl.setToArtist(picasso)`).
+
+[source, java, indent=0]
+----
+include::{java-include-dir}/Main.java[tag=link-objects]
+----
+
+Now lets save all five new objects, in a single method call:
+
+[source, java, indent=0]
+----
+include::{java-include-dir}/Main.java[tag=commit]
+----
+
+Now you can run the application again as described in the previous chapter. The new
+output will show a few actual DB operations:
+
+    ...
+    INFO: --- transaction started.
+    INFO: No schema detected, will create mapped tables
+    INFO: CREATE TABLE GALLERY (ID INTEGER NOT NULL, NAME VARCHAR (200), PRIMARY KEY (ID))
+    INFO: CREATE TABLE ARTIST (DATE_OF_BIRTH DATE, ID INTEGER NOT NULL, NAME VARCHAR (200), PRIMARY KEY (ID))
+    INFO: CREATE TABLE PAINTING (ARTIST_ID INTEGER, GALLERY_ID INTEGER, ID INTEGER NOT NULL,
+          NAME VARCHAR (200), PRIMARY KEY (ID))
+    INFO: ALTER TABLE PAINTING ADD FOREIGN KEY (ARTIST_ID) REFERENCES ARTIST (ID)
+    INFO: ALTER TABLE PAINTING ADD FOREIGN KEY (GALLERY_ID) REFERENCES GALLERY (ID)
+    INFO: CREATE TABLE AUTO_PK_SUPPORT (
+          TABLE_NAME CHAR(100) NOT NULL,  NEXT_ID BIGINT NOT NULL,  PRIMARY KEY(TABLE_NAME))
+    INFO: DELETE FROM AUTO_PK_SUPPORT WHERE TABLE_NAME IN ('ARTIST', 'GALLERY', 'PAINTING')
+    INFO: INSERT INTO AUTO_PK_SUPPORT (TABLE_NAME, NEXT_ID) VALUES ('ARTIST', 200)
+    INFO: INSERT INTO AUTO_PK_SUPPORT (TABLE_NAME, NEXT_ID) VALUES ('GALLERY', 200)
+    INFO: INSERT INTO AUTO_PK_SUPPORT (TABLE_NAME, NEXT_ID) VALUES ('PAINTING', 200)
+    INFO: SELECT NEXT_ID FROM AUTO_PK_SUPPORT WHERE TABLE_NAME = ? FOR UPDATE [bind: 1:'ARTIST']
+    INFO: SELECT NEXT_ID FROM AUTO_PK_SUPPORT WHERE TABLE_NAME = ? FOR UPDATE [bind: 1:'GALLERY']
+    INFO: SELECT NEXT_ID FROM AUTO_PK_SUPPORT WHERE TABLE_NAME = ? FOR UPDATE [bind: 1:'PAINTING']
+    INFO: INSERT INTO GALLERY (ID, NAME) VALUES (?, ?)
+    INFO: [batch bind: 1->ID:200, 2->NAME:'Metropolitan Museum of Art']
+    INFO: === updated 1 row.
+    INFO: INSERT INTO ARTIST (DATE_OF_BIRTH, ID, NAME) VALUES (?, ?, ?)
+    INFO: [batch bind: 1->DATE_OF_BIRTH:'1881-10-25 00:00:00.0', 2->ID:200, 3->NAME:'Pablo Picasso']
+    INFO: === updated 1 row.
+    INFO: INSERT INTO PAINTING (ARTIST_ID, GALLERY_ID, ID, NAME) VALUES (?, ?, ?, ?)
+    INFO: [batch bind: 1->ARTIST_ID:200, 2->GALLERY_ID:200, 3->ID:200, 4->NAME:'Gertrude Stein']
+    INFO: [batch bind: 1->ARTIST_ID:200, 2->GALLERY_ID:200, 3->ID:201, 4->NAME:'Girl Reading at a Table']
+    INFO: === updated 2 rows.
+    INFO: +++ transaction committed.
+
+So first Cayenne creates the needed tables (remember, we used
+"`CreateIfNoSchemaStrategy`"). Then it runs a number of inserts, generating primary keys
+on the fly. Not bad for just a few lines of code.
+    
+

http://git-wip-us.apache.org/repos/asf/cayenne/blob/df1324e4/docs/asciidoc/getting-started-guide/src/docs/asciidoc/_getting-started-guide/select-query.adoc
----------------------------------------------------------------------
diff --git a/docs/asciidoc/getting-started-guide/src/docs/asciidoc/_getting-started-guide/select-query.adoc b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/_getting-started-guide/select-query.adoc
new file mode 100644
index 0000000..56c843d
--- /dev/null
+++ b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/_getting-started-guide/select-query.adoc
@@ -0,0 +1,56 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with
+// this work for additional information regarding copyright ownership.
+// The ASF licenses this file to you under the Apache License, Version
+// 2.0 (the "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0 Unless required by
+// applicable law or agreed to in writing, software distributed under the
+// License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+// CONDITIONS OF ANY KIND, either express or implied. See the License for
+// the specific language governing permissions and limitations under the
+// License.
+=== Selecting Objects
+This chapter shows how to select objects from the database using `ObjectSelect` query. 
+    
+==== Introducing ObjectSelect
+It was shown before how to persist new objects. Cayenne queries are used to access
+already saved objects. The primary query type used for selecting objects is `ObjectSelect`.
+It can be mapped in CayenneModeler or created
+via the API. We'll use the latter approach in this section. We don't have too much data
+in the database yet, but we can still demonstrate the main principles below.
+
+- Select all paintings (the code, and the log output it generates):
+
+[source,java]
+----
+List<Painting> paintings1 = ObjectSelect.query(Painting.class).select(context);
+----
+
+   INFO: SELECT t0.GALLERY_ID, t0.ARTIST_ID, t0.NAME, t0.ID FROM PAINTING t0
+   INFO: === returned 2 rows. - took 18 ms.
+
+- Select paintings that start with "`gi`", ignoring case:
+
+[source,java]
+----
+List<Painting> paintings2 = ObjectSelect.query(Painting.class)
+        .where(Painting.NAME.likeIgnoreCase("gi%")).select(context);
+----
+    INFO: SELECT t0.GALLERY_ID, t0.NAME, t0.ARTIST_ID, t0.ID FROM PAINTING t0 WHERE UPPER(t0.NAME) LIKE UPPER(?)
+      [bind: 1->NAME:'gi%'] - prepared in 6 ms.
+    INFO: === returned 1 row. - took 18 ms.
+
+- Select all paintings done by artists who were born more than a 100 years ago:
+
+[source,java]
+----
+List<Painting> paintings3 = ObjectSelect.query(Painting.class)
+        .where(Painting.ARTIST.dot(Artist.DATE_OF_BIRTH).lt(LocalDate.of(1900,1,1)))
+        .select(context);
+----
+
+    INFO: SELECT t0.GALLERY_ID, t0.NAME, t0.ARTIST_ID, t0.ID FROM PAINTING t0 JOIN ARTIST t1 ON (t0.ARTIST_ID = t1.ID)
+      WHERE t1.DATE_OF_BIRTH < ? [bind: 1->DATE_OF_BIRTH:'1911-01-01 00:00:00.493'] - prepared in 7 ms.
+    INFO: === returned 2 rows. - took 25 ms.
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/cayenne/blob/df1324e4/docs/asciidoc/getting-started-guide/src/docs/asciidoc/_getting-started-guide/setup.adoc
----------------------------------------------------------------------
diff --git a/docs/asciidoc/getting-started-guide/src/docs/asciidoc/_getting-started-guide/setup.adoc b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/_getting-started-guide/setup.adoc
new file mode 100644
index 0000000..5a81104
--- /dev/null
+++ b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/_getting-started-guide/setup.adoc
@@ -0,0 +1,26 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with
+// this work for additional information regarding copyright ownership.
+// The ASF licenses this file to you under the Apache License, Version
+// 2.0 (the "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0 Unless required by
+// applicable law or agreed to in writing, software distributed under the
+// License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+// CONDITIONS OF ANY KIND, either express or implied. See the License for
+// the specific language governing permissions and limitations under the
+// License.
+== Setting up the environment
+
+The goal of this chapter of the tutorial is to install (or check that you already have
+installed) a minimally needed set of software to build a Cayenne application.
+
+=== Install Java
+
+Obviously, JDK has to be installed. Cayenne 4.0 requires JDK 1.7 or newer.
+
+=== Install IntelliJ IDEA
+
+Download and install IntelliJ IDEA Community Edition.
+This tutorial is based on version 2016.3, still it should work with any recent IntelliJ IDEA version.
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/cayenne/blob/df1324e4/docs/asciidoc/getting-started-guide/src/docs/asciidoc/_getting-started-guide/starting-project.adoc
----------------------------------------------------------------------
diff --git a/docs/asciidoc/getting-started-guide/src/docs/asciidoc/_getting-started-guide/starting-project.adoc b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/_getting-started-guide/starting-project.adoc
new file mode 100644
index 0000000..7f07377
--- /dev/null
+++ b/docs/asciidoc/getting-started-guide/src/docs/asciidoc/_getting-started-guide/starting-project.adoc
@@ -0,0 +1,111 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with
+// this work for additional information regarding copyright ownership.
+// The ASF licenses this file to you under the Apache License, Version
+// 2.0 (the "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0 Unless required by
+// applicable law or agreed to in writing, software distributed under the
+// License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+// CONDITIONS OF ANY KIND, either express or implied. See the License for
+// the specific language governing permissions and limitations under the
+// License.
+=== Starting a project
+
+The goal of this chapter is to create a new Java project in IntelliJ IDEA
+containing a basic Cayenne mapping. It presents an introduction to
+CayenneModeler GUI tool, showing how to create the initial mapping
+objects: `DataDomain`, `DataNode`, `DataMap`.
+
+==== Create a new Project in IntelliJ IDEA
+
+In IntelliJ IDEA select `File > New > Project..` and then
+select `Maven` and click `Next`.
+In the dialog shown on the screenshot below, fill the `Group Id`
+and `Artifact Id` fields and click `Next`.
+
+image::tutorial-idea-project.png[align="center"]
+
+On next dialog screen you can customize directory for your project and click `Finish`.
+Now you should have a new empty project.
+
+==== Download and Start CayenneModeler
+
+Although later in this tutorial we'll be using Maven to include Cayenne
+runtime jars in the project, you'll still need to download Cayenne to
+get access to the CayenneModeler tool.
+
+NOTE: If you are really into Maven, you can start CayenneModeler from Maven too.
+      We'll do it in a more traditional way here.
+
+Download the http://cayenne.apache.org/download.html[latest release]. Unpack the distribution
+somewhere in the file system and start CayenneModeler, following platform-specific instructions.
+On most platforms it is done simply by doubleclicking the Modeler icon.
+The welcome screen of the Modeler looks like this:
+
+image::modeler-started.png[align="center"]
+
+==== Create a New Mapping Project in CayenneModeler
+
+Click on the `New Project` button on Welcome screen. A new mapping project will appear
+that contains a single *DataDomain*. The meaning of a
+DataDomain is explained elsewhere in the User Guide. For now it is sufficient to
+understand that DataDomain is the root of your mapping project.
+
+==== Create a DataNode
+
+The next project object you will create is a *DataNode*.
+DataNode is a descriptor of a single database your application
+will connect to. Cayenne mapping project can use more than one database, but for now,
+we'll only use one. With "project" selected on the left, click on `Create DataNode` button image:icon-node.png[]
+on the toolbar (or select `Project > Create DataNode` from the menu).
+
+A new DataNode is displayed. Now you need to specify JDBC connection parameters. For
+an in-memory Derby database you can enter the following settings:
+
+- JDBC Driver: `org.apache.derby.jdbc.EmbeddedDriver`
+- DB URL: `jdbc:derby:memory:testdb;create=true`
+
+NOTE: We are creating an in-memory database here. So when
+      you stop your application, all the data will be lost. In most real-life
+      cases you'll be connecting to a database that actually persists its data on
+      disk, but an in-memory DB will do for the simple tutorial.
+
+Also you will need to change "Schema Update Strategy". Select
+`org.apache.cayenne.access.dbsync.CreateIfNoSchemaStrategy` from the dropdown, so that
+Cayenne creates a new schema on Derby based on the ORM mapping when the application
+starts.
+
+image::base-datanode.png[align="center"]
+
+==== Create a DataMap
+
+Now you will create a *DataMap*. DataMap is an object
+that holds all the mapping information. To create it, click on "Create DataMap" button
+image:icon-datamap.png[] (or select a corresponding menu item).
+Note that the newly created DataMap is automatically linked to the DataNode that you created in
+the previous step. If there is more than one DataNode, you may need to link a DataMap
+to the correct node manually. In other words a DataMap within DataDomain must point
+to a database described by the map.
+
+You can leave all the DataMap defaults unchanged except for one - "Java Package".
+Enter `org.example.cayenne.persistent`. This name will later be used for all persistent
+classes.
+
+image::base-datamap.png[align="center"]
+
+==== Save the Project
+
+image::idea-xmlfiles.png[float="right"]
+
+Before you proceed with the actual mapping, let's save the project. Click on "Save"
+button in the toolbar and navigate to the `tutorial` IDEA project folder that was
+created earlier in this section and its `src/main/resources` subfolder and save the
+project there. Now go back to IDEA and you will see two Cayenne XML files.
+
+Note that the location of the XML files is not coincidental. Cayenne runtime looks for
+`cayenne-*.xml` file in the application `CLASSPATH` and `src/main/resources` folder should
+already be a "class folder" in IDEA for our project (and is also a standard location
+that Maven would copy to a jar file, if we were using Maven from command-line).
+


Mime
View raw message