<?xml version="1.0" encoding="ISO-8859-1"?>
<document url="http://castor.org/jdo-examples.xml">
  <properties>
    <title>Castor JDO - An introduction</title>
    <author email="werner DOT guttmann AT gmx DOT net">Werner Guttmann</author>
    <abstract>
       Castor JDO - An introduction
    </abstract>
    <status>Final</status>
  </properties>
  <body>
    <title>Castor JDO - An introduction</title>
    <header>
    </header>

    <section title="What is Castor JDO">
        
        <p>Castor JDO is an Object-Relational Mapping and Data-Binding Framework, which is 
           written in 100% pure Java[tm]. Castor can map relational database data into 
           Java Data Object based on user-defined mapping schema. In the other point-of-view, 
           it provides java data objects a persistence layer.</p>

        <p>It frees programmer from dealing with database directly and replacing the entire 
           burden of composing updating the database. Proper SQL statements are automatically 
           generated for loading, updating, creating and deleting. Changes to objects in transaction 
           are automatically done to data source at commit time. Thus programmer can stay in pure-Java
           without remember all the details in the backing database, after the creation of 
           database tables and the mapping schema. The separation of persistence and programming 
           logic also enable much clearer object-oriented design, which is important in larger 
           projects.</p>

    </section>

    <section title="Features">
        
        <p>JDO is <b>transactional</b>. Data objects loaded in Castor are properly locked and isolated 
           from other transactions. Castor supports full 2-phase commit via xa.Synchronzation. 
           Castor supports several locking modes, including "shared", "exclusive", "database 
           locked", and "read-only". </p>
           
        <p>
            <ul>
                <li><b>Shared access</b>, the default, is useful for situations in which it 
                    is common for two or more transactions to read the same objects, and/or update 
                    different objects.</li>
               <li><b>Exclusive access</b> uses in-memory locks implemented by Castor to force 
                   competing transactions to serialize access to an object. This is useful for 
                   applications in which it is common for more than one transaction to attempt 
                   to update the same object, and for which most, if not all access to the 
                   database is performed through Castor.</li>
                <li><b>Database-Locked access</b> is often used for applications in which 
                    exclusive locking is required, but in which the database is frequently 
                    accessed from applications outside of Castor, bypassing Castor's memory-based 
                    locking mechanism used by "exclusive access" locking.</li>
                <li><b>Read-Only access</b> performs no locking at all. Objects read using this 
                    access mode are not locked, and those objects do not participate in transaction 
                    commit/rollback.</li></ul></p>

         <p>In addition, Castor supports <b>"long transactions"</b>, whichs allow objects to be read 
            in one transaction, modified, and then committed in a second transaction, with 
            built-in dirty-checking to prevent data that has been changed since the initial 
            transaction from being overwritten.</p>
            
         <p>Through <b>automatic dirty-checking</b> and <b>deadlock detection</b>, Castor can be 
            used to ensure data integrity and reduce unnecessary database updates.</p>
            
         <p>A subset of OQL, defined in the Object Management Group (OMG) 3.0 <b>Object Query 
            Language</b> Specification, is supported for interacting with the database. OQL is 
            similar to SQL, though operations are performed directly on Java objects instead 
            of database tables, making the language more appropriate for use within a 
            Java-based application.</p>
            
         <p>Castor implements a <b>data cache</b> to reduce database accesses, providing several 
            alternative LRU-based caching strategies. </p>

        <p>Castor supports different cardinalities of <b>relationship</b>, including <b>one-to-one</b>, 
           <b>one-to-many</b> and <b>many-to-many</b>. It also supports both object and database record 
           <b>inheritance</b>. It distinguishes between <b>related</b> (i.e. association) and 
           <b>dependent</b> (i.e. aggregation) relationships during an object's life cycle, 
           automatically creating and deleting dependent objects at appropriate times in the independent 
           object's life cycle.</p>
           
        <p>Multiple-column primary keys, and a variety of key generators are supported.</p>

        <p>Castor automatically manages persistence for objects that contain Java collection 
           types, including Vector, Hashtable, Collection, Set, and Map. <b>Lazy loading</b> 
           (of collections as well as simple 1:1 relations) is implemented to reduce unnecessary 
           database loading. Lazy loading can be turned on or off for each individual field (of 
           any supported collection type for 1-to-many and many-to-many relations).</p>

        <p>Other features include a type converter for all Java primitive types (see the 
           info on supported<a href="types.html">types</a>).</p>

        <p>No pre-processor (aka pre-compiler), class enhancer (bytecodes modification) is needed 
           or used for data-binding and object persistence.</p>

        <p>Castor JDO works in an application that uses multiple ClassLoaders, making it possible to 
           use in an EJB container or servlet, for example. A Castor-defined callback interface, 
           "Persistent", can be implemented if the objects wants to be notified on Castor 
           events: jdoLoad(), jdoCreate(), jdoRemove() and jdoTransient(). This makes it possible 
           to create user-defined actions to take at various times in an object's life cycle.</p>

        <p>The Java-XML Data-Binding Framework (Castor XML) has been merged with Castor JDO for 
           users who need both O/R Mapping and Java-XML Data-Binding together. </p>

        <p>The following relational databases are supported: 
            
            <ul>
            <li>DB2</li>
            <li>Derby</li>
            <li>Generic DBMS</li>
            <li>Hypersonic SQL</li>
            <li>Informix</li>
            <li>InstantDB</li>
            <li>Interbase</li>
            <li>MySQL</li>
            <li>Oracle</li>
            <li>PostgreSQL</li>
            <li>SAP DB / MaxDB</li>
            <li>SQLServer</li>
            <li>Sybase</li>
            </ul>
            
            </p>
            
        <p>Database support includes Oracle 8.1.x and different versions of Sybase Enterprise and 
           Anywhere. Users can implement the Driver interface to adapt Castor to the differences in 
           SQL syntax supported by different relational DBMS's, as long as the DBMS supports JDBC 
           2.0, multiple ResultSet, and transactions. Thanks to many individual open source 
           contributors, drivers for different database are available.</p>

    </section>

  </body>
</document>

