<?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 castor-${RELEASE}-examples.zip 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, please issue one of the following
           commands:</p>
          
          <code-panel>
  unzip castor-1.0M3-examples.zip</code-panel> 

          <p>or</p>

          <code-panel>
  jar xvf castor-1.0M3-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 downloaded,
           you'll find a castor-1.0M3-examples.jar. In addition, a directory named
           'lib' had been created, where you'll find several JAR files required to
           run the samples.</p> 
           
        <p>To execute he samples, please issue the following command:</p>
        
        <code-panel>
  java -jar castor-1.0M3-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 artefacts (JDOManager, Database, etc.) against this
         embedded database.</p>
         
      <p>In other words, everything is self-contained, and there is no need anymore
         to install a database, create a database schema and all the required tables.
         Everything required is initiated and setup 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>
