<?xml version="1.0" encoding="ISO-8859-1"?>
<document url="http://castor.codehaus.org/jdo-self-executable-examples.xml">

  <properties>
    <title>Running the self-executable Castor JDO examples</title>
    <author email="werner DOT guttmann AT gmx DOT net">Werner Guttmann</author>
    <abstract>
      Outlines how to run the self-executable Castor JDO examples.
    </abstract>
    <status>Draft</status>
  </properties>

  <body>
    <title>Running the self-executable Castor JDO examples</title>

    <p>
      As of release 1.0M3, the Castor JDO examples have been packaged in a
      new way and are available for download at the
      <a href="download.html">download page</a>. In the following sections, we
      explain the steps required to unpack this new archive, and how to execute
      the tests.
    </p>

    <section title="Download the castor-$RELEASE-examples.zip archive">

      <p>
        In order to be able to run the new Castor JDO examples, please download
        the new <tt>castor-</tt>${RELEASE}<tt>-examples.zip</tt> from the
        <a href="download.html">download page</a> and put it into some location
        on your computer.
      </p>

    </section>

    <section title="Unpack the ZIP file">

      <p>
        To unpack the ZIP file downloaded, issue one of the following commands:
      </p>

      <code-panel>
  unzip castor-1.1M2-examples.zip</code-panel>

      <p>or</p>

      <code-panel>
  jar xvf castor-1.1M2-examples.zip</code-panel>

      <p>
        You can now run the examples using the directions provided in the
        next section.
      </p>

    </section>

    <section title="Running the Castor JDO samples">

      <p>
        In the directory where you have unpacked the ZIP file you'll find a
        castor-1.1M2-examples.jar. In addition, you'll find a directory named
        <tt>lib</tt> where you'll find several JAR files required to
        run the samples.
      </p>

      <p>To execute the samples, issue the following command:</p>

      <code-panel>
  java -jar castor-1.1M2-examples.jar</code-panel>

      <p>
        ... et voila ! You'll see various lines of logging output flashing
        by whilst the Castor JDO samples are executing against a database.
      </p>

    </section>

    <section title="What happens">

      <p>
        The Castor JDO sample will test persistence between a set of Java
        classes (Product, ProductGroup, ProductDetail, etc.) and perform this
        code against an Apache Derby instance as RDBMS. For this purpose, the
        sample code will start an embedded Derby instance on the fly, create
        the required tables, and then continue to execute several code
        fragments using various Castor JDO artifacts (JDOManager, Database,
        etc.) against this embedded database.
      </p>

      <p>
        In other words, everything is self-contained and there is no need to
        install a database, create a database schema, or create database tables.
        Everything required for the tests is initiated and set up from within
        the sample code.
      </p>

    </section>

    <section title="Hints">

      <ul>
        <li>
          If it is not set yet, you might have to set the <tt>JAVA_HOME</tt>
          environment variable, and add the $JAVA_HOME/bin directory to
          your path.
        </li>
      </ul>

    </section>

  </body>
</document>
