| Title: Tutorial Starting Project |
| |
| <P>The goal of this section is to create a new Java project in Eclipse containing a basic Cayenne mapping. It presents an introduction to CayenneModeler GUI tool, showing how to create the initial mapping objects: DataDomain, DataNode, DataMap.</P> |
| |
| <H3><A name="TutorialStartingProject-CreateanewProjectinEclipse"></A>Create a new Project in Eclipse</H3> |
| |
| <P>In Eclipse select <TT>"File > New > Other..."</TT> and then <TT>"Maven > Maven Project"</TT>. Click "Next". On the following screen check "Create a simple project" checkbox and click "Next" again. In the dialog shown on the screenshot below, fill the "Group Id" and "Artifact Id" fields and click "Finish". <BR> |
| <SPAN class="image-wrap" style=""><IMG src="tutorial-starting-project.data/tutorial-eclipse-project.png" style="border: 0px solid black"></SPAN></P> |
| |
| <P>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" project, select <TT>"Properties > Java Compiler"</TT> 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).</P> |
| |
| <H3><A name="TutorialStartingProject-DownloadandStartCayenneModeler"></A>Download and Start CayenneModeler</H3> |
| |
| <P>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. </P> |
| |
| <DIV class="panelMacro"><TABLE class="noteMacro"><COLGROUP><COL width="24"><COL></COLGROUP><TR><TD valign="top"><IMG src="http://cayenne.apache.org/docs/3.0/images/icons/emoticons/warning.gif" width="16" height="16" align="absmiddle" alt="" border="0"></TD><TD>If you are really into Maven, you can <A href="maven2-modeler.html" title="maven2-modeler">start CayenneModeler from Maven</A> if you wish. We'll do it in a more traditional way here.</TD></TR></TABLE></DIV> |
| |
| <P>Download the latest release <A href="http://cayenne.apache.org/download.html" class="external-link" rel="nofollow">from here</A>. Unpack the distribution somewhere in the file system and start CayenneModeler, following <A href="running-cayennemodeler.html" title="Running CayenneModeler">platform-specific instructions</A>. On most platforms it is done simply by doubleclicking the Modeler icon. The welcome screen of the Modeler looks like this:</P> |
| |
| <P><SPAN class="image-wrap" style=""><IMG src="tutorial-starting-project.data/modeler-started.png" style="border: 0px solid black"></SPAN></P> |
| |
| <H3><A name="TutorialStartingProject-CreateaNewMappingProjectinCayenneModeler"></A>Create a New Mapping Project in CayenneModeler</H3> |
| |
| <P>Click on the "New Project" button on Welcome screen. A new mapping project will appear that contains a single <B>DataDomain</B>. 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.</P> |
| |
| <H3><A name="TutorialStartingProject-CreateaDataNode"></A>Create a DataNode</H3> |
| |
| <P>The next project object you will create is a <B>DataNode</B>. 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 "UntitledDomain" selected on the left, click on "Create DataNode" button on the toolbar (or select <TT>"Project > Create DataNode"</TT> from the menu.</P> |
| |
| <P>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: </P> |
| |
| <UL> |
| <LI>JDBC Driver: <TT>org.apache.derby.jdbc.EmbeddedDriver</TT></LI> |
| <LI>DB URL: <TT>jdbc:derby:memory:testdb;create=true</TT></LI> |
| </UL> |
| |
| |
| <DIV class="panelMacro"><TABLE class="noteMacro"><COLGROUP><COL width="24"><COL></COLGROUP><TR><TD valign="top"><IMG src="http://cayenne.apache.org/docs/3.0/images/icons/emoticons/warning.gif" width="16" height="16" align="absmiddle" alt="" border="0"></TD><TD>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.</TD></TR></TABLE></DIV> |
| |
| <P>Also you will need to change "Schema Update Strategy". Select <TT>"org.apache.cayenne.access.dbsync.CreateIfNoSchemaStrategy"</TT> from the dropdown, so that Cayenne creates a new schema on Derby based on the ORM mapping when the application starts.</P> |
| |
| <P><SPAN class="image-wrap" style=""><IMG src="tutorial-starting-project.data/base-datanode.png" style="border: 0px solid black"></SPAN></P> |
| |
| |
| <H3><A name="TutorialStartingProject-CreateaDataMap"></A>Create a DataMap</H3> |
| |
| <P>Now you will create a <B>DataMap</B>. DataMap is an object that holds all the mapping information. To create it, click on "Create DataMap" button (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.</P> |
| |
| <P>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.</P> |
| |
| <P><SPAN class="image-wrap" style=""><IMG src="tutorial-starting-project.data/base-datamap.png" style="border: 0px solid black"></SPAN></P> |
| |
| <H3><A name="TutorialStartingProject-SavetheProject"></A>Save the Project</H3> |
| |
| <P>Before you proceed with the actual mapping, let's save the project. Click on "Save" button in the toolbar and navigate to the <TT>"tutorial"</TT> Eclipse project folder that was created earlier in this section and its <TT>"src/main/resources"</TT> subfolder and save the project there. Now go back to Eclipse, right click on "tutorial" project and select "Refresh", you will see three Cayenne XML files.</P> |
| |
| <P><SPAN class="image-wrap" style=""><IMG src="tutorial-starting-project.data/eclipse-xmlfiles.png" style="border: 0px solid black"></SPAN></P> |
| |
| <P>Note that the location of the XML files is not coincidental. Cayenne runtime looks for <TT>"cayenne.xml"</TT> file in the application CLASSPATH and <TT>"src/main/resources"</TT> folder should already be a "class folder" in Eclipse 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).</P> |
| |
| <HR> |
| <P><B>Next Step: <A href="tutorial-object-relational-mapping.html" title="Tutorial Object Relational Mapping">Tutorial Object Relational Mapping</A></B></P> |
| <HR> |
