2.2. Getting Started

2.2.1. Configuring the Data Store

Let's compile the initial classes and see them in action. To do so, we must compile the .java files, as we would with any Java project, and then pass the resulting classes through the JDO enhancer:


Be sure that your CLASSPATH is set correctly. Please see Section 2.9, “Windows Installation (no installer -- zip file)” of Part I of this manual for Windows, or Section 2.10, “POSIX (Linux, Solaris, Mac OS X, Windows with cygwin, etc.) Installation” of Part I of this manual for POSIX (Linux, Solaris, Cygwin, etc.). Detailed information on which libraries are needed can be found in Appendix G, Development and Runtime Libraries. Note, also, that your Kodo install directory should be in the CLASSPATH, as the tutorial classes are located in the tutorial directory under your Kodo install directory, and are in the tutorial package.

  1. Change to the tutorial directory.

    All examples throughout the tutorial assume that you are in this directory.

  2. Examine Animal.java, Dog.java , and SeedDatabase.java

    These files are good examples of the simplicity JDO engenders. As noted earlier, persisting an object or manipulating an object's persistent data requires almost no JDO-specific code. For a very simple example of creating persistent objects, please see the main method of SeedDatabase.java . Note the objects are created with normal Java constructors. The files Animal.java and Dog.java are also good examples of how JDO allows you to manipulate persistent data without writing any specific JDO code.

  3. Compile the .java files.

    javac *.java

    You can use any java compiler instead of javac.

  4. Enhance the JDO classes.

    jdoc package.jdo

    This step runs the Kodo JDO enhancer on the package.jdo file mentioned above. The package.jdo file contains an enumeration of all the classes that should be JDO enhanced. The Kodo JDO enhancer will examine the metadata defined in this file and enhance all classes listed in it appropriately. See Section 5.5, “Enhancement” of the Reference Guide for more information on the JDO enhancer.

2.2.1. Configuring the Data Store

Now that we've compiled the source files and enhanced the JDO classes, we're ready to set up the database. Hypersonic SQL, a pure Java relational database, is included in this distribution. We have included this database because it is simple to set up and has a small memory footprint; however, you can use this tutorial with any of the relational databases that we support. You can also write your own plugin for any database that we do not support. For the sake of simplicity, this tutorial only describes how to set up connectivity to a Hypersonic SQL database. For more information on how to connect to a different database or how to add support for other databases, see Chapter 4, JDBC of the Reference Guide.

  1. Create the object-relational mappings and database schema.

    mappingtool -action refresh package.jdo

    This command creates object-relational mappings for the classes listed in package.jdo, and at the same time propagates the necessary schema to the database configured in kodo.properties . If you are using the default Hypersonic SQL setup, the first time you run the mapping tool Hypersonic will create tutorial_database.properties and tutorial_database.script database files in your current directory. To delete the database, just delete these files.

    By default, Kodo stores object-relational mapping information in .mapping files. As you will see in the Reverse Mapping Tool Tutorial, you can also configure Kodo to store object-relational mappings in your JDO metadata files or in a database table. Chapter 7, Object-Relational Mapping of the Reference Guide describes your mapping options in detail.

    If you'd like to see the mapping information Kodo has just created for the classes listed in package.jdo, examine the package.mapping file. Again, Chapter 7, Object-Relational Mapping of the Reference Guide will help you understand mapping XML in detail, should the need ever arise. Most Kodo development does not require any knowledge of mappings.

    If you are curious, you can also view view the schema Kodo created for the tutorial classes with Kodo's schema generator tool:

    schemagen -file tmp.schema

    This will create a tmp.schema file with an XML representation of the database schema. The XML should be self explanatory; see Section 8.3, “XML Schema Format” of the Reference Guide for details. You may delete the tmp.schema file before proceeding.

  2. Populate the database with sample data.

    java tutorial.SeedDatabase

Congratulations! You have now created a JDO-accessible persistent store, and seeded it with some sample data.