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). +
