|  |  |  | License Codehaus OpenEJB OpenJMS OpenORB Tyrex

Old releases
General
Release 1.3
Release 1.3rc1
Release 1.2

Main
Home
About
Features
Download
Dependencies
Reference guide
Publications
JavaDoc
Maven 2 support
Maven 2 archetypes
DTD & Schemas
Recent HTML changes
News Archive
RSS news feed
Project Wiki

Development/Support
Mailing Lists
SVN/JIRA
Contributing
Support
Continuous builds
Prof. services

Related projects
Spring ORM support
Spring XML factories
WS frameworks

XML
XML

XML Code Generator
XML Code Generator

JDO
Introduction
First steps
Using JDO
JDO Config
Types
JDO Mapping
JDO FAQ
JDO Examples
JDO HOW-TOs
Tips & Tricks
Other Features
JDO sample JAR

Tools
Schema generator

Advanced JDO
Caching
OQL
Trans. & Locks
Design
KeyGen
Long Trans.
Nested Attrs.
Pooling Examples
LOBs
Best practice

DDL Generator
Using DDL Generator
Properties
Ant task
Type Mapping

More
The Examples
3rd Party Tools
JDO Tests
XML Tests
Configuration

About
License
User stories
Contributors
Marketplace
Status, Todo
Changelog
Library
Contact
Project Name

## Castor JDO - First steps

Introduction
Sample domain objects
Using Castor JDO for the first time
JDO configuration

## 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>

<notice> Copyright © 1999-2005 ExoLab Group, Intalio Inc., and Contributors. All rights reserved. </notice>
<notice> Java, EJB, JDBC, JNDI, JTA, Sun, Sun Microsystems are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and in other countries. XML, XML Schema, XSLT and related standards are trademarks or registered trademarks of MIT, INRIA, Keio or others, and a product of the World Wide Web Consortium. All other product names mentioned herein are trademarks of their respective owners. </notice>