# Castor JDO - First steps

## Introduction

This guide assumes that you do not have any experience with CASTOR JDO, but would like to make your first steps into the world of persistence and object/relation mapping tools. The following sections show how to setup and configure Castor JDO so that it is possible to perform persistence operations on the domain objects presented.

## Sample domain objects

The sample domain objects used in here basically define a `Catalogue`, which is a collection of `Product`s.

    public class Catalogue {

       private long id;
       private List products = new ArrayList();

       public long getId() { ... }
       public void setId(long id) { ... }

       public String getProducts() { ... }
       public void setProducts(List products) { ... }

    }

    public class Product {

       private long id;

       private String description;

       public long getId() { ... }
       public void setId(long id) { ... }

       public String getDescription() { ... }
       public void setDescription(String description) { ... }

    }

In order to be able to perform any persistence operation (such as loading products, deleting products from a catalogue, ...) on these domain objects through Castor JDO, a Castor JDO mapping has to be provided, defining class and field level mappings for the Java classes given and their members:

    <class name="org.castor.sample.Catalogue">
       <map-to table="catalogue"/>
       <field name="id" type="long">
          <sql name="id" type="integer" />
       </field>
       <field name="products" type="org.castor.sample.Product" collection="arraylist">
          <sql many-key="c_id" />
       </field>
    </class>

    <class name="org.castor.sample.Product">
       <map-to table="product"/>
       <field name="id" type="long">
          <sql name="id" type="integer" />
       </field>
       <field name="description" type="string">
          <sql name="desc" type="varchar" />
       </field>
    </class>

## Using Castor JDO for the first time

To e.g. load a given `Catalogue` instance as defined by its identity, and all its associated `Product` instances, the following code could be used, based upon the Castor-specific interfaces `JDOManager` and `Database`.

    JDOManager.loadConfiguration("jdo-conf.xml");
    JDOManager jdoManager = JDOmanager.createInstance("sample");

    Database database = jdoManager.getDatabase();
    database.begin();
    Catalogue catalogue = database.load(catalogue.class, new Long(1));
    database.commit();
    database.close();

For brevity, exception handling has been ommitted completely. But is is quite obvious that - when using such code fragments again and again, to e.g. implement various methods of a DAO - there's a lot of redundant code that needed to be written again and again - and exception handling is adding some additional complexity here as well.

## JDO configuration

As shown in above code example, before you can perform any persistence operations on your domain objects, Castor JDO has to be configured by the means of a JDO configuration file. as part of this JDO configuration, the user defines one or more databases and everything required to connect to this database (user credentials, JDBC connection string, ....).

A valid JDO configuration file for HSQL looks as follows:

    <?xml version="1.0" ?>
    <!DOCTYPE jdo-conf PUBLIC "-//EXOLAB/Castor JDO Configuration DTD Version 1.0//EN" "http://castor.org/jdo-conf.dtd">
    <jdo-conf>
      <database name="hsqldb" engine="hsql">
        <driver class-name="org.hsqldb.jdbcDriver" url="jdbc:hsqldb:hsql://localhost:9002/dbname">
          <param name="user" value="sa"/>
          <param name="password" value=""/>
        </driver>
        <mapping href="mapping.xml"/>
      </database>
      <transaction-demarcation mode="local"/>
    </jdo-conf>