<?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">
    <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 "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 &gt;
        Create Database Schema".
    </para>
    <section xml:id="creating-java-classes">
        <title>Creating Java Classes</title>
        <itemizedlist>
            <listitem>
                <para>Select "Tools &gt; 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 "src/main/java" folder under your Eclipse
                    project folder (this is a "peer" location to the cayenne-*.xml location we
                    selected before).</para>
            </listitem>
            <listitem>
                <para>Click on "Entities" 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" project and select "Refresh" - 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 Eclipse.
            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 pom.xml file. The
            resulting POM should look like
            this:<programlisting>&lt;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"&gt;
    &lt;modelVersion&gt;4.0.0&lt;/modelVersion&gt;
    &lt;groupId&gt;org.example.cayenne&lt;/groupId&gt;
    &lt;artifactId&gt;tutorial&lt;/artifactId&gt;
    &lt;version&gt;0.0.1-SNAPSHOT&lt;/version&gt;

    &lt;dependencies&gt;
        &lt;dependency&gt;
            &lt;groupId&gt;org.apache.cayenne&lt;/groupId&gt;
            &lt;artifactId&gt;cayenne-server&lt;/artifactId&gt;
   &lt;!-- Here specify the version of Cayenne you are actually using --&gt;
            &lt;version&gt;3.1M3&lt;/version&gt;
        &lt;/dependency&gt;
    &lt;/dependencies&gt;
&lt;/project&gt;</programlisting></para>
        <para>Your computer must be connected to the internet. Once you save the pom.xml, Eclipse
            will download the needed Cayenne jar file and add it to the project build path. As a
            result, all the errors should disappear.</para>
        <para><inlinemediaobject>
                <imageobject>
                    <imagedata fileref="images/eclipse-generatedclasses.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. Artist)
            and a subclass (e.g. Artist). 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 "org.example.cayenne.persistent" package - those will never be overwritten by the
            class generator.</para>
        <para>
            <note>
                <para><emphasis role="bold">Class Generation
                    Hint</emphasis> 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>
</chapter>
