You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@cayenne.apache.org by nt...@apache.org on 2018/01/04 16:01:24 UTC
[10/14] cayenne git commit: Switch documentation from Docbook to
Asciidoctor format
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 > Reengineer Database
+ Schema". This will save you lots of time compared to manual mapping. However
+ understanding how to create the mapping by hand is important, so we are showing
+ the "manual" approach below.
+
+==== Mapping Database Tables and Columns
+Lets go back to CayenneModeler where we have the newly created project open and start
+by adding the ARTIST table. Database tables are called *DbEntities*
+in Cayenne mapping (those can be actual tables or database views).
+
+Select "datamap" on the left-hand side project tree and click "Create DbEntity" button image:icon-dbentity.png[]
+(or use "Project > Create DbEntity" menu). A new DbEntity is created. In "DbEntity
+Name" field enter "ARTIST". Then click on "Create Attribute" button image:icon-attribute.png[]
+on the entity toolbar. This action changes the view to the "Attribute"
+tab and adds a new attribute (attribute means a "table column" in this case) called
+"untitledAttr". Let's rename it to ID, make it an `INTEGER` and make it a PK:
+
+image::modeler-artistid.png[align="center"]
+
+Similarly add NAME `VARCHAR(200)` and DATE_OF_BIRTH `DATE` attributes. After that repeat
+this procedure for PAINTING and GALLERY entities to match DB schema shown above.
+
+==== Mapping Database Relationships
+
+Now we need to specify relationships between ARTIST, PAINTING and GALLERY tables.
+Start by creating a one-to-many ARTIST/PAINTING relationship:
+
+- Select the ARTIST DbEntity on the left and click on the "Properties" tab.
+
+- Click on "Create Relationship" button on the entity toolbar image:icon-relationship.png[] - a relationship
+called "untitledRel" is created.
+
+- Choose the "Target" to be "Painting".
+
+- Click on the "Database Mapping" button image:icon-edit.png[] - relationship
+configuration dialog is presented. Here you can assign a name to the
+relationship and also its complimentary reverse relationship. This name can be
+anything (this is really a symbolic name of the database referential
+constraint), but it is recommended to use a valid Java identifier, as this will
+save some typing later. We'll call the relationship "paintings" and reverse
+relationship "artist".
+
+- Click on "Add" button on the right to add a join
+
+- Select "ID" column for the "Source" and "ARTIST_ID" column for the target.
+
+- Relationship information should now look like this:
+
+image::modeler-dbrelationship.png[align="center"]
+
+- Click "Done" to confirm the changes and close the dialog.
+
+- Two complimentary relationships have been created - from ARTIST to PAINTING
+and back. Still you may have noticed one thing is missing - "paintings"
+relationship should be to-many, but "To Many" checkbox is not checked. Let's
+change that - check the checkbox for "paintings" relationship, and then click on
+PAINTING DbEntity, and uncheck "artist" relationship "To Many" to make the
+reverse relationship "to-one" as it should be.
+
+- Repeat the steps above to create a many-to-one relationship from PAINTING to GALLERY, calling the relationships pair
+"gallery" and "paintings".
+
+==== Mapping Java Classes
+
+Now that the database schema mapping is complete, CayenneModeler can create mappings
+of Java classes (aka "ObjEntities") by deriving everything from DbEntities. At present
+there is no way to do it for the entire DataMap in one click, so we'll do it for each
+table individually.
+
+- Select "ARTIST" DbEntity and click on "Create ObjEntity" button image:icon-new_objentity.png[]
+either on the entity toolbar or on the main toolbar. An ObjEntity called
+"Artist" is created with a Java class field set to
+`org.example.cayenne.persistent.Artist`. The modeler transformed the database
+names to the Java-friendly names (e.g., if you click on the "Attributes" tab,
+you'll see that "DATE_OF_BIRTH" column was converted to "dateOfBirth" Java class
+attribute).
+
+- Select "GALLERY" DbEntity and click on "Create ObjEntity" button again - you'll see a "Gallery" ObjEntity created.
+- Finally, do the same thing for "PAINTING".
+
+Now you need to synchronize relationships. Artist and Gallery entities were created
+when there was no related "Painting" entity, so their relationships were not set.
+
+- Click on the "Artist" ObjEntity. Now click on "Sync ObjEntity with DbEntity" button on
+the toolbar image:icon-sync.png[] - you will see the "paintings" relationship appear.
+- Do the same for the "Gallery" entity.
+
+Unless you want to customize the Java class and property names (which you can do easily) the mapping is complete.
http://git-wip-us.apache.org/repos/asf/cayenne/blob/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).
+