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:16 UTC
[02/14] cayenne git commit: Switch documentation from Docbook to
Asciidoctor format
http://git-wip-us.apache.org/repos/asf/cayenne/blob/df1324e4/docs/docbook/getting-started-rop/src/docbkx/client-project.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/getting-started-rop/src/docbkx/client-project.xml b/docs/docbook/getting-started-rop/src/docbkx/client-project.xml
deleted file mode 100644
index a777edb..0000000
--- a/docs/docbook/getting-started-rop/src/docbkx/client-project.xml
+++ /dev/null
@@ -1,131 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!--
- Licensed to the Apache Software Foundation (ASF) under one or more
- contributor license agreements. See the NOTICE file distributed with
- this work for additional information regarding copyright ownership.
- The ASF licenses this file to you under the Apache License, Version
- 2.0 (the "License"); you may not use this file except in compliance
- with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0 Unless required by
- applicable law or agreed to in writing, software distributed under the
- License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
- CONDITIONS OF ANY KIND, either express or implied. See the License for
- the specific language governing permissions and limitations under the
- License.
--->
-<chapter xmlns="http://docbook.org/ns/docbook"
- xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0">
- <title>Starting Client Project</title>
- <section xml:id="create-rop-client-project">
- <title>Create an ROP Client Project in Eclipse</title>
- <para>Creation of a new Eclipse project has been discussed in some details in "Getting
- Started with Cayenne" guide, so we will omit the screenshots for the common
- parts.</para>
- <para>In Eclipse select "File > New > Other..." and then "Maven > Maven Project".
- Click "Next". On the following screen check "Create a simple project" checkbox and click
- "Next" again. In the dialog shown on the screenshot below, enter "org.example.cayenne"
- for the "Group Id" and "tutorial-rop-client" for the "Artifact Id" (both without the
- quotes) and click "Finish". </para>
- <para>Now you should have a new empty project in the Eclipse workspace. Check that the
- project Java compiler settings are correct. Rightclick on the "tutorial-rop-client"
- project, select "Properties > Java Compiler" and ensure that "Compiler compliance
- level" is at least 1.5 (some versions of Maven plugin seem to be setting it to 1.4 by
- default).</para>
- </section>
- <section xml:id="create-client-java-classes">
- <title>Create Client Java Classes</title>
- <para>The client doesn't need the XML ORM mapping, as it is loaded from the server. However
- it needs the client-side Java classes. Let's generate them from the existing
- mapping:</para>
- <itemizedlist>
- <listitem>
- <para>Start CayenneModeler and open cayenne.xml from the "tutorial" project (located
- under "tutorial/src/main/resources", unless it is already open.</para>
- </listitem>
- <listitem>
- <para>Select the "datamap" DataMap and check "Allow Client Entities"
- checkbox.</para>
- </listitem>
- <listitem>
- <para>Enter "org.example.cayenne.persistent.client" for the "Client Java Package"
- and click "Update.." button next to the field to refresh the client package of
- all entities.</para>
- <para><inlinemediaobject>
- <imageobject>
- <imagedata fileref="images/datamap-enableclient.png" scalefit="1" width="100%"/>
- </imageobject>
- </inlinemediaobject></para>
- </listitem>
- </itemizedlist>
- <itemizedlist>
- <listitem>
- <para>Select "Tools > Generate Classes" menu.</para>
- </listitem>
- <listitem>
- <para>For "Type" select "Client Persistent Objects".</para>
- </listitem>
- <listitem>
- <para>For the "Output Directory" select "tutorial-rop-client/src/main/java" folder
- (as client classes should go in the <emphasis role="italic">client</emphasis>
- project).</para>
- </listitem>
- <listitem>
- <para>Click on "Classes" tab and check the "Check All Classes" checkbox (unless it
- is already checked and reads "Uncheck all Classes").</para>
- </listitem>
- <listitem>
- <para>Click "Generate".</para>
- </listitem>
- </itemizedlist>
- <para>Now go back to Eclipse, right click on "tutorial-rop-client" project and select
- "Refresh" - you should see pairs of classes generated for each mapped entity, same as on
- the server. And again, we see a bunch of errors in those classes. Let's fix it now by
- adding two dependencies, "cayenne-client" and "resin-hessian", in the bottom of the
- pom.xml file. We also need to add Caucho M2 repository to pull Hessian jar files. The
- resulting POM should look like this:</para>
- <programlisting><project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
- <modelVersion>4.0.0</modelVersion>
- <groupId>org.example.cayenne</groupId>
- <artifactId>tutorial-rop-client</artifactId>
- <version>0.0.1-SNAPSHOT</version>
-
- <dependencies>
- <dependency>
- <groupId>org.apache.cayenne</groupId>
- <artifactId>cayenne-client</artifactId>
- <!-- Here specify the version of Cayenne you are actually using -->
- <version>4.0.M3</version>
- </dependency>
- <dependency>
- <groupId>com.caucho</groupId>
- <artifactId>hessian</artifactId>
- <version>4.0.38</version>
- </dependency>
- </dependencies>
-
- <repositories>
- <repository>
- <id>caucho</id>
- <name>Caucho Repository</name>
- <url>http://caucho.com/m2</url>
- <layout>default</layout>
- <snapshots>
- <enabled>false</enabled>
- </snapshots>
- <releases>
- <enabled>true</enabled>
- </releases>
- </repository>
- </repositories>
-</project></programlisting>
- <para>Your computer must be connected to the internet. Once you save the pom.xml, Eclipse
- will download the needed jar files and add them to the project build path. After that
- all the errors should disappear.</para>
- <para>Now let's check the entity class pairs. They look almost identical to their server
- counterparts, although the superclass and the property access code are different. At
- this point these differences are somewhat academic, so let's go on with the
- tutorial.</para>
- </section>
-</chapter>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/df1324e4/docs/docbook/getting-started-rop/src/docbkx/index.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/getting-started-rop/src/docbkx/index.xml b/docs/docbook/getting-started-rop/src/docbkx/index.xml
deleted file mode 100644
index c6814f4..0000000
--- a/docs/docbook/getting-started-rop/src/docbkx/index.xml
+++ /dev/null
@@ -1,43 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!--
- Licensed to the Apache Software Foundation (ASF) under one or more
- contributor license agreements. See the NOTICE file distributed with
- this work for additional information regarding copyright ownership.
- The ASF licenses this file to you under the Apache License, Version
- 2.0 (the "License"); you may not use this file except in compliance
- with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0 Unless required by
- applicable law or agreed to in writing, software distributed under the
- License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
- CONDITIONS OF ANY KIND, either express or implied. See the License for
- the specific language governing permissions and limitations under the
- License.
--->
-<book xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
- xml:id="getting-started-rop" xmlns:xi="http://www.w3.org/2001/XInclude">
- <info>
- <title>Getting Started with Cayenne ROP (Remote Object Persistence)</title>
- <copyright>
- <year>2011-<?dbtimestamp format="Y"?></year>
- <holder>Apache Software Foundation and individual authors</holder>
- </copyright>
- <legalnotice>
- <title>License</title>
- <para>Licensed to the Apache Software Foundation (ASF) under one or more contributor
- license agreements. See the NOTICE file distributed with this work for additional
- information regarding copyright ownership. The ASF licenses this file to you under
- the Apache License, Version 2.0 (the "License"); you may not use this file except in
- compliance with the License. You may obtain a copy of the License at
- http://www.apache.org/licenses/LICENSE-2.0</para>
-
- <para>Unless required by applicable law or agreed to in writing, software distributed
- under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
- CONDITIONS OF ANY KIND, either express or implied. See the License for the specific
- language governing permissions and limitations under the License.</para>
- </legalnotice>
- </info>
- <xi:include href="part1.xml"/>
- <xi:include href="part2.xml"/>
-</book>
-
http://git-wip-us.apache.org/repos/asf/cayenne/blob/df1324e4/docs/docbook/getting-started-rop/src/docbkx/part1.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/getting-started-rop/src/docbkx/part1.xml b/docs/docbook/getting-started-rop/src/docbkx/part1.xml
deleted file mode 100644
index cf86a52..0000000
--- a/docs/docbook/getting-started-rop/src/docbkx/part1.xml
+++ /dev/null
@@ -1,22 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!--
- Licensed to the Apache Software Foundation (ASF) under one or more
- contributor license agreements. See the NOTICE file distributed with
- this work for additional information regarding copyright ownership.
- The ASF licenses this file to you under the Apache License, Version
- 2.0 (the "License"); you may not use this file except in compliance
- with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0 Unless required by
- applicable law or agreed to in writing, software distributed under the
- License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
- CONDITIONS OF ANY KIND, either express or implied. See the License for
- the specific language governing permissions and limitations under the
- License.
--->
-<part xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
- xml:id="getting-started-rop-part1" xmlns:xi="http://www.w3.org/2001/XInclude">
- <title>Prerequisites</title>
- <xi:include href="setup.xml"/>
-</part>
-
http://git-wip-us.apache.org/repos/asf/cayenne/blob/df1324e4/docs/docbook/getting-started-rop/src/docbkx/part2.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/getting-started-rop/src/docbkx/part2.xml b/docs/docbook/getting-started-rop/src/docbkx/part2.xml
deleted file mode 100644
index 3f17927..0000000
--- a/docs/docbook/getting-started-rop/src/docbkx/part2.xml
+++ /dev/null
@@ -1,24 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!--
- Licensed to the Apache Software Foundation (ASF) under one or more
- contributor license agreements. See the NOTICE file distributed with
- this work for additional information regarding copyright ownership.
- The ASF licenses this file to you under the Apache License, Version
- 2.0 (the "License"); you may not use this file except in compliance
- with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0 Unless required by
- applicable law or agreed to in writing, software distributed under the
- License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
- CONDITIONS OF ANY KIND, either express or implied. See the License for
- the specific language governing permissions and limitations under the
- License.
--->
-<part xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
- xml:id="getting-started-rop-part2" xmlns:xi="http://www.w3.org/2001/XInclude">
- <title>Remote Object Persistence Quick Start</title>
- <xi:include href="client-project.xml"/>
- <xi:include href="web-service.xml"/>
- <xi:include href="client-code.xml"/>
- <xi:include href="authentication.xml"/>
-</part>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/df1324e4/docs/docbook/getting-started-rop/src/docbkx/setup.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/getting-started-rop/src/docbkx/setup.xml b/docs/docbook/getting-started-rop/src/docbkx/setup.xml
deleted file mode 100644
index 4c5f5b9..0000000
--- a/docs/docbook/getting-started-rop/src/docbkx/setup.xml
+++ /dev/null
@@ -1,53 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!--
- Licensed to the Apache Software Foundation (ASF) under one or more
- contributor license agreements. See the NOTICE file distributed with
- this work for additional information regarding copyright ownership.
- The ASF licenses this file to you under the Apache License, Version
- 2.0 (the "License"); you may not use this file except in compliance
- with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0 Unless required by
- applicable law or agreed to in writing, software distributed under the
- License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
- CONDITIONS OF ANY KIND, either express or implied. See the License for
- the specific language governing permissions and limitations under the
- License.
--->
-<chapter xmlns="http://docbook.org/ns/docbook"
- xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0">
- <title>Prerequisites</title>
- <para>This tutorial starts where "Getting Started with Cayenne" left
- off. If you have gone through the previous tutorial, and have the "tutorial" project open in
- Eclipse, you can go directly to the
- next step. If not, here are the compressed instructions to prepare you for work
- with ROP:</para>
- <itemizedlist>
- <listitem>
- <para>
- Step 1 - Eclipse Setup
- </para>
- </listitem>
- <listitem>
- <para>
- Step 2 - Create a project
- </para>
- </listitem>
- <listitem>
- <para>
- Step 3 - Create Cayenne OR Mapping
- </para>
- </listitem>
- <listitem>
- <para>
- Step 4 - Create Java Classes
- </para>
- </listitem>
- <listitem>
- <para>
- Step 5 - Convert the project to webapp.</para>
- </listitem>
- </itemizedlist>
- <para>Note that at "Step 5" you can skip the JSP creation part. Just setup web.xml and
- maven-jetty-plugin in the POM.</para>
-</chapter>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/df1324e4/docs/docbook/getting-started-rop/src/docbkx/web-service.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/getting-started-rop/src/docbkx/web-service.xml b/docs/docbook/getting-started-rop/src/docbkx/web-service.xml
deleted file mode 100644
index 62ad70f..0000000
--- a/docs/docbook/getting-started-rop/src/docbkx/web-service.xml
+++ /dev/null
@@ -1,131 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!--
- Licensed to the Apache Software Foundation (ASF) under one or more
- contributor license agreements. See the NOTICE file distributed with
- this work for additional information regarding copyright ownership.
- The ASF licenses this file to you under the Apache License, Version
- 2.0 (the "License"); you may not use this file except in compliance
- with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0 Unless required by
- applicable law or agreed to in writing, software distributed under the
- License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
- CONDITIONS OF ANY KIND, either express or implied. See the License for
- the specific language governing permissions and limitations under the
- License.
--->
-<chapter xmlns="http://docbook.org/ns/docbook"
- xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0">
- <title>Setting up Hessian Web Service</title>
- <section xml:id="setting-up-dependencies">
- <title>Setting up Dependencies</title>
- <para>Now lets get back to the "tutorial" project that contains a web application and set up
- dependencies. The only extra one that we don't have yet is resin-hessian.jar, just like
- the client, so let's add it (and the caucho repo declaration) to the pom.xml.</para>
- <programlisting><project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
- ...
- <dependencies>
- ...
- <dependency>
- <groupId>com.caucho</groupId>
- <artifactId>hessian</artifactId>
- <version>4.0.38</version>
- </dependency>
- </dependencies>
-
- <build>
- ...
- </build>
-
- <repositories>
- <repository>
- <id>caucho</id>
- <name>Caucho Repository</name>
- <url>http://caucho.com/m2</url>
- <layout>default</layout>
- <snapshots>
- <enabled>false</enabled>
- </snapshots>
- <releases>
- <enabled>true</enabled>
- </releases>
- </repository>
- </repositories>
- </project></programlisting>
-
- <note>
- <para><emphasis role="bold">Maven Optimization
- Hint</emphasis> On a real project both server and client modules will
- likely share a common parent pom.xml where common repository delcaration can
- be placed, with child pom's "inheriting" it from parent. This would reduce
- build code duplication.</para>
- </note>
- </section>
- <section xml:id="client-classes-on-server">
- <title>Client Classes on the Server</title>
- <para>Since ROP web service requires both server and client persistent classes, we need to
- generate a second copy of the client classes inside the server project. This is a minor
- inconvenience that will hopefully go away in the future versions of Cayenne. <emphasis
- role="italic">Don't forget to refresh the project in Eclipse after class generation
- is done.</emphasis></para>
- </section>
- <section xml:id="configuring-web-xml">
- <title>Configuring web.xml</title>
- <para>Cayenne web service is declared in the web.xml. It is implemented as a servlet
- "org.apache.cayenne.rop.ROPServlet". Open
- tutorial/src/main/webapp/WEB-INF/web.xml in Eclipse and add a service declaration: </para>
- <programlisting><?xml version="1.0" encoding="utf-8"?>
- <!DOCTYPE web-app
- PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
- "http://java.sun.com/dtd/web-app_2_3.dtd">
-<web-app>
- <display-name>Cayenne Tutorial</display-name>
- <servlet>
- <servlet-name>cayenne-project</servlet-name>
- <servlet-class>org.apache.cayenne.rop.ROPServlet</servlet-class>
- <load-on-startup>0</load-on-startup>
- </servlet>
- <servlet-mapping>
- <servlet-name>cayenne-project</servlet-name>
- <url-pattern>/cayenne-service</url-pattern>
- </servlet-mapping>
- </web-app></programlisting>
- <note>
- <para><emphasis role="bold">Extending Server Behavior via
- Callbacks</emphasis> While no custom Java code is required on the
- server, just a service declaration, it is possible to customizing
- server-side behavior via callbacks and listeners (not shown in the
- tutorial).</para>
- </note>
- </section>
- <section xml:id="running-rop-server">
- <title>Running ROP Server</title>
- <para>Use previosly
- created Eclipse Jetty run configuration available via "Run > Run
- Configurations..." (or create a new
- one if none exists yet). You should see output in the Eclipse console similar
- to the following:</para>
- <programlisting>[INFO] Scanning for projects...
-[INFO]
-[INFO] ------------------------------------------------------------------------
-[INFO] Building tutorial 0.0.1-SNAPSHOT
-[INFO] ------------------------------------------------------------------------
-...
-[INFO] Starting jetty 6.1.22 ...
-INFO::jetty-6.1.22
-INFO::No Transaction manager found - if your webapp requires one, please configure one.
-INFO::Started SelectChannelConnector@0.0.0.0:8080
-[INFO] Started Jetty Server
-INFO: Loading XML configuration resource from file:cayenne-project.xml
-INFO: loading user name and password.
-INFO: Created connection pool: jdbc:derby:memory:testdb;create=true
- Driver class: org.apache.derby.jdbc.EmbeddedDriver
- Min. connections in the pool: 1
- Max. connections in the pool: 1</programlisting>
- <para>Cayenne ROP service URL is <emphasis role="italic"
- >http://localhost:8080/tutorial/cayenne-service</emphasis>. If you click on it, you
- will see "Hessian Requires POST" message, that means that the service is alive, but you
- need a client other than the web browser to access it.</para>
- </section>
-</chapter>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/df1324e4/docs/docbook/getting-started-rop/src/images/datamap-enableclient.png
----------------------------------------------------------------------
diff --git a/docs/docbook/getting-started-rop/src/images/datamap-enableclient.png b/docs/docbook/getting-started-rop/src/images/datamap-enableclient.png
deleted file mode 100644
index 62a2af2..0000000
Binary files a/docs/docbook/getting-started-rop/src/images/datamap-enableclient.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/cayenne/blob/df1324e4/docs/docbook/getting-started/pom.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/getting-started/pom.xml b/docs/docbook/getting-started/pom.xml
deleted file mode 100644
index bcc4f0c..0000000
--- a/docs/docbook/getting-started/pom.xml
+++ /dev/null
@@ -1,40 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!--
- Licensed to the Apache Software Foundation (ASF) under one
- or more contributor license agreements. See the NOTICE file
- distributed with this work for additional information
- regarding copyright ownership. The ASF licenses this file
- to you under the Apache License, Version 2.0 (the
- "License"); you may not use this file except in compliance
- with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
- Unless required by applicable law or agreed to in writing,
- software distributed under the License is distributed on an
- "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- KIND, either express or implied. See the License for the
- specific language governing permissions and limitations
- under the License.
--->
-
-<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
- <parent>
- <groupId>org.apache.cayenne.docs</groupId>
- <artifactId>cayenne-docbook</artifactId>
- <version>4.1.M2-SNAPSHOT</version>
- </parent>
-
- <modelVersion>4.0.0</modelVersion>
- <artifactId>getting-started</artifactId>
- <packaging>jar</packaging>
- <name>getting-started: Docbook - Getting Started with Cayenne</name>
-
- <build>
- <resources>
- <resource>
- <directory>target/site</directory>
- </resource>
- </resources>
- </build>
-</project>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/df1324e4/docs/docbook/getting-started/src/docbkx/delete.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/getting-started/src/docbkx/delete.xml b/docs/docbook/getting-started/src/docbkx/delete.xml
deleted file mode 100644
index b2ecdb3..0000000
--- a/docs/docbook/getting-started/src/docbkx/delete.xml
+++ /dev/null
@@ -1,79 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<?xml-model href="http://www.oasis-open.org/docbook/xml/5.0/rng/docbook.rng" schematypens="http://relaxng.org/ns/structure/1.0"?>
-<!--
- Licensed to the Apache Software Foundation (ASF) under one or more
- contributor license agreements. See the NOTICE file distributed with
- this work for additional information regarding copyright ownership.
- The ASF licenses this file to you under the Apache License, Version
- 2.0 (the "License"); you may not use this file except in compliance
- with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0 Unless required by
- applicable law or agreed to in writing, software distributed under the
- License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
- CONDITIONS OF ANY KIND, either express or implied. See the License for
- the specific language governing permissions and limitations under the
- License.
--->
-<section xmlns="http://docbook.org/ns/docbook"
- xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0">
- <title>Deleting Objects</title>
- <para>This chapter explains how to model relationship delete rules and how to delete individual
- objects as well as sets of objects. Also demonstrated the use of Cayenne class to run a
- query.</para>
- <section xml:id="setup-delete-rules">
- <title>Setting Up Delete Rules</title>
- <para>Before we discuss the API for object deletion, lets go back to CayenneModeler and set
- up some delete rules. Doing this is optional but will simplify correct handling of the
- objects related to deleted objects.</para>
- <para>In the Modeler go to "Artist" ObjEntity, "Relationships" tab and select "Cascade" for
- the "paintings" relationship delete rule:</para>
- <para><inlinemediaobject>
- <imageobject>
- <imagedata fileref="images/modeler-deleterule.png" scalefit="1" width="100%"/>
- </imageobject>
- </inlinemediaobject>
- </para>
- <para>Repeat this step for other relationships:</para>
- <itemizedlist>
- <listitem>
- <para>For Gallery set "paintings" relationship to be "Nullify", as a painting can
- exist without being displayed in a gallery.</para>
- </listitem>
- <listitem>
- <para>For Painting set both relationships rules to "Nullify".</para>
- </listitem>
- </itemizedlist>
- <para>Now save the mapping.</para>
- </section>
- <section xml:id="deleting-objects">
- <title>Deleting Objects</title>
- <para>While deleting objects is possible via SQL, qualifying a delete on one or more IDs, a
- more common way in Cayenne (or ORM in general) is to get a hold of the object first, and
- then delete it via the context. Let's use utility class Cayenne to find an
- artist:</para>
- <programlisting language="java">Artist picasso = ObjectSelect.query(Artist.class)
- .where(Artist.NAME.eq("Pablo Picasso")).selectOne(context);</programlisting>
- <para>Now let's delete the artist:</para>
- <programlisting language="java">if (picasso != null) {
- context.deleteObject(picasso);
- context.commitChanges();
-}</programlisting>
- <para>Since we set up "Cascade" delete rule for the Artist.paintings relationships, Cayenne
- will automatically delete all paintings of this artist. So when your run the app you'll
- see this output:</para>
- <screen>INFO: SELECT t0.DATE_OF_BIRTH, t0.NAME, t0.ID FROM ARTIST t0
- WHERE t0.NAME = ? [bind: 1->NAME:'Pablo Picasso'] - prepared in 6 ms.
-INFO: === returned 1 row. - took 18 ms.
-INFO: +++ transaction committed.
-INFO: --- transaction started.
-INFO: DELETE FROM PAINTING WHERE ID = ?
-INFO: [batch bind: 1->ID:200]
-INFO: [batch bind: 1->ID:201]
-INFO: === updated 2 rows.
-INFO: DELETE FROM ARTIST WHERE ID = ?
-INFO: [batch bind: 1->ID:200]
-INFO: === updated 1 row.
-INFO: +++ transaction committed.</screen>
- </section>
-</section>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/df1324e4/docs/docbook/getting-started/src/docbkx/index.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/getting-started/src/docbkx/index.xml b/docs/docbook/getting-started/src/docbkx/index.xml
deleted file mode 100644
index 433c098..0000000
--- a/docs/docbook/getting-started/src/docbkx/index.xml
+++ /dev/null
@@ -1,44 +0,0 @@
-<?xml version="1.0" encoding="UTF-8" ?>
-<!--
- Licensed to the Apache Software Foundation (ASF) under one or more
- contributor license agreements. See the NOTICE file distributed with
- this work for additional information regarding copyright ownership.
- The ASF licenses this file to you under the Apache License, Version
- 2.0 (the "License"); you may not use this file except in compliance
- with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0 Unless required by
- applicable law or agreed to in writing, software distributed under the
- License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
- CONDITIONS OF ANY KIND, either express or implied. See the License for
- the specific language governing permissions and limitations under the
- License.
--->
-<book xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
- xml:id="getting-started" xmlns:xi="http://www.w3.org/2001/XInclude">
- <info>
- <title>Getting Started with Cayenne</title>
- <copyright>
- <year>2011-<?dbtimestamp format="Y"?></year>
- <holder>Apache Software Foundation and individual authors</holder>
- </copyright>
- <legalnotice>
- <title>License</title>
- <para>Licensed to the Apache Software Foundation (ASF) under one or more contributor
- license agreements. See the NOTICE file distributed with this work for additional
- information regarding copyright ownership. The ASF licenses this file to you under
- the Apache License, Version 2.0 (the "License"); you may not use this file except in
- compliance with the License. You may obtain a copy of the License at
- http://www.apache.org/licenses/LICENSE-2.0</para>
-
- <para>Unless required by applicable law or agreed to in writing, software distributed
- under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
- CONDITIONS OF ANY KIND, either express or implied. See the License for the specific
- language governing permissions and limitations under the License.</para>
- </legalnotice>
- </info>
- <xi:include href="part1.xml"/>
- <xi:include href="part2.xml"/>
- <xi:include href="part3.xml"/>
- <xi:include href="part4.xml"/>
-</book>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/df1324e4/docs/docbook/getting-started/src/docbkx/java-classes.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/getting-started/src/docbkx/java-classes.xml b/docs/docbook/getting-started/src/docbkx/java-classes.xml
deleted file mode 100644
index d6b46d5..0000000
--- a/docs/docbook/getting-started/src/docbkx/java-classes.xml
+++ /dev/null
@@ -1,122 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<?xml-model href="http://www.oasis-open.org/docbook/xml/5.0/rng/docbook.rng" schematypens="http://relaxng.org/ns/structure/1.0"?>
-<!--
- Licensed to the Apache Software Foundation (ASF) under one or more
- contributor license agreements. See the NOTICE file distributed with
- this work for additional information regarding copyright ownership.
- The ASF licenses this file to you under the Apache License, Version
- 2.0 (the "License"); you may not use this file except in compliance
- with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0 Unless required by
- applicable law or agreed to in writing, software distributed under the
- License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
- CONDITIONS OF ANY KIND, either express or implied. See the License for
- the specific language governing permissions and limitations under the
- License.
--->
-<section xmlns="http://docbook.org/ns/docbook"
- xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0">
- <title>Creating Java Classes</title>
- <para>Here we'll generate the Java classes from the model that was created in the previous
- section. CayenneModeler can be used to also generate the database schema, but since we
- specified "<code>CreateIfNoSchemaStrategy</code>" earlier when we created a DataNode, we'll skip the
- database schema step. Still be aware that you can do it if you need to via "Tools >
- Create Database Schema".
- </para>
- <section xml:id="creating-java-classes">
- <title>Creating Java Classes</title>
- <itemizedlist>
- <listitem>
- <para>Select "Tools > Generate Classes" menu.</para>
- </listitem>
- <listitem>
- <para>For "Type" select "Standard Persistent Objects", if it is not already
- selected.</para>
- </listitem>
- <listitem>
- <para>For the "Output Directory" select "<code>src/main/java</code>" folder under your IDEA
- project folder (this is a "peer" location to the <code>cayenne-*.xml</code> location we
- selected before).</para>
- </listitem>
- <listitem>
- <para>Click on "Classes" tab and check the "Check All Classes" checkbox (unless it
- is already checked and reads "Uncheck all Classes").</para>
- </listitem>
- <listitem>
- <para>Click "Generate"</para>
- </listitem>
- </itemizedlist>
- <para>Now go back to IDEA - you should see pairs of classes generated for each mapped
- entity. You probably also see that there's a bunch of red squiggles next to the newly
- generated Java classes in IDEA. This is because our project does not include Cayenne as
- a Maven dependency yet. Let's fix it now by adding "cayenne-server"
- artifact in the bottom of the <code>pom.xml</code> file. Also we should tell Maven
- compile plugin that our project needs Java 8. The resulting POM should look like
- this:<programlisting language="xml"><project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
- <modelVersion>4.0.0</modelVersion>
- <groupId>org.example.cayenne</groupId>
- <artifactId>tutorial</artifactId>
- <version>0.0.1-SNAPSHOT</version>
-
- <dependencies>
- <dependency>
- <groupId>org.apache.cayenne</groupId>
- <artifactId>cayenne-server</artifactId>
- <!-- Here specify the version of Cayenne you are actually using -->
- <version><?eval ${project.version}?></version>
- </dependency>
- <dependency>
- <groupId>org.slf4j</groupId>
- <artifactId>slf4j-simple</artifactId>
- <version>1.7.25</version>
- </dependency>
- </dependencies>
-
- <build>
- <plugins>
- <!-- Tell maven to support Java 8 -->
- <plugin>
- <groupId>org.apache.maven.plugins</groupId>
- <artifactId>maven-compiler-plugin</artifactId>
- <version>3.6.1</version>
- <configuration>
- <source>1.8</source>
- <target>1.8</target>
- </configuration>
- </plugin>
- </plugins>
- </build>
-</project></programlisting></para>
- <para>Your computer must be connected to the internet. Once you edit the <code>pom.xml</code>, IDEA
- will download the needed Cayenne jar file and add it to the project build path. As a
- result, all the errors should disappear. In tutorial for console output we use slf4j-simple logger
- implementation. Due to use SLF4J logger in Apache Cayenne, you can use your custom logger (e.g. log4j
- or commons-logging) through bridges.
- </para>
- <para><inlinemediaobject>
- <imageobject>
- <imagedata fileref="images/idea-generated-classes.png" scalefit="1" width="100%"/>
- </imageobject>
- </inlinemediaobject></para>
- <para>Now let's check the entity class pairs. Each one is made of a superclass (e.g. <code>_Artist</code>)
- and a subclass (e.g. <code>Artist</code>). You <emphasis role="bold">should not</emphasis> modify the
- superclasses whose names start with "_" (underscore), as they will be replaced on
- subsequent generator runs. Instead all custom logic should be placed in the subclasses
- in "<code>org.example.cayenne.persistent</code>" package - those will never be overwritten by the
- class generator.</para>
- <para>
- <note>
- <title>Class Generation Hint</title>
- <para> Often you'd start by generating classes from the
- Modeler, but at the later stages of the project the generation is usually
- automated either via Ant cgen task or Maven cgen mojo. All three methods are
- interchangeable, however Ant and Maven methods would ensure that you never
- forget to regenerate classes on mapping changes, as they are integrated into
- the build cycle.</para>
- </note>
- </para>
-
- </section>
-</section>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/df1324e4/docs/docbook/getting-started/src/docbkx/object-context.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/getting-started/src/docbkx/object-context.xml b/docs/docbook/getting-started/src/docbkx/object-context.xml
deleted file mode 100644
index d17b64a..0000000
--- a/docs/docbook/getting-started/src/docbkx/object-context.xml
+++ /dev/null
@@ -1,103 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<?xml-model href="http://www.oasis-open.org/docbook/xml/5.0/rng/docbook.rng" schematypens="http://relaxng.org/ns/structure/1.0"?>
-<!--
- Licensed to the Apache Software Foundation (ASF) under one or more
- contributor license agreements. See the NOTICE file distributed with
- this work for additional information regarding copyright ownership.
- The ASF licenses this file to you under the Apache License, Version
- 2.0 (the "License"); you may not use this file except in compliance
- with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0 Unless required by
- applicable law or agreed to in writing, software distributed under the
- License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
- CONDITIONS OF ANY KIND, either express or implied. See the License for
- the specific language governing permissions and limitations under the
- License.
--->
-<section xmlns="http://docbook.org/ns/docbook"
- xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0">
- <title>Getting started with ObjectContext</title>
- <para>In this section we'll write a simple main class to run our application, and get a brief
- introduction to Cayenne ObjectContext.</para>
- <section xml:id="creating-main-class">
- <title>Creating the Main Class</title>
- <itemizedlist>
- <listitem>
- <para>In IDEA create a new class called "<code>Main</code>" in the "<code>org.example.cayenne</code>"
- package.</para>
- </listitem>
- <listitem>
- <para>Create a standard "main" method to make it a runnable
- class:<programlisting language="java">package org.example.cayenne;
-
-public class Main {
-
- public static void main(String[] args) {
-
- }
-}</programlisting></para>
- </listitem>
- <listitem>
- <para>The first thing you need to be able to access the database is to create a
- <code>ServerRuntime</code> object (which is essentially a wrapper around Cayenne stack) and
- use it to obtain an instance of an
- <code>ObjectContext</code>.<programlisting language="java">package org.example.cayenne;
-
-import org.apache.cayenne.ObjectContext;
-import org.apache.cayenne.configuration.server.ServerRuntime;
-
-public class Main {
-
- public static void main(String[] args) {
- ServerRuntime cayenneRuntime = ServerRuntime.builder()
- .addConfig("cayenne-project.xml")
- .build();
- ObjectContext context = cayenneRuntime.newContext();
- }
-}</programlisting></para>
- <para><code>ObjectContext</code> is an isolated "session" in Cayenne that provides all needed API
- to work with data. ObjectContext has methods to execute queries and manage
- persistent objects. We'll discuss them in the following sections. When the first
- ObjectContext is created in the application, Cayenne loads XML mapping files and
- creates a shared access stack that is later reused by other ObjectContexts.
- </para>
- </listitem>
- </itemizedlist>
- </section>
- <section xml:id="runnning-app">
- <title>Running Application</title>
- <para>Let's check what happens when you run the application. But before we do that we need
- to add another dependency to the <code>pom.xml</code> - Apache Derby, our embedded database engine.
- The following piece of XML needs to be added to the
- <code><dependencies>...</dependencies></code> section, where we already have Cayenne
- jars:<programlisting language="xml"><dependency>
- <groupId>org.apache.derby</groupId>
- <artifactId>derby</artifactId>
- <version>10.13.1.1</version>
-</dependency></programlisting>Now
- we are ready to run. Right click the "Main" class in IDEA and select "Run 'Main.main()'".
- </para>
- <para>
- <inlinemediaobject>
- <imageobject>
- <imagedata fileref="images/idea-file-run-menu.png"/>
- </imageobject>
- </inlinemediaobject>
- </para>
- <para>
- In the console you'll see output similar to this, indicating that Cayenne stack has been started:
- <screen>INFO: Loading XML configuration resource from file:/.../cayenne-project.xml
-INFO: Loading XML DataMap resource from file:/.../datamap.map.xml
-INFO: loading user name and password.
-INFO: Connecting to 'jdbc:derby:memory:testdb;create=true' as 'null'
-INFO: +++ Connecting: SUCCESS.
-INFO: setting DataNode 'datanode' as default, used by all unlinked DataMaps</screen>
-
- <note>
- <title>How to Configure Cayenne Logging</title>
- <para>Follow the instructions in the logging chapter to tweak verbosity of the logging output.</para>
- </note>
- </para>
- </section>
-</section>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/df1324e4/docs/docbook/getting-started/src/docbkx/object-relational-mapping.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/getting-started/src/docbkx/object-relational-mapping.xml b/docs/docbook/getting-started/src/docbkx/object-relational-mapping.xml
deleted file mode 100644
index ba2b771..0000000
--- a/docs/docbook/getting-started/src/docbkx/object-relational-mapping.xml
+++ /dev/null
@@ -1,184 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<?xml-model href="http://www.oasis-open.org/docbook/xml/5.0/rng/docbook.rng" schematypens="http://relaxng.org/ns/structure/1.0"?>
-<!--
- Licensed to the Apache Software Foundation (ASF) under one or more
- contributor license agreements. See the NOTICE file distributed with
- this work for additional information regarding copyright ownership.
- The ASF licenses this file to you under the Apache License, Version
- 2.0 (the "License"); you may not use this file except in compliance
- with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0 Unless required by
- applicable law or agreed to in writing, software distributed under the
- License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
- CONDITIONS OF ANY KIND, either express or implied. See the License for
- the specific language governing permissions and limitations under the
- License.
--->
-<section xmlns="http://docbook.org/ns/docbook"
- xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0">
- <title>Getting started with Object Relational Mapping (ORM)</title>
- <para> The goal of this section is to learn how to create a simple Object-Relational model with
- CayenneModeler. We will create a complete ORM model for the following database
- schema:</para>
- <para><inlinemediaobject>
- <imageobject>
- <imagedata fileref="images/database-schema.jpg"/>
- </imageobject>
- </inlinemediaobject>
- </para>
- <para>
- <note><para>Very often you'd have an existing database already, and
- it can be quickly imported in Cayenne via "Tools > Reengineer Database
- Schema". This will save you lots of time compared to manual mapping. However
- understanding how to create the mapping by hand is important, so we are showing
- the "manual" approach below.</para></note>
- </para>
- <section xml:id="mapping-db-tables-and-columns">
- <title>Mapping Database Tables and Columns</title>
- <para>Lets go back to CayenneModeler where we have the newly created project open and start
- by adding the ARTIST table. Database tables are called <emphasis role="bold">"DbEntities"</emphasis>
- in Cayenne mapping (those can be actual tables or database views).
- </para>
- <para>Select "datamap" on the left-hand side project tree and click "Create DbEntity" button <inlinemediaobject>
- <imageobject>
- <imagedata fileref="images/icon-dbentity.png"/>
- </imageobject>
- </inlinemediaobject>
- (or use "Project > Create DbEntity" menu). A new DbEntity is created. In "DbEntity
- Name" field enter "ARTIST". Then click on "Create Attribute" button <inlinemediaobject>
- <imageobject>
- <imagedata fileref="images/icon-attribute.png"/>
- </imageobject>
- </inlinemediaobject> on the entity
- toolbar. This action changes the view to the "Attribute"
- tab and adds a new attribute (attribute means a "table column" in this case) called
- "untitledAttr". Let's rename it to ID, make it an <code>INTEGER</code> and make it a PK:
- </para>
- <para><inlinemediaobject>
- <imageobject>
- <imagedata fileref="images/modeler-artistid.png" scalefit="1" width="100%"/>
- </imageobject>
- </inlinemediaobject></para>
- <para>Similarly add NAME <code>VARCHAR(200)</code> and DATE_OF_BIRTH <code>DATE</code> attributes. After that repeat
- this procedure for PAINTING and GALLERY entities to match DB schema shown above.</para>
- <para>
- <note>
- <para>
- Don't forget to save your project periodically to avoid losing your work.
- </para>
- </note>
- </para>
- </section>
- <section xml:id="mapping-db-relationships">
- <title>Mapping Database Relationships</title>
- <para>Now we need to specify relationships between ARTIST, PAINTING and GALLERY tables.
- Start by creating a one-to-many ARTIST/PAINTING relationship:</para>
- <itemizedlist>
- <listitem>
- <para>Select the ARTIST DbEntity on the left and click on the "Properties"
- tab.</para>
- </listitem>
- <listitem>
- <para>Click on "Create Relationship" button on the entity toolbar <inlinemediaobject>
- <imageobject>
- <imagedata fileref="images/icon-relationship.png"/>
- </imageobject>
- </inlinemediaobject> - a relationship called "untitledRel" is created.</para>
- </listitem>
- <listitem>
- <para>Choose the "Target" to be "Painting".</para>
- </listitem>
- <listitem>
- <para>Click on the "Database Mapping" button <inlinemediaobject>
- <imageobject>
- <imagedata fileref="images/icon-edit.png"/>
- </imageobject>
- </inlinemediaobject> - relationship
- configuration dialog is presented. Here you can assign a name to the
- relationship and also its complimentary reverse relationship. This name can be
- anything (this is really a symbolic name of the database referential
- constraint), but it is recommended to use a valid Java identifier, as this will
- save some typing later. We'll call the relationship "paintings" and reverse
- relationship "artist".</para>
- </listitem>
- <listitem>
- <para>Click on "Add" button on the right to add a join</para>
- </listitem>
- <listitem>
- <para>Select "ID" column for the "Source" and "ARTIST_ID" column for the
- target.</para>
- </listitem>
- <listitem>
- <para>Relationship information should now look like this:</para>
- </listitem>
- </itemizedlist>
- <para><inlinemediaobject>
- <imageobject>
- <imagedata fileref="images/modeler-dbrelationship.png" scalefit="1" width="100%"/>
- </imageobject>
- </inlinemediaobject></para>
- <itemizedlist>
- <listitem>
- <para>Click "Done" to confirm the changes and close the dialog.</para>
- </listitem>
- <listitem>
- <para>Two complimentary relationships have been created - from ARTIST to PAINTING
- and back. Still you may have noticed one thing is missing - "paintings"
- relationship should be to-many, but "To Many" checkbox is not checked. Let's
- change that - check the checkbox for "paintings" relationship, and then click on
- PAINTING DbEntity, and uncheck "artist" relationship "To Many" to make the
- reverse relationship "to-one" as it should be.</para>
- </listitem>
- <listitem>
- <para>Repeat the steps above to create a many-to-one relationship from PAINTING to
- GALLERY, calling the relationships pair "gallery" and "paintings".</para>
- </listitem>
- </itemizedlist>
- </section>
- <section xml:id="mapping-java-classes">
- <title>Mapping Java Classes</title>
- <para>Now that the database schema mapping is complete, CayenneModeler can create mappings
- of Java classes (aka "ObjEntities") by deriving everything from DbEntities. At present
- there is no way to do it for the entire DataMap in one click, so we'll do it for each
- table individually.</para>
- <itemizedlist>
- <listitem>
- <para>Select "ARTIST" DbEntity and click on "Create ObjEntity" button <inlinemediaobject>
- <imageobject>
- <imagedata fileref="images/icon-new_objentity.png"/>
- </imageobject>
- </inlinemediaobject> either on the entity toolbar or on the main toolbar. An ObjEntity called
- "Artist" is created with a Java class field set to
- "org.example.cayenne.persistent.Artist". The modeler transformed the database
- names to the Java-friendly names (e.g., if you click on the "Attributes" tab,
- you'll see that "DATE_OF_BIRTH" column was converted to "dateOfBirth" Java class
- attribute).</para>
- </listitem>
- <listitem>
- <para>Select "GALLERY" DbEntity and click on "Create ObjEntity" button again -
- you'll see a "Gallery" ObjEntity created.</para>
- </listitem>
- <listitem>
- <para>Finally, do the same thing for "PAINTING".</para>
- </listitem>
- </itemizedlist>
- <para>Now you need to synchronize relationships. Artist and Gallery entities were created
- when there was no related "Painting" entity, so their relationships were not set. <itemizedlist>
- <listitem>
- <para>Click on the "Artist" ObjEntity. Now click on "Sync ObjEntity with DbEntity" button on
- the toolbar <inlinemediaobject>
- <imageobject>
- <imagedata fileref="images/icon-sync.png"/>
- </imageobject>
- </inlinemediaobject> - you will see the "paintings" relationship
- appear.</para>
- </listitem>
- <listitem>
- <para>Do the same for the "Gallery" entity.</para>
- </listitem>
- </itemizedlist></para>
- <para>Unless you want to customize the Java class and property names (which you can do
- easily) the mapping is complete. </para>
- </section>
-</section>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/df1324e4/docs/docbook/getting-started/src/docbkx/part1.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/getting-started/src/docbkx/part1.xml b/docs/docbook/getting-started/src/docbkx/part1.xml
deleted file mode 100644
index a08bd3e..0000000
--- a/docs/docbook/getting-started/src/docbkx/part1.xml
+++ /dev/null
@@ -1,21 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!--
- Licensed to the Apache Software Foundation (ASF) under one or more
- contributor license agreements. See the NOTICE file distributed with
- this work for additional information regarding copyright ownership.
- The ASF licenses this file to you under the Apache License, Version
- 2.0 (the "License"); you may not use this file except in compliance
- with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0 Unless required by
- applicable law or agreed to in writing, software distributed under the
- License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
- CONDITIONS OF ANY KIND, either express or implied. See the License for
- the specific language governing permissions and limitations under the
- License.
--->
-<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
- xml:id="getting-started-part1" xmlns:xi="http://www.w3.org/2001/XInclude">
- <title>Setting up the environment</title>
- <xi:include href="setup.xml"/>
-</chapter>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/df1324e4/docs/docbook/getting-started/src/docbkx/part2.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/getting-started/src/docbkx/part2.xml b/docs/docbook/getting-started/src/docbkx/part2.xml
deleted file mode 100644
index 9a1f247..0000000
--- a/docs/docbook/getting-started/src/docbkx/part2.xml
+++ /dev/null
@@ -1,25 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<?xml-model href="http://www.oasis-open.org/docbook/xml/5.0/rng/docbook.rng" schematypens="http://relaxng.org/ns/structure/1.0"?>
-<!--
- Licensed to the Apache Software Foundation (ASF) under one or more
- contributor license agreements. See the NOTICE file distributed with
- this work for additional information regarding copyright ownership.
- The ASF licenses this file to you under the Apache License, Version
- 2.0 (the "License"); you may not use this file except in compliance
- with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0 Unless required by
- applicable law or agreed to in writing, software distributed under the
- License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
- CONDITIONS OF ANY KIND, either express or implied. See the License for
- the specific language governing permissions and limitations under the
- License.
--->
-<chapter xmlns="http://docbook.org/ns/docbook"
- xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
- xml:id="getting-started-part2" xmlns:xi="http://www.w3.org/2001/XInclude">
- <title>Learning mapping basics</title>
- <xi:include href="starting-project.xml"/>
- <xi:include href="object-relational-mapping.xml"/>
- <xi:include href="java-classes.xml"/>
-</chapter>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/df1324e4/docs/docbook/getting-started/src/docbkx/part3.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/getting-started/src/docbkx/part3.xml b/docs/docbook/getting-started/src/docbkx/part3.xml
deleted file mode 100644
index cc4bcd9..0000000
--- a/docs/docbook/getting-started/src/docbkx/part3.xml
+++ /dev/null
@@ -1,26 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<?xml-model href="http://www.oasis-open.org/docbook/xml/5.0/rng/docbook.rng" schematypens="http://relaxng.org/ns/structure/1.0"?>
-<!--
- Licensed to the Apache Software Foundation (ASF) under one or more
- contributor license agreements. See the NOTICE file distributed with
- this work for additional information regarding copyright ownership.
- The ASF licenses this file to you under the Apache License, Version
- 2.0 (the "License"); you may not use this file except in compliance
- with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0 Unless required by
- applicable law or agreed to in writing, software distributed under the
- License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
- CONDITIONS OF ANY KIND, either express or implied. See the License for
- the specific language governing permissions and limitations under the
- License.
--->
-<chapter xmlns="http://docbook.org/ns/docbook"
- xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
- xml:id="getting-started-part3" xmlns:xi="http://www.w3.org/2001/XInclude">
- <title>Learning Cayenne API</title>
- <xi:include href="object-context.xml"/>
- <xi:include href="persistent-objects.xml"/>
- <xi:include href="select-query.xml"/>
- <xi:include href="delete.xml"/>
-</chapter>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/df1324e4/docs/docbook/getting-started/src/docbkx/part4.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/getting-started/src/docbkx/part4.xml b/docs/docbook/getting-started/src/docbkx/part4.xml
deleted file mode 100644
index ad87fa9..0000000
--- a/docs/docbook/getting-started/src/docbkx/part4.xml
+++ /dev/null
@@ -1,22 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!--
- Licensed to the Apache Software Foundation (ASF) under one or more
- contributor license agreements. See the NOTICE file distributed with
- this work for additional information regarding copyright ownership.
- The ASF licenses this file to you under the Apache License, Version
- 2.0 (the "License"); you may not use this file except in compliance
- with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0 Unless required by
- applicable law or agreed to in writing, software distributed under the
- License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
- CONDITIONS OF ANY KIND, either express or implied. See the License for
- the specific language governing permissions and limitations under the
- License.
--->
-<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
- xml:id="getting-started-part4" xmlns:xi="http://www.w3.org/2001/XInclude">
- <title>Converting to Web Application</title>
- <xi:include href="webapp.xml"/>
-</chapter>
-
http://git-wip-us.apache.org/repos/asf/cayenne/blob/df1324e4/docs/docbook/getting-started/src/docbkx/persistent-objects.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/getting-started/src/docbkx/persistent-objects.xml b/docs/docbook/getting-started/src/docbkx/persistent-objects.xml
deleted file mode 100644
index 08396e3..0000000
--- a/docs/docbook/getting-started/src/docbkx/persistent-objects.xml
+++ /dev/null
@@ -1,145 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<?xml-model href="http://www.oasis-open.org/docbook/xml/5.0/rng/docbook.rng" schematypens="http://relaxng.org/ns/structure/1.0"?>
-<!--
- Licensed to the Apache Software Foundation (ASF) under one or more
- contributor license agreements. See the NOTICE file distributed with
- this work for additional information regarding copyright ownership.
- The ASF licenses this file to you under the Apache License, Version
- 2.0 (the "License"); you may not use this file except in compliance
- with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0 Unless required by
- applicable law or agreed to in writing, software distributed under the
- License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
- CONDITIONS OF ANY KIND, either express or implied. See the License for
- the specific language governing permissions and limitations under the
- License.
--->
-<section xmlns="http://docbook.org/ns/docbook"
- xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0">
- <title>Getting started with persistent objects</title>
- <para>In this chapter we'll learn about persistent objects, how to customize them and how to
- create and save them in DB.</para>
- <section xml:id="customizing-persistent-objects">
- <title>Inspecting and Customizing Persistent Objects</title>
- <para>Persistent classes in Cayenne implement a DataObject interface. If you inspect any of
- the classes generated earlier in this tutorial (e.g.
- <code>org.example.cayenne.persistent.Artist</code>), you'll see that it extends a class with the name
- that starts with underscore (<code>org.example.cayenne.persistent.auto._Artist</code>), which in turn
- extends from <code>org.apache.cayenne.CayenneDataObject</code>. Splitting each persistent class into
- user-customizable subclass (<code>Xyz</code>) and a generated superclass (<code>_Xyz</code>) is a useful technique
- to avoid overwriting the custom code when refreshing classes from the mapping
- model.</para>
- <para>Let's for instance add a utility method to the Artist class that sets Artist date of
- birth, taking a string argument for the date. It will be preserved even if the model
- changes later:</para>
- <programlisting language="java">package org.example.cayenne.persistent;
-
-import java.time.LocalDate;
-import java.time.format.DateTimeFormatter;
-import java.time.format.DateTimeParseException;
-
-import org.example.cayenne.persistent.auto._Artist;
-
-public class Artist extends _Artist {
-
- static final String DEFAULT_DATE_FORMAT = "yyyyMMdd";
-
- /**
- * Sets date of birth using a string in format yyyyMMdd.
- */
- public void setDateOfBirthString(String yearMonthDay) {
- if (yearMonthDay == null) {
- setDateOfBirth(null);
- } else {
-
- LocalDate date;
- try {
- DateTimeFormatter formatter = DateTimeFormatter.ofPattern(DEFAULT_DATE_FORMAT);
- date = LocalDate.parse(yearMonthDay, formatter);
- } catch (DateTimeParseException e) {
- throw new IllegalArgumentException(
- "A date argument must be in format '"
- + DEFAULT_DATE_FORMAT + "': " + yearMonthDay);
- }
-
- setDateOfBirth(date);
- }
- }
-}</programlisting>
- </section>
- <section xml:id="create-new-objects">
- <title>Create New Objects</title>
- <para>Now we'll create a bunch of objects and save them to the database. An object is
- created and registered with <code>ObjectContext</code> using "<code>newObject</code>" method. Objects <emphasis
- role="bold">must</emphasis> be registered with <code>DataContext</code> to be persisted and to
- allow setting relationships with other objects. Add this code to the "main" method of
- the Main class:</para>
- <programlisting language="java">Artist picasso = context.newObject(Artist.class);
-picasso.setName("Pablo Picasso");
-picasso.setDateOfBirthString("18811025");</programlisting>
- <para>Note that at this point "picasso" object is only stored in memory and is not saved in
- the database. Let's continue by adding a Metropolitan Museum "<code>Gallery</code>" object and a few
- Picasso "Paintings":</para>
- <programlisting language="java">Gallery metropolitan = context.newObject(Gallery.class);
-metropolitan.setName("Metropolitan Museum of Art");
-
-Painting girl = context.newObject(Painting.class);
-girl.setName("Girl Reading at a Table");
-
-Painting stein = context.newObject(Painting.class);
-stein.setName("Gertrude Stein");</programlisting>
- <para>Now we can link the objects together, establishing relationships. Note that in each
- case below relationships are automatically established in both directions (e.g.
- <code>picasso.addToPaintings(girl)</code> has exactly the same effect as
- <code>girl.setToArtist(picasso)</code>).</para>
- <programlisting language="java">picasso.addToPaintings(girl);
-picasso.addToPaintings(stein);
-
-girl.setGallery(metropolitan);
-stein.setGallery(metropolitan);</programlisting>
- <para>Now lets save all five new objects, in a single method call:</para>
- <programlisting language="java">context.commitChanges();</programlisting>
- <para>Now you can run the application again as described in the previous chapter. The new
- output will show a few actual DB operations:</para>
- <screen>org.apache.cayenne.configuration.XMLDataChannelDescriptorLoader load
-INFO: Loading XML configuration resource from file:cayenne-project.xml
-...
-INFO: Connecting to 'jdbc:derby:memory:testdb;create=true' as 'null'
-INFO: +++ Connecting: SUCCESS.
-INFO: setting DataNode 'datanode' as default, used by all unlinked DataMaps
-INFO: Detected and installed adapter: org.apache.cayenne.dba.derby.DerbyAdapter
-INFO: --- transaction started.
-INFO: No schema detected, will create mapped tables
-INFO: CREATE TABLE GALLERY (ID INTEGER NOT NULL, NAME VARCHAR (200), PRIMARY KEY (ID))
-INFO: CREATE TABLE ARTIST (DATE_OF_BIRTH DATE, ID INTEGER NOT NULL, NAME VARCHAR (200), PRIMARY KEY (ID))
-INFO: CREATE TABLE PAINTING (ARTIST_ID INTEGER, GALLERY_ID INTEGER, ID INTEGER NOT NULL,
- NAME VARCHAR (200), PRIMARY KEY (ID))
-INFO: ALTER TABLE PAINTING ADD FOREIGN KEY (ARTIST_ID) REFERENCES ARTIST (ID)
-INFO: ALTER TABLE PAINTING ADD FOREIGN KEY (GALLERY_ID) REFERENCES GALLERY (ID)
-INFO: CREATE TABLE AUTO_PK_SUPPORT (
- TABLE_NAME CHAR(100) NOT NULL, NEXT_ID BIGINT NOT NULL, PRIMARY KEY(TABLE_NAME))
-INFO: DELETE FROM AUTO_PK_SUPPORT WHERE TABLE_NAME IN ('ARTIST', 'GALLERY', 'PAINTING')
-INFO: INSERT INTO AUTO_PK_SUPPORT (TABLE_NAME, NEXT_ID) VALUES ('ARTIST', 200)
-INFO: INSERT INTO AUTO_PK_SUPPORT (TABLE_NAME, NEXT_ID) VALUES ('GALLERY', 200)
-INFO: INSERT INTO AUTO_PK_SUPPORT (TABLE_NAME, NEXT_ID) VALUES ('PAINTING', 200)
-INFO: SELECT NEXT_ID FROM AUTO_PK_SUPPORT WHERE TABLE_NAME = ? FOR UPDATE [bind: 1:'ARTIST']
-INFO: SELECT NEXT_ID FROM AUTO_PK_SUPPORT WHERE TABLE_NAME = ? FOR UPDATE [bind: 1:'GALLERY']
-INFO: SELECT NEXT_ID FROM AUTO_PK_SUPPORT WHERE TABLE_NAME = ? FOR UPDATE [bind: 1:'PAINTING']
-INFO: INSERT INTO GALLERY (ID, NAME) VALUES (?, ?)
-INFO: [batch bind: 1->ID:200, 2->NAME:'Metropolitan Museum of Art']
-INFO: === updated 1 row.
-INFO: INSERT INTO ARTIST (DATE_OF_BIRTH, ID, NAME) VALUES (?, ?, ?)
-INFO: [batch bind: 1->DATE_OF_BIRTH:'1881-10-25 00:00:00.0', 2->ID:200, 3->NAME:'Pablo Picasso']
-INFO: === updated 1 row.
-INFO: INSERT INTO PAINTING (ARTIST_ID, GALLERY_ID, ID, NAME) VALUES (?, ?, ?, ?)
-INFO: [batch bind: 1->ARTIST_ID:200, 2->GALLERY_ID:200, 3->ID:200, 4->NAME:'Gertrude Stein']
-INFO: [batch bind: 1->ARTIST_ID:200, 2->GALLERY_ID:200, 3->ID:201, 4->NAME:'Girl Reading at a Table']
-INFO: === updated 2 rows.
-INFO: +++ transaction committed.
-</screen>
- <para>So first Cayenne creates the needed tables (remember, we used
- "<code>CreateIfNoSchemaStrategy</code>"). Then it runs a number of inserts, generating primary keys
- on the fly. Not bad for just a few lines of code.</para>
- </section>
-</section>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/df1324e4/docs/docbook/getting-started/src/docbkx/select-query.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/getting-started/src/docbkx/select-query.xml b/docs/docbook/getting-started/src/docbkx/select-query.xml
deleted file mode 100644
index 72ee254..0000000
--- a/docs/docbook/getting-started/src/docbkx/select-query.xml
+++ /dev/null
@@ -1,60 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<?xml-model href="http://www.oasis-open.org/docbook/xml/5.0/rng/docbook.rng" schematypens="http://relaxng.org/ns/structure/1.0"?>
-<!--
- Licensed to the Apache Software Foundation (ASF) under one or more
- contributor license agreements. See the NOTICE file distributed with
- this work for additional information regarding copyright ownership.
- The ASF licenses this file to you under the Apache License, Version
- 2.0 (the "License"); you may not use this file except in compliance
- with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0 Unless required by
- applicable law or agreed to in writing, software distributed under the
- License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
- CONDITIONS OF ANY KIND, either express or implied. See the License for
- the specific language governing permissions and limitations under the
- License.
--->
-<section xmlns="http://docbook.org/ns/docbook"
- xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0">
- <title>Selecting Objects</title>
- <para>This chapter shows how to select objects from the database using <code>ObjectSelect</code> query. </para>
- <section xml:id="introducing-select-query">
- <title>Introducing ObjectSelect</title>
- <para>It was shown before how to persist new objects. Cayenne queries are used to access
- already saved objects. The primary query type used for selecting objects is <code>ObjectSelect</code>.
- It can be mapped in CayenneModeler or created
- via the API. We'll use the latter approach in this section. We don't have too much data
- in the database yet, but we can still demonstrate the main principles below.</para>
- <itemizedlist>
- <listitem>
- <para>Select all paintings (the code, and the log output it generates):</para>
- </listitem>
- </itemizedlist>
- <programlisting language="java">List<Painting> paintings1 = ObjectSelect.query(Painting.class).select(context); </programlisting>
- <screen>INFO: SELECT t0.GALLERY_ID, t0.ARTIST_ID, t0.NAME, t0.ID FROM PAINTING t0
-INFO: === returned 2 rows. - took 18 ms.</screen>
- <itemizedlist>
- <listitem>
- <para>Select paintings that start with "<code>gi</code>", ignoring case:</para>
- </listitem>
- </itemizedlist>
- <programlisting language="java">List<Painting> paintings2 = ObjectSelect.query(Painting.class)
- .where(Painting.NAME.likeIgnoreCase("gi%")).select(context); </programlisting>
- <screen>INFO: SELECT t0.GALLERY_ID, t0.NAME, t0.ARTIST_ID, t0.ID FROM PAINTING t0 WHERE UPPER(t0.NAME) LIKE UPPER(?)
- [bind: 1->NAME:'gi%'] - prepared in 6 ms.
-INFO: === returned 1 row. - took 18 ms.</screen>
- <itemizedlist>
- <listitem>
- <para>Select all paintings done by artists who were born more than a 100 years
- ago:</para>
- </listitem>
- </itemizedlist>
- <programlisting language="java">List<Painting> paintings3 = ObjectSelect.query(Painting.class)
- .where(Painting.ARTIST.dot(Artist.DATE_OF_BIRTH).lt(LocalDate.of(1900,1,1)))
- .select(context); </programlisting>
- <screen>INFO: SELECT t0.GALLERY_ID, t0.NAME, t0.ARTIST_ID, t0.ID FROM PAINTING t0 JOIN ARTIST t1 ON (t0.ARTIST_ID = t1.ID)
- WHERE t1.DATE_OF_BIRTH < ? [bind: 1->DATE_OF_BIRTH:'1911-01-01 00:00:00.493'] - prepared in 7 ms.
-INFO: === returned 2 rows. - took 25 ms.</screen>
- </section>
-</section>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/df1324e4/docs/docbook/getting-started/src/docbkx/setup.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/getting-started/src/docbkx/setup.xml b/docs/docbook/getting-started/src/docbkx/setup.xml
deleted file mode 100644
index f3f9774..0000000
--- a/docs/docbook/getting-started/src/docbkx/setup.xml
+++ /dev/null
@@ -1,36 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<?xml-model href="http://www.oasis-open.org/docbook/xml/5.0/rng/docbook.rng" schematypens="http://relaxng.org/ns/structure/1.0"?>
-<!--
- Licensed to the Apache Software Foundation (ASF) under one or more
- contributor license agreements. See the NOTICE file distributed with
- this work for additional information regarding copyright ownership.
- The ASF licenses this file to you under the Apache License, Version
- 2.0 (the "License"); you may not use this file except in compliance
- with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0 Unless required by
- applicable law or agreed to in writing, software distributed under the
- License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
- CONDITIONS OF ANY KIND, either express or implied. See the License for
- the specific language governing permissions and limitations under the
- License.
--->
-<section xmlns="http://docbook.org/ns/docbook"
- xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0">
- <title>Setup</title>
- <para> The goal of this chapter of the tutorial is to install (or check that you already have
- installed) a minimally needed set of software to build a Cayenne application. </para>
- <section xml:id="install-java">
- <title>Install Java</title>
- <para>
- Obviously, JDK has to be installed. Cayenne 4.0 requires JDK 1.7 or newer.
- </para>
- </section>
- <section xml:id="install-idea">
- <title>Install IntelliJ IDEA</title>
- <para>
- Download and install IntelliJ IDEA Community Edition.
- This tutorial is based on version 2016.3, still it should work with any recent IntelliJ IDEA version.
- </para>
- </section>
-</section>
http://git-wip-us.apache.org/repos/asf/cayenne/blob/df1324e4/docs/docbook/getting-started/src/docbkx/starting-project.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/getting-started/src/docbkx/starting-project.xml b/docs/docbook/getting-started/src/docbkx/starting-project.xml
deleted file mode 100644
index c883d5a..0000000
--- a/docs/docbook/getting-started/src/docbkx/starting-project.xml
+++ /dev/null
@@ -1,165 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<?xml-model href="http://www.oasis-open.org/docbook/xml/5.0/rng/docbook.rng" schematypens="http://relaxng.org/ns/structure/1.0"?>
-<!--
- Licensed to the Apache Software Foundation (ASF) under one or more
- contributor license agreements. See the NOTICE file distributed with
- this work for additional information regarding copyright ownership.
- The ASF licenses this file to you under the Apache License, Version
- 2.0 (the "License"); you may not use this file except in compliance
- with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0 Unless required by
- applicable law or agreed to in writing, software distributed under the
- License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
- CONDITIONS OF ANY KIND, either express or implied. See the License for
- the specific language governing permissions and limitations under the
- License.
--->
-<section xmlns="http://docbook.org/ns/docbook"
- xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0">
- <title>Starting a project</title>
- <para>
- The goal of this chapter is to create a new Java project in IntelliJ IDEA
- containing a basic Cayenne mapping. It presents an introduction to
- CayenneModeler GUI tool, showing how to create the initial mapping
- objects: <code>DataDomain</code>, <code>DataNode</code>, <code>DataMap</code>.
- </para>
- <section xml:id="create-new-project">
- <title>Create a new Project in IntelliJ IDEA</title>
- <para>
- In IntelliJ IDEA select "<guimenu>File</guimenu> > <guimenuitem>New</guimenuitem> > <guimenuitem>Project...</guimenuitem>" and then
- select "Maven" and click "Next".
- In the dialog shown on the screenshot below, fill the "Group Id"
- and "Artifact Id" fields and click "Next".
- </para>
- <para>
- <inlinemediaobject>
- <imageobject>
- <imagedata fileref="images/tutorial-idea-project.png" scalefit="1" width="100%"/>
- </imageobject>
- </inlinemediaobject>
- </para>
- <para>
- On next dialog screen you can customize directory for your project and click "Finish".
- Now you should have a new empty project.
- </para>
- </section>
- <section xml:id="download-and-start-cayenne-modeler">
- <title>Download and Start CayenneModeler</title>
- <para>
- Although later in this tutorial we'll be using Maven to include Cayenne
- runtime jars in the project, you'll still need to download Cayenne to
- get access to the CayenneModeler tool.
- </para>
- <para>
- <note>
- <para>If you are really into Maven, you can start
- CayenneModeler from Maven too. We'll do it in a more traditional way
- here.</para>
- </note>
- </para>
- <para>Download the <link xlink:href="http://cayenne.apache.org/download.html">latest release</link>. Unpack the distribution somewhere in the file system and
- start CayenneModeler, following platform-specific instructions. On most platforms it is
- done simply by doubleclicking the Modeler icon. The welcome screen of the Modeler looks
- like this:
- </para>
- <para>
- <inlinemediaobject>
- <imageobject>
- <imagedata fileref="images/modeler-started.png" scalefit="1" width="100%"/>
- </imageobject>
- </inlinemediaobject>
- </para>
- </section>
- <section xml:id="create-new-mapping-project">
- <title>Create a New Mapping Project in CayenneModeler</title>
- <para>Click on the "New Project" button on Welcome screen. A new mapping project will appear
- that contains a single <emphasis role="bold">DataDomain</emphasis>. The meaning of a
- DataDomain is explained elsewhere in the User Guide. For now it is sufficient to
- understand that DataDomain is the root of your mapping project.
- </para>
- </section>
- <section xml:id="create-datanode">
- <title>Create a DataNode</title>
- <para>The next project object you will create is a <emphasis role="bold"
- >DataNode</emphasis>. DataNode is a descriptor of a single database your application
- will connect to. Cayenne mapping project can use more than one database, but for now,
- we'll only use one. With "project" selected on the left, click on "Create DataNode"
- button <inlinemediaobject>
- <imageobject>
- <imagedata fileref="images/icon-node.png"/>
- </imageobject>
- </inlinemediaobject> on the toolbar (or select "Project > Create DataNode" from the menu).
- </para>
- <para>A new DataNode is displayed. Now you need to specify JDBC connection parameters. For
- an in-memory Derby database you can enter the following settings: <itemizedlist>
- <listitem>
- <para>JDBC Driver: org.apache.derby.jdbc.EmbeddedDriver</para>
- </listitem>
- <listitem>
- <para>DB URL: jdbc:derby:memory:testdb;create=true</para>
- </listitem>
- </itemizedlist></para>
- <para>
- <note><para>We are creating an in-memory database here. So when
- you stop your application, all the data will be lost. In most real-life
- cases you'll be connecting to a database that actually persists its data on
- disk, but an in-memory DB will do for the simple tutorial.</para>
- </note>
- </para>
- <para>Also you will need to change "Schema Update Strategy". Select
- "<code>org.apache.cayenne.access.dbsync.CreateIfNoSchemaStrategy</code>" from the dropdown, so that
- Cayenne creates a new schema on Derby based on the ORM mapping when the application
- starts.</para>
- <para>
- <inlinemediaobject>
- <imageobject>
- <imagedata fileref="images/base-datanode.png" scalefit="1" width="100%"/>
- </imageobject>
- </inlinemediaobject>
- </para>
- </section>
- <section xml:id="create-datamap">
- <title>Create a DataMap</title>
- <para>Now you will create a <emphasis role="bold">DataMap</emphasis>. DataMap is an object
- that holds all the mapping information. To create it, click on "Create DataMap" button
- <inlinemediaobject>
- <imageobject>
- <imagedata fileref="images/icon-datamap.png"/>
- </imageobject>
- </inlinemediaobject>
- (or select a corresponding menu item). Note that the newly created DataMap is
- automatically linked to the DataNode that you created in the previous step. If there is
- more than one DataNode, you may need to link a DataMap to the correct node manually. In
- other words a DataMap within DataDomain must point to a database described by the
- map.
- </para>
- <para>You can leave all the DataMap defaults unchanged except for one - "Java Package".
- Enter "<code>org.example.cayenne.persistent</code>". This name will later be used for all persistent
- classes.
- </para>
- <para>
- <inlinemediaobject>
- <imageobject>
- <imagedata fileref="images/base-datamap.png" scalefit="1" width="100%"/>
- </imageobject>
- </inlinemediaobject>
- </para>
- </section>
- <section xml:id="save-project">
- <title>Save the Project</title>
- <para>Before you proceed with the actual mapping, let's save the project. Click on "Save"
- button in the toolbar and navigate to the "<code>tutorial</code>" IDEA project folder that was
- created earlier in this section and its "<code>src/main/resources</code>" subfolder and save the
- project there. Now go back to IDEA and you will see two Cayenne XML files.</para>
- <para><inlinemediaobject>
- <imageobject>
- <imagedata fileref="images/idea-xmlfiles.png"/>
- </imageobject>
- </inlinemediaobject></para>
- <para>Note that the location of the XML files is not coincidental. Cayenne runtime looks for
- "<code>cayenne-*.xml</code>" file in the application <code>CLASSPATH</code> and "<code>src/main/resources</code>" folder should
- already be a "class folder" in IDEA for our project (and is also a standard location
- that Maven would copy to a jar file, if we were using Maven from command-line).</para>
- </section>
-</section>