This document is intended for developers who want to learn about JDO in order to use it in their applications. It assumes that you have a strong knowledge of Java and object-oriented concepts, and a familiarity with the eXtensible Markup Language (XML). The chapters on using JDO in a managed environment and using JDO with Enterprise Java Beans (EJBs) further assume that you have a firm grasp of Java Enterprise Edition (J2EE) architecture and of the EJB specification, respectively. This document does not, however, assume any experience with database programming or the manipulation of persistent data in general.

If your goal is to understand every nuance of JDO or to create your own JDO implementation, then you should skip this document and go directly to the official JDO specification, available from Sun Microsystems.

Persistent data is information that can outlive the program that creates it. The majority of complex programs use persistent data: GUI applications need to store user preferences across program invocations, web applications track user movements and orders over long periods of time, etc.

Transparent persistence is the storage and retrieval of persistent data with little or no work from you, the developer. For example, Java serialization is a form of transparent persistence because it can be used to persist Java objects directly to a file with very little effort. Serialization's capabilities as a transparent persistence mechanism pale in comparison to those provided by JDO, however. The next chapter compares JDO to serialization and other available persistence mechanisms.

The above diagram outlines the JDO exception architecture. Runtime exceptions such as NullPointerExceptions and IllegalArgumentExceptions aside, JDO components throw nothing but JDOExceptions of one type or another.

The JDO exception hierarchy should be self-explanatory. Consult the JDO Javadoc for details.

In order to shield you from the intricacies of the PersistenceCapable interface, most JDO implementations provide an enhancer. An enhancer is a tool that automatically adds code to your persistent classes after you have written them. Enhancers generally come in two forms: source enhancers and bytecode enhancers.

Source enhancers change the source code in the .java files defining your classes to implement the PersistenceCapable interface. This approach has the advantage of letting you see the changes that are made to your classes; however, it has several disadvantages as well:

Bytecode enhancers, on the other hand, operate on your .class files. They post-process the bytecode generated by your Java compiler, adding the necessary fields and methods to implement the PersistenceCapable interface. Bytecode enhancers overcome the difficulties associated with source enhancers:

	Note
	Kodo JDO uses bytecode enhancement.

Regardless of type, all JDO enhancers are required to be binary-compatible with each other. This means that the final enhanced class can be used not only by the JDO implementation whose enhancer created it, but by any other JDO implementation as well. The binary compatibility requirement ensures that you can package and ship persistent classes to other developers without worrying about what JDO vendor they use. It also means that you can switch JDO vendors without even recompiling your persistent classes.

Classes that have been enhanced to implement the PersistenceCapable interface are referred to as persistence-capable classes. Classes that directly access public or protected persistent fields of persistence-capable classes are called persistence-aware. Persistence-aware classes must also be enhanced -- each time a persistence-aware class directly accesses a persistent field of a persistence-capable class, the enhancer adds code to notify the JDO implementation that the field in question is about to be read or written. This enables the JDO implementation to synchronize the field's value with the data store as needed. Unless the persistence-aware class is also persistence-capable, the enhancer does not add code to make it implement the PersistenceCapable interface.

Generally, it is best to keep all of your persistent fields private, or protected but only accessed by subclasses. In addition to the standard arguments in favor of state encapsulation, this approach avoids the hassle of tracking which non-persistent classes must be enhanced as persistence-aware because they happen to access a public or protected field of some persistent class.

There are very few restrictions placed on persistent classes. Still, it never hurts to familiarize yourself with exactly what JDO does and does not support.

4.3.2. Persistent Fields

JDO manages the state of all persistent fields. Before you access a field, JDO makes sure that it has been loaded from the data store. When you set a field, JDO records that it has changed so that the new value will be persisted. This allows you to treat the field in exactly the same way you treat any other field -- another aspect of JDO's transparent persistence.

JDO includes built-in support for most common field types. These types can be roughly divided into three categories: immutable types, mutable types, and relations.

Immutable types, once created, cannot be changed. The only way to alter a persistent field of an immutable type is to assign a new value to the field. JDO supports the following immutable types for persistent fields:

• All primitives (int, float, byte, etc)

• All primitive wrappers (java.lang.Integer, java.lang.Float, java.lang.Byte, etc)

• java.lang.String

• java.math.BigInteger

• java.math.BigDecimal

• java.util.Locale

Persistent fields of mutable types can be altered without assigning the field a new value. Mutable types can be modified directly through their own methods. The JDO specification requires that implementations support the following mutable field type:

• java.util.Date

• java.util.HashSet

	Note
	Most JDO implementations support many other mutable field types as well. Kodo JDO supports the following: java.util.List java.util.ArrayList java.util.LinkedList java.util.Vector java.util.Set java.util.SortedSet java.util.TreeSet java.util.Map java.util.HashMap java.util.SortedMap java.util.TreeMap java.util.Hashtable java.util.Properties

Most implementations do not allow you to persist nested mutable types, such as Maps of LinkedLists.

JDO implementations support mutable fields by transparently replacing the field value with an instance of a special subclass of the field's declared type. For example, if your persistent object has a field containing a java.util.Date, the JDO implementation will transparently replace the value of that field at runtime with some vendor-specific Date subclass -- call it JDODate. The job of this subclass is to track modifications to the field. Thus the JDODate class will override all mutator methods of Date to notify the JDO implementation that the field's value has been changed. The JDO implementation then knows to write the field's new value to the data store at the next opportunity.

Of course, when you develop and use persistent classes, this is all transparent. You continue to use the standard methods of mutable fields as you normally would. It is important to know how support for mutable fields is implemented, however, in order to understand why JDO has such trouble with arrays. JDO allows you to use persistent array fields, and it automatically detects when these fields are assigned a new array value or set to null. Because arrays cannot be subclassed, however, JDO cannot detect when new values are written to array indexes. If you set an index of a persistent array, you must explicitly tell the JDO implementation you have changed the array field; this is referred to as "dirtying" the field. Dirtying is accomplished through the JDOHelper's makeDirty method.

Example 4.2. Accessing Mutable Persistent Fields

/**
 * Example demonstrating the use of mutable persistent fields in JDO.
 * Assume Person is a persistent class.
 */
public void addChild (Person parent, Person child)
{
    // can modify most mutable types directly; JDO tracks
    // the modifications for you
    Date lastUp = parent.getLastUpdated ();
    lastUp.setTime (System.currentTimeMillis ());
    Collection children = parent.getChildren ();
    children.add (child);
    child.setParent (parent);

    // arrays need explicit dirtying if they are modified,
    // but not if the field is reset
    parent.setObjectArray (new Object[0]);
    child.getObjectArray ()[0] = parent;
    JDOHelper.makeDirty (child, "objectArray");
}
				

As the example above illustrates, JDO supports relations between persistent objects in addition to the standard Java types covered so far. All JDO implementations should allow user-defined persistent classes and collections of user-defined persistent classes as persistent field types. The exact collection classes you can use to hold persistent relations will depend on which mutable field types the implementation supports. Some JDO implementations may also allow map fields in which the keys, values, or both are relations to other persistent objects. Again, the exact types of maps allowed depend on the implementation's mutable field type support.

	Note
	Kodo JDO supports user-defined persistent classes for map values, but it only allows immutable types for map keys.

Most JDO implementations also have some support for fields whose concrete class is not known. Fields declared as type java.lang.Object or as a user-defined interface type fall into this category. Because the information on these fields is so limited, though, there may be limitations placed on them. For example, they may be impossible to query, and loading and/or storing them may be inefficient.

	Note
	Kodo JDO supports persistent fields of an unknown type by serializing the field value and storing it as a sequence of bytes.

Your persistent classes can implement the javax.jdo.InstanceCallbacks interface to receive callbacks when certain JDO lifecycle events take place. This interface consists of four methods:

Unlike the PersistenceCapable interface, you must implement the InstanceCallbacks interface explicitly if you want to receive lifecycle callbacks.

Java recognizes two forms of object identity: numeric identity and qualitative identity. If two references are numerically identical, then they refer to the same JVM instance in memory. You can test for this using the == operator. Qualitative identity, on the other hand, relies on some user-defined criteria to determine whether two objects are "equal". You test for qualitative identity using the equals method. By default, this method simply relies on numerical identity.

JDO introduces another form of object identity, called JDO identity. JDO identity tests whether two persistent objects represent the same state in the data store.

You can obtain the JDO identity object from a persistent instance through the JDOHelper's getObjectId method. If two JDO identity objects compare equal using the equals method, then the two corresponding persistent objects represent the same state in the data store.

If you are dealing with a single PersistenceManager, then there is an even easier way to test whether two persistent object references represent that same state in the data store: use the == operator. JDO requires that each PersistenceManager maintain only one JVM object to represent each unique data store record. Thus, JDO identity is equivalent to numerical identity within a PersistenceManager's cache of managed objects. This is referred to as the uniqueness requirement.

The uniqueness requirement is extremely important -- without it, it would be impossible to maintain data integrity. Think of what could happen if two different objects of the same PersistenceManager were allowed to represent the same persistent data. If you made different modifications to each of these objects, which set of changes should be written to the data store? How would your application logic handle seeing two different "versions" of the same data? Thanks to the uniqueness requirement, these questions do not have to be answered.

There are three types of JDO identity, but only two of them are important to most applications: datastore identity and application identity. The majority of JDO implementations support datastore identity at a minimum; many support application identity as well.

	Note
	Kodo JDO supports both datastore and application identity.

4.5.2. Application Identity

Application identity is managed by you, the developer. Under application identity, the values of one or more persistent fields in an object determine its JDO identity. The fields whose values make up the object's identity are called primary key fields. Each object's primary key fields must be unique among all other objects of the same type.

When using application identity, it is up to you to supply the class used for JDO identity objects. This application identity class must meet all of the criteria listed for datastore identity classes. It must also obey the following requirements:

• The names of the non-static fields of the class must include the names of the primary key fields of the corresponding persistence-capable class, and the field types must be identical.

• The equals and hashCode methods of the class must use the values of all fields corresponding to primary key fields in the persistence-capable class.

• If the class is an inner class, it must be static.

• All classes related by inheritance must use the same application identity class.

• Each inheritance tree must use a unique application identity class.

These criteria allow you to construct an application identity object from either the values of the primary key fields of a persistent instance, or from a string produced by the toString method of another identity object.

Though it is not a requirement, you should also use your application identity class to register the corresponding persitence capable class with the JVM. This is typically accomplished with a static block in the application identity class code:

/**
 *  Application identity class for persistence capable class Magazine.
 */
public class MagazineId
{
    static
    {
		// register Magazine with the JVM
        Class c = Magazine.class;
    }

    // rest of code...
}

This registration process is a workaround for a quirk in JDO's persistent type registration system whereby some by-id lookups might fail if the type being looked up hasn't been used yet in your application.

	Note
	Though you may still create application identity classes by hand, Kodo JDO provides the com.solarmetric.kodo.enhance.ApplicationIdTool to automatically generate application identity classes that meet the above requirements.

This chapter covered everything you need to know to write persistent class definitions in JDO. JDO implementations cannot use your persistent classes, however, until you complete one additional step: you must create the JDO metadata. The next chapter explores metadata in detail.

<!ELEMENT jdo (package)+>
<!ELEMENT package ((class)+, (extension)*)>
<!ATTLIST package name CDATA #REQUIRED>
<!ELEMENT class (field|extension)*>
<!ATTLIST class name CDATA #REQUIRED>
<!ATTLIST class identity-type (application|datastore|none) 'datastore'>
<!ATTLIST class objectid-class CDATA #IMPLIED>
<!ATTLIST class requires-extent (true|false) 'true'>
<!ATTLIST class persistence-capable-superclass CDATA #IMPLIED> 
<!ELEMENT field ((collection|map|array)?, (extension)*)>
<!ATTLIST field name CDATA #REQUIRED>
<!ATTLIST field persistence-modifier (persistent|transactional|none) 'persistent'>
<!ATTLIST field primary-key (true|false) 'false'>
<!ATTLIST field null-value (exception|default|none) 'none'>
<!ATTLIST field default-fetch-group (true|false) #IMPLIED>
<!ATTLIST field embedded (true|false) #IMPLIED>
<!ELEMENT array (extension)*>
<!ATTLIST array embedded-element (true|false) #IMPLIED>
<!ELEMENT collection (extension)*>
<!ATTLIST collection element-type CDATA #IMPLIED>
<!ATTLIST collection embedded-element (true|false) #IMPLIED>
<!ELEMENT map (extension)*>
<!ATTLIST map key-type CDATA #IMPLIED>
<!ATTLIST map embedded-key (true|false) #IMPLIED>
<!ATTLIST map value-type CDATA #IMPLIED>
<!ATTLIST map embedded-value (true|false) #IMPLIED>
<!ELEMENT extension (extension)*>
<!ATTLIST extension vendor-name CDATA #REQUIRED>
<!ATTLIST extension key CDATA #IMPLIED>
<!ATTLIST extension value CDATA #IMPLIED>
		

The root element of all metadata documents is the jdo element. The only legal children of the jdo element are package elements. Each package element must specify a name attribute giving the full name of the package it represents.

<?xml version="1.0"?>
<jdo>
    <package name="org.mag">
        ...
    </package>
    <package name="org.mag.subscribe">
        ...
    </package>
</jdo>
			

package elements contain one or more class elements, followed by zero or more extension elements. Extensions are used to annotate metadata with vendor-specific information. The extension element may contain other extension elements as children, and has three attributes:

	Note
	Kodo JDO defines many useful metadata extensions. See the Kodo JDO Reference Guide chapter on metadata extensions for a full list.

Every persistence-capable class in the package named by each package element must be represented by a class element. Before we explore this element in detail, a brief note on how JDO resolves class names is in order.

Several metadata attributes require you to specify class names. The names you give should follow the following guidelines:

We now turn our attention back to the class element. This element has the following attributes:

<?xml version="1.0"?>
<jdo>
    <package name="org.mag">
        <class name="Magazine" objectid-class="Magazine$ObjectId">
            ...
        </class>
        <class name="Article">
            ...
        </class>
        <class name="Author">
            ...
        </class>
        <class name="Address">
            ...
        </class>
    </package>
    <package name="org.mag.subscribe">
        <class name="Form">
            ...
        </class>
        <class name="SubscriptionForm" persistence-capable-superclass="Form">
            ...
        </class>
        <class name="SubscriptionForm$LineItem">
            ...
        </class>
    </package>
</jdo>
			

The class element may contain extension elements and field elements. field elements represent fields declared by the persistence-capable class. These elements are optional; if a field declared in the class is not named by some field element, then its properties are defaulted as explained in the attribute listings below. Thanks to JDO's comprehensive set of defaults, most fields do not need to be listed explicitly. field elements may have the following attributes:

All field elements may contain extension child elements. field elements that represent array, collection, or map fields may also contain a single array, collection, or map child element, respectively. Each of these elements may contain additional extension elements in turn.

The array element has a single attribute, embedded-element. This attribute mirrors the embedded attribute of the class element, but applies to the values stored in each array index.

The collection element also has the embedded-element attribute. Additionally, it declares the element-type attribute. Use this attribute to tell the JDO implementation what class of objects the collection contains. If the element-type is not given, it defaults to java.lang.Object.

map elements define four attributes. They are:

That exhausts the metadata document structure. A complete metadata document example is presented below.

<?xml version="1.0"?>
<!-- Note that all persistence-capable classes must be listed, but -->
<!-- very few fields need to be specified                          -->
<jdo>
    <package name="org.mag">
        <class name="Magazine" objectid-class="Magazine$ObjectId">
            <field name="isbn" primary-key="true"/>
            <field name="articles">
                <collection element-type="Article"/>
            </field>
        </class>
        <class name="Article">
            <field name="authors">
                <map key-type="String" value-type="Author"/>
            </field>
        </class>
        <class name="Author"/>
        <class name="Address"/>
    </package>
    <package name="org.mag.subscribe">
        <class name="Form"/>
	    <class name="SubscriptionForm" persistence-capable-superclass="Form">
            <field name="lineItems">
                <collection element-type="SubscriptionForm$LineItem">
                    <extension vendor-name="kodo" key="inverse" value="form"/>
                </collection>
            </field>
		</class>
        <class name="SubscriptionForm$LineItem"/>
    </package>
</jdo>
			

JDO metadata must be available both during class enhancement and at runtime. The metadata document listing a persistence-capable class must be available as a resource from the class' class loader, and must exist in one of two standard locations:

	Note
	Some JDO implementations may not support all of the metadata placements discussed, or may support additional placements. Kodo JDO supports the standard metadata locations listed as well as a package-level resource called package.jdo and a system.jdo resource defining the metadata for the entire system, located in any top-level directory of the CLASSPATH.

We have already seen the first two persistence-capable operations, makeDirty and getObjectId. Given a persistence-capable object and the name of the field that has been modified, the makeDirty method notifies the JDO implementation that the field's value has changed so that it can write the new value to the data store. JDO usually tracks field modifications automatically; the only time you are required to use this method is when you assign a new value to some index of a persistent array.

The getObjectId method returns the JDO identity object for the persistence-capable instance given as an argument. If the given instance is not persistent, this method returns null.

The final persistence-capable operation, getPersistenceManager, is self-explanatory. It simply returns the PersistenceManager that is managing the persistence-capable object supplied as an argument. If the argument is a transient object, meaning it is not managed by a PersistenceManager, null is returned.

JDO recognizes several lifecycle states for persistence-capable objects. Instances transition between these states according to strict rules defined in the JDO specification. State transitions can be triggered by both explicit actions, such as calling the deletePersistent method of a PersistenceManager to delete a persistent object, and by implicit actions, such as reading or writing a persistent field.

The list below enumerates the lifecycle states for persistence-capable instances. Unless otherwise noted, each state must be supported by all JDO implementations. Do not concern yourself with memorizing the states and transitions presented; you will rarely need to think about them in practice.

	Note
	Some of the state transitions mentioned below occur at transaction boundaries. If you are unfamiliar with transactions, you may want to read the first few paragraphs of the chapter on the Transaction interface to become familiar with the concepts involved before continuing.

	Note
	Kodo JDO supports all JDO lifecycle states, including all optional states.

After reviewing the JDO lifecycle states, the purpose of the JDOHelper's lifecycle operations -- isDirty, isTransactional, isPersistent, isNew, isDeleted -- should be clear. Each one tells you whether or not the given persistence-capable instance has a certain property (dirty, transactional, persistent, new, and deleted, respectively), where these properties are determined by the lifecycle state of the instance. In fact, you can calculate the exact state of the instance based on these properties according to the table below. Once again, however, you will rarely worry about the lifecycle state of your persistence-capable objects in practice.

You can use the getPersistenceManagerFactory method of the JDOHelper to obtain PersistenceManagerFactory objects in a vendor-neutral fashion. This method takes a single argument, a java.util.Properties instance. The Properties instance is used to configure the PersistenceManagerFactory before it is returned from the method. Vendors may construct a new PersistenceManagerFactory with each invocation of this method, or may pool PersistenceManagerFactory instances and return a pooled instance that matches the supplied properties. The available configuration options and their associated property names are discussed in the next chapter detailing the PersistenceManagerFactory interface.

// this is usually just done once in your application somewhere, and then
// you cache the factory for easy retrieval by application components; often
// the properties are read from a properties file
Properties props = new Properties ();

// this property key tells the jdohelper what pmfactory class to instantiate
props.setProperty ("javax.jdo.PersistenceManagerFactoryClass", 
    "com.solarmetric.kodo.impl.jdbc.JDBCPersistenceManagerFactory");

// these properties define the default settings for persistence managers 
// produced by this factory; these settings are covered in the next chapter
props.setProperty ("javax.jdo.option.Optimistic", "true");
props.setProperty ("javax.jdo.option.RetainValues", "true");
props.setProperty ("javax.jdo.option.ConnectionUserName", "solarmetric");
props.setProperty ("javax.jdo.option.ConnectionPassword", "kodo");
props.setProperty ("javax.jdo.option.ConnectionURL", "jdbc:hsql:database");
props.setProperty ("javax.jdo.option.ConnectionDriverName", 
    "org.hsqldb.jdbcDriver");

PersistenceManagerFactory pmf = JDOHelper.getPersistenceManagerFactory (props);
			

JDO vendors may supply public constructors for their PersistenceManagerFactory implementations, but the recommended method of obtaining a PersistenceManagerFactory is through the JDOHelper's getPersistenceManagerFactory method. This method's Properties parameter supplies the configuration for the factory. PersistenceManagerFactory objects returned from the getPersistenceManagerFactory method are "frozen"; any attempt to change their property settings will result in a JDOUserException. This is because the returned factory may come from a pool, and might be shared by other application components.

JDO requires that concrete PersistenceManagerFactory classes implement the Serializable interface. This allows you to create and configure a PersistenceManagerFactory, then serialize it to a file or store it in a Java Naming and Directory Interface (JNDI) tree for later retrieval and use.

The majority of the PersistenceManagerFactory interface consists of Java bean-style "getter" and "setter" methods for several properties, represented by field declarations in the diagram at the beginning of this chapter. These properties can be grouped into three functional categories: data store connection configuration, default PersistenceManager and Transaction options, and PersistenceManager pooling settings.

The lists below explain the meaning of each property. Many of these properties can be set through the Properties instance passed to the aforementioned getPersistenceManagerFactory method in JDOHelper. Where this is the case, the name of the corresponding Properties key will appear in parentheses after the property name.

7.2.1. Connection Configuration

Use the properties below to tell JDO implementations how to connect with your data store.

• ConnectionUserName (javax.jdo.option.ConnectionUserName). The user name to specify when connecting to the data store.

• ConnectionPassword (javax.jdo.option.ConnectionPassword). The password for the above user.

• ConnectionURL (javax.jdo.option.ConnectionURL). The URL of the data store.

• ConnectionDriverName (javax.jdo.option.ConnectionDriverName). The full class name of the driver to use when interacting with the data store.

• ConnectionFactoryName (javax.jdo.option.ConnectionFactoryName). The JNDI location of a connection factory to use to obtain data store connections. This property overrides the other data store connection properties above.

• ConnectionFactory . A connection factory to use to obtain data store connections. This property overrides all other data store connection properties above, including the ConnectionFactoryName. The exact type of the given factory is implementation-dependent. Many JDO implementations will expect a standard Java Connector Architecture (JCA) ConnectionFactory. Implementations layered on top of JDBC might expect a JDBC DataSource. Still other implementations might use other factory types.

• ConnectionFactory2Name (javax.jdo.option.ConnectionFactory2Name). In a managed environment, connections obtained from the primary connection factory may be automatically enlisted in any global transaction in progress. To implement local transactions, the JDO implementation might require an additional connection factory that is not configured to participate in global transactions. The JNDI location of this factory can be specified through this property.

• ConnectionFactory2 . The connection factory to use for local transactions. Overrides the ConnectionFactory2Name above.

	Note
	Kodo JDO uses JDBC DataSources in place of JCA ConnectionFactory objects.

7.2.2. PersistenceManagerFactory and Transaction Defaults

The settings below will become the default property values for the PersistenceManagers and associated Transactions produced by the PersistenceManagerFactory. Some implementations may not fully support all properties. If you attempt to set a property to an unsupported value, the operation will throw a JDOUnsupportedOptionException.

• Multithreaded (javax.jdo.option.Multithreaded). Set this property to true to indicate that the persistence-capable instances managed by the PersistenceManager will be accessed concurrently by multiple threads.

• Optimistic (javax.jdo.option.Optimistic). Set to true to use optimistic transactions by default.

• RetainValues (javax.jdo.option.RetainValues). If this property is true, the fields of persistent objects will not be cleared on transaction commit. RetainValues automatically implies NontransactionalRead.

• RestoreValues (javax.jdo.option.RestoreValues). Controls the behavior of persistent and transactional fields on transaction rollback. Set this property to true to restore the fields to the values they had when the transaction began.

• NontransactionalRead (javax.jdo.option.NontransactionalRead). Specifies whether you can read persistent fields outside of a transaction. If this property is false, any attempt to read a persistent field outside of a transaction will result in a JDOUserException.

• NontransactionalWrite (javax.jdo.option.NontransactionalWrite). Specifies whether you can write to persistent fields outside of a transaction. If this property is false, any attempt to modify a persistent field outside of a transaction will result in a JDOUserException.

• IgnoreCache (javax.jdo.option.IgnoreCache). This property controls whether changes made to persistent instances in the current transaction are considered when evaluating queries. A value of true is a hint to the JDO runtime that changes in the current transaction can be ignored; this usually enables the implementation to run the query using the data store's native query interface. A value of false, on the other hand, may force implementations to run transactional queries in memory, which is often a slow process.

	Note
	Kodo JDO supports all PersistenceManager and Transaction properties. It recognizes many additional properties as well; see the Kodo JDO Reference Guide for details.

7.2.3. PersistenceManager Pooling

The following properties apply to the PersistenceManagerFactory's pooling of PersistenceManagers. Implementations are free to ignore these property settings if they do not support PersistenceManager pooling.

• MaxPool (javax.jdo.option.MaxPool). The maximum number of PersistenceManagers to allow in the pool.

• MinPool (javax.jdo.option.MinPool). The minimum number of PersistenceManagers to allow in the pool.

• MsWait (javax.jdo.option.MsWait). The number of milliseconds to wait for a free PersistenceManager before giving up.

	Note
	Kodo JDO applies these settings to its automatic connection pooling; it does not pool PersistenceManagers.

The PersistenceManagerFactory interface includes two getPersistenceManager methods for obtaining PersistenceManager instances. One version takes as parameters the user name and password to use for the PersistenceManager's data store connection(s). The other version relies on the ConnectionUserName and ConnectionPassword settings of the PersistenceManagerFactory. Both methods may return a newly-constructed PersistenceManager, or may return one from a pool of instances.

After the first PersistenceManager is acquired from a PersistenceManagerFactory, the factory's configuration is "frozen". Any attempt to change its properties will result in a JDOUserException.

In addition to supplying PersistenceManagers, the PersistenceManagerFactory also supplies metadata about the current JDO implementation. The getProperties method returns a Properties instance containing, at a minimum, the following keys:

The supportedOptions method returns a Collection of Strings enumerating the JDO options supported by the implementation. The following option names are recognized:

	Note
	Kodo JDO currently supports all options except javax.jdo.option.NullCollection and javax.jdo.option.ChangeApplicationIdentity.

The PersistenceManager's UserObject property allows you to associate an arbitrary object with each PersistenceManager. The given object is not used in any way by the JDO implementation.

The PersistenceManager interface includes "getter" and "setter" methods for two configuration properties: Multithreaded and IgnoreCache. These properties are discussed in the section detailing the PersistenceManagerFactory settings.

Every PersistenceManager has a one-to-one relation with a Transaction instance; in fact, many vendors use a single class to implement both the PersistenceManager and Transaction interfaces. If your application requires multiple concurrent transactions, you will have to use multiple PersistenceManagers.

You can retrieve the Transaction associated with a PersistenceManager through the currentTransaction method.

PersistenceManagers perform several actions that affect the lifecycle state of persistence-capable instances. Each of these actions is represented by multiple methods in the PersistenceManager interface: one method that acts on a single persistence-capable object, such as makePersistent, and corresponding methods that accept a collection or array of persistence-capable objects, such as makePersistentAll.

Each PersistenceManager is responsible for managing the JDO identities of the persistent objects in its cache. The following methods allow you to interact with the management of JDO identities:

Extents are logical representations of all persistent instances of a given persistence-capable class, possibly including subclasses.

Extents are obtained through the PersistenceManager's getExtent method. This method takes two parameters: the class of objects the Extent contains, and a boolean indicating whether or not subclasses are included as well.

You can only retrieve Extents for persistence-capable classes whose metadata specifies a value of true for the requires-extent attribute (this is the default).

Query objects are used to find persistent objects matching certain criteria. You can obtain a Query through one of the PersistenceManager's several newQuery methods. See the chapter covering the Query interface and the PersistenceManager Javadoc for details.

When a PersistenceManager is no longer needed, you should call its close method. Closing a PersistenceManager releases any resources it is using. The persistent instances managed by the PersistenceManager become invalid, as do any Query and Extent objects it created. Calling any method other than isClosed on a closed PersistenceManager results in a JDOUserException.

There are two major types of transactions: data store, or pessimistic, transactions and optimistic transactions. Each type has both advantages and disadvantages.

Pessimistic transactions generally lock the data store records they act on, preventing other concurrent transactions from using the same data. This avoids conflicts between transactions, but consumes a lot of database resources. Additionally, locking records can result in deadlock, a situation in which two transactions are both waiting for the other to release its locks before completing. The results of a deadlock are data store-dependent; usually one transaction is forcefully rolled back after some specified time out interval, and an exception is thrown.

Optimistic transactions consume less resources than pessimistic transactions, but only at the expense of reliability. Because optimistic transactions do not lock data store records, two transactions might change the same persistent information at the same time, and the conflict will not be detected until the second transaction attempts to commit. At this time, the second transaction will realize that another transaction has concurrently modified the same records (usually through a timestamp or versioning system), and will throw an appropriate exception. Note that optimistic transactions still maintain data integrity; they are simply more likely to fail in heavily concurrent situations.

The Transaction interface controls transactions in JDO. This interface consists of "getter" and "setter" methods for several Java bean-style properties, standard transaction demarcation methods, and a method to test whether there is a transaction in progress.

The Transaction's NonTransactionalRead, NonTransactionalWrite, RetainValues, RestoreValues, and Optimistic properties mirror those presented in the section on PersistenceManagerFactory settings. The final Transaction property, Synchronization has not been covered yet. This property enables you to associate a javax.transaction.Synchronization instance with the Transaction. The Transaction will notify your Synchronization instance on transaction completion events, so that you can implement custom behavior on commit or rollback. See the javax.transaction.Synchronization Javadoc for details.

The begin, commit, and rollback methods demarcate transaction boundaries. The methods should be self-explanatory: begin starts a transaction, commit attempts to commit the transaction's changes to the data store, and rollback aborts the transaction, in which case the data store is "rolled back" to its previous state. JDO implementations will automatically roll back transactions if any fatal exception is thrown during the commit process. Otherwise, it is up to you to roll back the transaction to free its resources.

Finally, the isActive method returns true if the transaction is in progress (begin has been called more recently than commit or rollback), and false otherwise.

public void transferFunds (User from, User to, double amnt)
{
    PersistenceManager pm = JDOHelper.getPersistenceManager (from);
    Transaction trans = pm.currentTransaction ();
    try
    {
        trans.begin ();
        from.decrementAccount (amnt);
        to.incrementAccount (amnt);
        trans.commit ();
    }
    catch (JDOFatalException jfe)
    {
        throw jfe;
    }
    catch (RuntimeException re)    // includes normal JDO exceptions
    {
        trans.rollback ();         // or could attempt to fix error and retry
        throw re;
    }
}
			

Every Query has three required elements:

The following are optional elements of JDO queries:

JDOQL is a data store-neutral query language based on Java boolean expressions. The syntax of JDOQL is the same as standard Java syntax, with the following exceptions:

	Note
	Kodo JDO also supports the Map.containsKey and Map.containsValue methods.

We will now present several examples illustrating the features of JDOQL and the Query interface. The examples use the following persistence-capable classes:

package org.mag;


public class Magazine
{
    private String  title;
    private double  price;
    private int     copiesSold;
	private Company publisher;
    private Article coverArticle;
    private Set     articles;

    ...
}


public class Article
{
    private String     title;
    private Collection subTitles;

	...
}


package org.mag.pub;


public class Company
{
    private String name;
    private double revenue;

    ...
}
		

Extent mags = pm.getExtent (Magazine.class, false);
String filter = "price > 10.0";
Query query = pm.newQuery (mags, filter);
Collection results = (Collection) query.execute ();
			

Extent mags = pm.getExtent (Magazine.class, false);
String filter = "title.startsWith (\"The \")";
Query query = pm.newQuery (mags, filter);
query.setOrdering ("price ascending");
Collection results = (Collection) query.execute ();
			

Extent mags = pm.getExtent (Magazine.class, false);
String filter = "price * copiesSold > publisher.revenue * .01";
Query query = pm.newQuery (mags, filter);
query.setOrdering ("publisher.revenue descending, publisher.name ascending");
Collection results = (Collection) query.execute ();
			

Extent mags = pm.getExtent (Magazine.class, false);
String filter = "price <= 10.0 "
    + "&& (publisher.name == \"Random House\" "
    + "|| publisher.name == \"Addison Wesley\")";
Query query = pm.newQuery (mags, filter);
Collection results = (Collection) query.execute ();
			

Company myCompany = ...;
Double myPrice = ...;

Extent mags = pm.getExtent (Magazine.class, false);
String filter = "publisher == pub && price > amnt";
Query query = pm.newQuery (mags, filter);
query.declareImports ("import org.mag.pub.*;");
query.declareParameters ("Company pub, Double amnt");
Collection results = (Collection) query.execute (myCompany, myPrice);
			

Extent mags = pm.getExtent (Magazine.class, false);
String filter = "coverArticle.subTitles.contains (\"The Real Story\") "
    + "|| coverArticle.subTitles.isEmpty ()";
Query query = pm.newQuery (mags, filter);
Collection results = (Collection) query.execute ();
			

Extent mags = pm.getExtent (Magazine.class, false);
String filter = "articles.contains (art) 
    && art.title == \"Fourier Transforms\"
Query query = pm.newQuery (mags, filter);
query.declareVariables ("Article art;");
Collection results = (Collection) query.execute ();
			

As evident from the examples above, queries are executed with one of the many execute methods defined in the Query interface. If your query declares between 0 and 3 parameters, use the execute version that takes the corresponding number of Object arguments; each argument should be set to a parameter value. For queries with more than 3 parameters, you can use the more generic executeWithArray and executeWithMap methods. See the Query interface Javadoc for details.

All execute methods declare a return type of Object, but they really return Collections. The JDO specification only uses Object rather than Collection to enable vendors to use proprietary return types in certain cases, and to allow for future expansion of the interface.

Query results may hold on to data store resources; therefore, all results should be closed when they are no longer needed. You can close an individual query result with the close method, or all open results at once with the closeAll.

Query objects can be compiled via the compile method. Compiling a query is a hint to the implementation to optimize an execution plan for the query. During compilation, all query elements are validated; any inconsistencies are reported via a JDOUserException.

Query instances can also be serialized. After deserialization, a query cannot be executed, but it retains its candidate class, filter string, imports, parameters, variables, and ordering. A deserialized query can therefore act as a template to create other query instances with the same configuration. This is accomplished through the PersistenceManager's newQuery(Object template) method.

This document is intended for Kodo JDO developers. It assumes strong knowledge of Java, familiarity with the eXtensible Markup Language (XML), and an understanding of JDO. If you are not familiar with JDO, please read SolarMetric's JDO Overview before proceeding.

Certain sections of this guide cover advanced topics such as custom object-relational mapping, enterprise integration, and using Kodo with third-party tools. These sections assume prior experience with the relevant subject.

JDO recognizes many standard runtime properties, all of which Kodo JDO supports (these properties are also covered in the JDO Overview).

Kodo JDO defines many properties of its own. Most of these properties are provided for advanced users who wish to customize Kodo JDO's behavior; the majority of developers can omit them. A complete listing of Kodo JDO-specific properties is given below.

com.solarmetric.kodo.ConnectionProperties: serverName=myserver port=1266

javax.jdo.option.ConnectionDriverName=oracle.jdbc.pool.OracleDataSource
com.solarmetric.kodo.ConnectionProperties=PortNumber=1521 \
                                          ServerName=saturn \
                                          DatabaseName=solarsid \
                                          DriverType=thin

2.2.28. com.solarmetric.kodo.impl.jdbc.SynchronizeSchema

Property name: com.solarmetric.kodo.impl.jdbc.SynchronizeSchema

Configuration API: com.solarmetric.kodo.impl.jdbc.JDBCConfiguration.getSynchronizeSchema

Resource adaptor config-property: SynchronizeSchema

Default: false

Description: If true, the Kodo runtime will automatically attempt to refresh the database schema when persistent classes are referenced, allowing the developer to bypass the schematool step.

	Warning
	This property is only intended to be used for development. As automatic schema migration can result in data loss, this feature should never be enabled on a production system. Furthermore, this feature has serious adverse affects on Kodo's runtime performace. Ensure that it is disabled before doing any performance analysis.

Kodo JDO uses the Apache Jakarta Commons Logging thin library for issuing log messages. The Commons Logging libraries act as a wrapper around a number of popular logging APIs, including the Jakarta Log4J project, and the native java.util.logging package in JDK 1.4. If neither of these libraries are available, then logging will fall back to using a very simple console logging. The remainder of this section presumes that Log4J will be used for logging. For details on customization of the Commons project, or on details on any of the underlying logging packages, please see the appropriate project page.

Logging is done over a number of logging channels, each of which has a logging level, which controls the verbosity of log messages that are sent to the channel. Following is an overview of the logging channels that Kodo will use, with a summary of the different levels to which log messages will be sent.

log4j.rootCategory=WARN, console
log4j.category.com.solarmetric.kodo.impl.jdbc.SQL=WARN, console
log4j.category.com.solarmetric.kodo.impl.jdbc.JDBC=WARN, console
log4j.category.com.solarmetric.kodo.impl.jdbc.Schema=INFO, console
log4j.category.com.solarmetric.kodo.Performance=INFO, console
log4j.category.com.solarmetric.kodo.MetaData=WARN, console
log4j.category.com.solarmetric.kodo.Enhance=WARN, console
log4j.category.com.solarmetric.kodo.Query=WARN, console
log4j.category.com.solarmetric.kodo.Runtime=INFO, console

log4j.appender.console=org.apache.log4j.ConsoleAppender
		

log4j.rootCategory=ERROR, console
log4j.category.com.solarmetric.kodo.impl.jdbc.SQL=ERROR, console
log4j.category.com.solarmetric.kodo.impl.jdbc.JDBC=ERROR, console
log4j.category.com.solarmetric.kodo.impl.jdbc.Schema=ERROR, console
log4j.category.com.solarmetric.kodo.Performance=ERROR, console
log4j.category.com.solarmetric.kodo.MetaData=ERROR, console
log4j.category.com.solarmetric.kodo.Enhance=ERROR, console
log4j.category.com.solarmetric.kodo.Query=ERROR, console
log4j.category.com.solarmetric.kodo.Runtime=ERROR, console

log4j.appender.console=org.apache.log4j.ConsoleAppender
		

log4j.rootCategory=TRACE, console
log4j.category.com.solarmetric.kodo.impl.jdbc.SQL=TRACE, console
log4j.category.com.solarmetric.kodo.impl.jdbc.JDBC=TRACE, console
log4j.category.com.solarmetric.kodo.impl.jdbc.Schema=TRACE, console
log4j.category.com.solarmetric.kodo.Performance=TRACE, console
log4j.category.com.solarmetric.kodo.MetaData=TRACE, console
log4j.category.com.solarmetric.kodo.Enhance=TRACE, console
log4j.category.com.solarmetric.kodo.Query=TRACE, console
log4j.category.com.solarmetric.kodo.Runtime=TRACE, console

log4j.appender.console=org.apache.log4j.ConsoleAppender
		

Kodo JDO supports both datastore and application JDO identity types. If you choose to use application identity, you may want to take advantage of Kodo JDO's appidtool.

The appidtool generates Java code implementing the object identity class for any persistent type using application identity. The code satisfies all the requirements JDO places on object identity classes. You can use it as-is, or simply use it as a starting point, editing it to meet your needs.

Before you can run the appidtool for a persistent class, the class must be compiled and must have JDO metadata. The metadata should include the objectid-class, though whatever class it refers to obviously may not exist yet. The tool will use the attribute to name the identity class that it generates.

The appidtool can be invoked via the included appidtool script or via its java class, com.solarmetric.kodo.enhance.ApplicationIdTool. It accepts the standard set of command-line arguments defined by the configuration framework. It also accepts an -ignoreErrors flag. If this flag is set to false, an exception will be thrown if the tool is run on any class that does not use application identity, or is not the base class in the inheritance hierarchy (subclasses never define the application identity class; they inherit it from their persistent superclass).

Each additional argument to the tool must be one of the following:

The .java file generated for each identity class will be placed in the same directory as the parent class' .java file. If the generated file is overwriting an older file, the older file will be backed up to <file-name>~.

	Note
	The .java for the parent class must be in the CLASSPATH.

java com.solarmetric.kodo.enhance.AppIdTool com.solarmetric.examples.Person
java com.solarmetric.kodo.enhance.AppIdTool -properties myapp.properties package.jdo
appidtool -licenseKey xxx-yyy-zzz com/solarmetric/examples/*.jdo
appidtool com.solarmetric.examples.Person Employee.class com/solarmetric/examples/Project.jdo
			

As discussed in the JDO Overview, JDO uses a process called enhancement to prepare persistent classes for management by the JDO runtime. The Kodo JDO enhancer is a command-line tool that can be invoked via the included jdoc script or via its java class, com.solarmetric.kodo.enhance.JDOEnhancer. The preferred method of enhancement is the jdoc script, which also validates the class metadata and points out any obvious inconsistencies.

The enhancer accepts the standard set of command-line arguments defined by the configuration framework. Like the appidtool, each additional argument to the enhancer must be either the full name of a persistent class, the .class file of a persistent class, or a .jdo metadata file listing one or more persistent classes.

You can run the enhancer over classes that have already been enhanced, in which case it will not further modify the class. You can also run it over classes that are not persistence-capable, in which case it will treat the class as persistence-aware.

Note that the enhancement process for subclasses introduces dependencies on the persistent parent class being enhanced. This is normally not problematic; however, when running the enhancer multiple times over a subclass whose parent class is not yet enhanced, class loading errors can occur. In the event of a class load error, simply re-compile and re-enhance the offending classes.

java com.solarmetric.kodo.enhance.JDOEnhancer com.solarmetric.examples.Person
java com.solarmetric.kodo.enhance.JDOEnhancer -properties myapp.properties package.jdo
jdoc -licenseKey xxx-yyy-zzz com/solarmetric/examples/*.jdo
jdoc com.solarmetric.examples.Person Employee.class com/solarmetric/examples/Project.jdo
			

Kodo JDO now includes a preview release of our upcoming reverse mapping tool. The reverse mapping tool generates persistent class definitions, complete with JDO metadata and Kodo mapping extensions, from an existing database schema. The tool is currently in its beta stages of development; bug reports are very much appreciated. The reverse mapping tool has been tested with the following databases:

To use the reverse mapping tool, follow the steps below:

<!ELEMENT schemas (schema)+>
<!ELEMENT schema (table)*>
<!ATTLIST schema name CDATA #IMPLIED>
<!ELEMENT table (column|index|pk|fk)+>
<!ATTLIST table name CDATA #REQUIRED>
<!ELEMENT column EMPTY>
<!ATTLIST column name CDATA #REQUIRED> 
<!ATTLIST column type (array | bigint | binary | bit | blob | char | clob | date | decimal | distinct | double | float | integer | java_object | longvarbinary | longvarchar | null | numeric | other | real | ref | smallint | struct | time | timestamp | tinyint | varbinary | varchar) #REQUIRED>
<!ATTLIST column not-null (true|false) "false">
<!ATTLIST column default CDATA #IMPLIED>
<!ATTLIST column size CDATA #IMPLIED>
<!ATTLIST column decimal-digits CDATA #IMPLIED>

<!-- the 'column' attribute of indexes, pks, and fks can be used -->
<!-- when the element has only one column (or for foriegn keys,  -->
<!-- only one local column); in these cases the on/join child    -->
<!-- elements can be ommitted                                    -->
<!ELEMENT index (on)*>
<!ATTLIST index name CDATA #REQUIRED>
<!ATTLIST index column CDATA #IMPLIED>
<!ATTLIST index unique (true|false) "false">
<!ELEMENT pk (on)*>
<!ATTLIST pk name CDATA #IMPLIED>
<!ATTLIST pk column CDATA #IMPLIED>
<!ELEMENT on EMPTY>
<!ATTLIST on column CDATA #REQUIRED>
<!ELEMENT fk (join)*>
<!ATTLIST fk name CDATA #IMPLIED>
<!ATTLIST fk to-table CDATA #REQUIRED>
<!ATTLIST fk column CDATA #IMPLIED>
<!ATTLIST fk delete-action (cascade|default|exception|none|null) "none">
<!ELEMENT join EMPTY>
<!ATTLIST join column CDATA #REQUIRED>
<!ATTLIST join to-column CDATA #REQUIRED>
			

Kodo JDO takes advantage of the guaranteed unqiueness of java.util.Set elements and java.util.Map keys to create smart proxies for your persistent set and map fields. Most proxies only track whether or not they have been modified. Smart proxies, however, keep a record of which elements have been added and removed. This record enables the Kodo JDO runtime to make more efficient database updates on these fields.

When designing your persistent classes, keep in mind that you can optimize for Kodo JDO by using fields of type java.util.Set, java.util.TreeSet, and java.util.HashSet for your collections whenever possible. You can also design your own smart proxies to further optimize Kodo JDO for your usage patterns. See the section on custom proxies for details.

Marking a field as dependent means that when the owning object is deleted, the related object(s) stored in the field will be deleted as well. This process is recursive, so dependent objects can have dependent fields themselves as well. Dependent fields are analyzed during JDO transaction commit.

All dependency-related extensions are specified at the field level (i.e. as direct child elements to the field elements they apply to). They all take a value of true or false:

The following keys are recognized for extension elements that are direct children of class elements in the metadata document:

The following keys are recognized for extension elements that are direct children of field elements in the metadata document:

Classes that use application identity require slightly different extensions than those enumerated above. First, no pk-column extension is ever needed, since the primary key columns can be determined from the columns for the primary key fields. Second, because application identity classes may use multiple primary key columns, all extensions associated with primary keys must be prefixed with the name of the corresponding field. This applies to all ref-column extensions, and to data-column extensions for one-to-one and many-to-many relation fields. A concrete example using application identity is presented in the next section.

The examples below show extensions being used to map persistent classes to an existing schema. Remember, however, that you are free to let Kodo auto-generate the schema. In this case, you might still use a few extensions, but only to specify inverses for one-to-many relations, turn on ordering in collection or array fields, and customize the names of a few tables and columns in the event of naming conflicts.

PERSON
|========================================|
| PK  | NAME      | SSNUM       | MGR    |
|========================================|
| 1   | john      | 123-45-6789 | 3      |
| 2   | fred      | 987-65-4321 | 3      |
| 3   | alice     | 111-22-3333 | NULL   |
|                 ...                    |
|========================================|

PROJECT
|============================================|
| PK  | START_DATE  | END_DATE  | CODE_NAME  |
|============================================|
| 1   | 10 25 2000  | NULL      | 2.0a1      |
| 2   | 01 10 2001  | 01 31 2001| TestPhase1 |
|                    ...                     |
|============================================|

XREF
|==================|
| PERSON | PROJECT |
|==================|
| 1      | 1       |
| 2      | 1       |
| 2      | 2       |
|==================|
			

package com.solarmetric.examples;

...

public class Person
{
    private String      name;
    private String      social;
    private Person      manager;
    private Collection  managedPeople;
    private Collection  projects;
    
    ...
}


public class Project
{
    private String  codeName;
    private Date    start;
    private Date    end;
    private List    people;

    ...
}
			

<?xml version="1.0"?>
<jdo>
    <package name="com.solarmetric.examples">
        <class name="Person">
            <extension vendor-name="kodo" key="table" value="PERSON"/>
            <extension vendor-name="kodo" key="pk-column" value="PK"/>
            <extension vendor-name="kodo" key="lock-column" value="none"/>
            <extension vendor-name="kodo" key="class-column" value="none"/>
            <field name="name">
                <extension vendor-name="kodo" key="data-column" value="NAME"/>
            </field>
            <field name="social">
                <extension vendor-name="kodo" key="data-column" value="SSNUM"/>
            </field>
            <field name="manager">
                <extension vendor-name="kodo" key="data-column" value="MGR"/>
            </field>

            <!-- 
                one-to-many mappings never take schema extensions; all the 
				needed information is available from the related class and its 
                inverse field
            -->
            <field name="managedPeople">
                <collection element-type="Person"/>
                <extension vendor-name="kodo" key="inverse" value="manager"/>
            </field>
            <field name="projects">
                <collection element-type="Project"/>
                <extension vendor-name="kodo" key="inverse" value="people"/>
                <extension vendor-name="kodo" key="table" value="XREF"/>
                <extension vendor-name="kodo" key="data-column" value="PROJECT"/>
                <extension vendor-name="kodo" key="ref-column" value="PERSON"/>
            </field>

        </class>
        <class name="Project">
            <extension vendor-name="kodo" key="table" value="PROJECT"/>
            <extension vendor-name="kodo" key="pk-column" value="PK"/>
            <extension vendor-name="kodo" key="lock-column" value="none"/>
            <extension vendor-name="kodo" key="class-column" value="none"/>
            <field name="codeName">
                <extension vendor-name="kodo" key="data-column" value="CODE_NAME"/>
            </field>
            <field name="start">
                <extension vendor-name="kodo" key="data-column" value="START_DATE"/>
            </field>
            <field name="end">
                <extension vendor-name="kodo" key="data-column" value="END_DATE"/>
            </field>
            <field name="people">
                <collection element-type="Person"/>
                <extension vendor-name="kodo" key="inverse" value="projects"/>
                <extension vendor-name="kodo" key="table" value="XREF"/>
                <extension vendor-name="kodo" key="data-column" value="PERSON"/>
                <extension vendor-name="kodo" key="ref-column" value="PROJECT"/>
            </field>
        </class>
    </package>
</jdo>
    		

PERSON
|===================================================|
|  NAME (PK) | SSNUM (PK)  | MGR_NAME | MGR_SSNUM   |
|===================================================|
|  john      | 123-45-6789 | alice    | 111-22-3333 |
|  fred      | 987-65-4321 | alice    | 111-22-3333 |
|  alice     | 111-22-3333 | NULL     | NULL        |
|                 ...                 |             |
|===================================================|

PROJECT
|==========================================|
| START_DATE  | END_DATE  | CODE_NAME (PK) |
|==========================================|
| 10 25 2000  | NULL      | 2.0a1          |
| 01 10 2001  | 01 31 2001| TestPhase1     |
|                    ...                   |
|==========================================|

XREF
|==========================================|
| PERSON_NAME | PERSON_SSNUM  | PROJECT    |
|==========================================|
| john        | 123-45-6789   | 2.0a1      |
| fred        | 987-65-4321   | 2.0a1      |
| alice       | 111-22-3333   | TestPhase1 |
|==========================================|
			

package com.solarmetric.examples;

...

public class Person
{
    private String      name;
    private String      social;
    private Person      manager;
    private Collection  managedPeople;
    private Collection  projects;
    
    ...
}


public class Project
{
    private String  codeName;
    private Date    start;
    private Date    end;
    private List    people;

    ...
}
			

<?xml version="1.0"?>
<jdo>
    <package name="com.solarmetric.examples">
        <class name="Person" objectid-class="...">
            <extension vendor-name="kodo" key="table" value="PERSON"/>
            <extension vendor-name="kodo" key="lock-column" value="none"/>
            <extension vendor-name="kodo" key="class-column" value="none"/>
            <field name="name" primary-key="true">
                <extension vendor-name="kodo" key="data-column" value="NAME"/>
            </field>
            <field name="social" primary-key="true">
                <extension vendor-name="kodo" key="data-column" value="SSNUM"/>
            </field>
            <field name="manager">
                <extension vendor-name="kodo" key="name-data-column" value="MGR_NAME"/>
                <extension vendor-name="kodo" key="social-data-column" value="MGR_SSNUM"/>
            </field>

            <!-- 
                one-to-many mappings never take schema extensions; all the 
				needed information is available from the related class and its 
                inverse field
            -->
            <field name="managedPeople">
                <collection element-type="Person"/>
                <extension vendor-name="kodo" key="inverse" value="manager"/>
            </field>
            <field name="projects">
                <collection element-type="Project"/>
                <extension vendor-name="kodo" key="inverse" value="people"/>
                <extension vendor-name="kodo" key="table" value="XREF"/>
                <extension vendor-name="kodo" key="codeName-data-column" value="PROJECT"/>
                <extension vendor-name="kodo" key="name-ref-column" value="PERSON_NAME"/>
                <extension vendor-name="kodo" key="social-ref-column" value="PERSON_SSNUM"/>
            </field>

        </class>
        <class name="Project" objectid-class="...">
            <extension vendor-name="kodo" key="table" value="PROJECT"/>
            <extension vendor-name="kodo" key="lock-column" value="none"/>
            <extension vendor-name="kodo" key="class-column" value="none"/>
            <field name="codeName" primary-key="true">
                <extension vendor-name="kodo" key="data-column" value="CODE_NAME"/>
            </field>
            <field name="start">
                <extension vendor-name="kodo" key="data-column" value="START_DATE"/>
            </field>
            <field name="end">
                <extension vendor-name="kodo" key="data-column" value="END_DATE"/>
            </field>
            <field name="people">
                <collection element-type="Person"/>
                <extension vendor-name="kodo" key="inverse" value="projects"/>
                <extension vendor-name="kodo" key="table" value="XREF"/>
                <extension vendor-name="kodo" key="name-data-column" value="PERSON_NAME"/>
                <extension vendor-name="kodo" key="social-data-column" value="PERSON_SSNUM"/>
                <extension vendor-name="kodo" key="codeName-ref-column" value="PROJECT"/>
            </field>
        </class>
    </package>
</jdo>
    		

By default, Kodo JDO maps all fields in a class hierarchy into the table defined by the least-derived type in that class hierarchy. This is often the best class mapping strategy to use, as it reduces the number of joins and separate statements necessary, reducing load on the database and increasing database performance. However, there are many situations in which this mapping is not ideal. Inheritance hierarchies with lots of fields might be better broken up into several tables in order to reduce overall table size, or to reduce the amount of data transmitted for a given select. Existing database schema constraints may require the use of multiple tables per hierarchy, or even multiple tables per individual class.

It is possible to control which tables a given class maps to on both per-class and per-field levels.

To designate the table that all fields declared in a class should map to, use the table metadata extension on the class element in the JDO metadata. If this extension is set, then Kodo will by default map all fields in this class into that table. Otherwise, the behavior is controlled by the com.solarmetric.kodo.impl.jdbc.FlatInheritanceMapping configuration property. Configuration is covered here. If this property is set to true (the default value), then the fields will by default be mapped into the table in use by the superclass of the class. Otherwise, a new table name will be generated based on the class name, and a table with that name will be used by default for all fields in the class.

To designate a table that a particular field should map to, use the table metadata extension on a field element in the JDO metadata. If this extension is set, then Kodo will map the given field's primary table data into the specified table. Otherwise, the field's primary table data will be mapped into the table in use by the owning class.

When presented with a class hierarchy that spans multiple tables, Kodo requires that all tables in the hierarchy share the same number of primary key fields and that the primary key column names be identical.

When loading a class that spans multiple tables and for which the entire class hierarchy maps to the same set of tables, Kodo performs a single select statement that joins the related tables on the primary keys. When loading a class that maps to additional tables not mapped to by the class' superclass, Kodo performs multiple select statements.

Kodo JDO now includes a preview release of our upcoming metadata tool. The metadata tool uses reflection to generate default JDO metadata for your persistent classes. It cannot fill in information that is not available from the class definition itself, such as the element type of collections or the primary key fields of a class using application identity. It does, however, provide a good starting point from which to build up your metadata.

The metadata tool recognizes JDO's extensive system of defaults, so fields that are persistent by default will not be included in the generated XML document. The only exception to this rule is for collection and map fields: the tool adds these fields to the metadata and sets their element-type, key-type, and value-type attributes to Object as a reminder to you to provide this information.

The metadata tool can be run via the included rd-metadatatool script, or through its Java class, com.solarmetric.rd.kodo.meta.JDOMetaDataTool. In addition to the standard configuration flags accepted by all Kodo JDO tools, the reverse mapping tool recognizes the following command line flags:

Standard usage example:

rd-metadatatool -properties myprops.properties -file mypackage/mypackage.jdo
mypackage/*.java
		

Kodo JDO can take advantage of any JDBC 1.x compliant driver, making almost any major database a candidate for use. See our officially supported database list for more information.

If your database is not officially supported, you can add support for it by implementing your own DBDictionary. This is typically accomplished by extending the concrete GenericDictionary class. You can then plug your dictionary into Kodo JDO using the com.solarmetric.kodo.impl.jdbc.DictionaryClass and com.solarmetric.kodo.impl.jdbc.DictionaryProperties configuration properties. These properties are described in the chapter examining the configuration framework.

com.solarmetric.kodo.impl.jdbc.DictionaryClass: \
    com.solarmetric.kodo.impl.jdbc.schema.dict.HSQLDictionary

com.solarmetric.kodo.impl.jdbc.DictionaryProperties: \
    SchemaName=MySchema SupportsSelectForUpdate=false
			

Through the properties above, each PersistenceManagerFactory can be configured to access a different database. If your application accesses multiple databases, we recommend that you maintain a separate properties file for each one. This will allow you to easily load the appropriate resource for each database at runtime, and to given the correct file to Kodo JDO's command-line tools during development.

By default, Kodo performs database connection pooling with its own javax.sql.DataSource implementation. The numbers provided in the javax.jdo.option.MinPool and javax.jdo.option.MaxPool configuration properties specify the number of connections that the pool should maintain. You can also manage connections yourself by setting the ConnectionFactory of the PersistenceManagerFactory to your own javax.sql.DataSource. Alternatively, you can set the javax.jdo.option.ConnectionFactoryName configuration property to the JNDI location of a bound javax.sql.DataSource.

If you would prefer to use a javax.sql.DataSource other than Kodo's built-in pooling implementation, you can set the DataSource's class name in the javax.jdo.option.ConnectionDriverName property, and specify the bean properties in the com.solarmetric.kodo.ConnectionProperties property. In these cases, the javax.jdo.option.ConnectionURL property will be unused.

javax.jdo.option.ConnectionDriverName=oracle.jdbc.pool.OracleDataSource
com.solarmetric.kodo.ConnectionProperties=PortNumber=1521 \
                                          ServerName=saturn \
                                          DatabaseName=solarsid \
                                          DriverType=thin
javax.jdo.option.ConnectionUserName=jdotestuser
javax.jdo.option.ConnectionPassword=jdotestpassword
		

	Important
	Kodo's built-in DataSource implementation performs advanced connection pooling and caching of PreparedStatement. Using a third-party DataSource that does not provide these feature may result in sub-optimal Kodo performance.

When using a JDBC driver that supports version 2.0 or higher of the JDBC specification, and that supports ResultSets of type TYPE_SCROLL_INSENSITIVE, collections returned from Query.execute methods will load rows from the database only when they are needed. This on-demand loading is also applied to javax.jdo.Extents.

The on-demand instantiation of elements of the ResultSet allows efficient handling of potentially very large result sets. Kodo JDO further conserves memory by using soft references to hold objects as they are instantiated during iteration. If the JVM begins to run low on memory, these objects will be garbage collected. Thus even query results or extents containing millions of objects can be fully iterated.

If an on-demand collection is ever completely instantiated, its soft references will be converted to hard references, and any database resources it is using will be freed. It becomes a standard collection of objects.

To facilitate users who require random access to query results, Kodo JDO always returns an implementation of java.util.List from calls to Query.execute. Remember, though, that other JDO implementations might choose to only implement the java.util.Collection interface in their query result objects. Also, note that unless ordering is specified in your query, there is no guarantee that multiple executions of the same query will return their results in the same order.

// get start and end indexes of results to display from web request
int startIndex = Integer.parseInt (jspRequest.getParameter ("start"));
int endIndex = Integer.parseInt (jspRequest.getParameter ("end"));

Extent extent = pm.getExtent (Product.class, true);
Query query = pm.newQuery (extent, "productName == \"Stereo\"");

// we want to ensure that we always order the results in the same way
query.setOrdering ("productCode ascending");

Collection results = (Collection) query.execute ();
List resultList;
if (results instanceof List)
    resultList = (List) results;
else
    // portable, but it will wind up instantiating all elements in
    // collection, which might be a huge number of objects
    resultList = new ArrayList (results);

// print info about each product in list range from "start" to "end"
for (int i = startIndex; i <= endIndex && i < resultList.size (); i++)
    out.print ("Stereo #" + i + ": "
        + ((Product) resultList.get (i)).getDescription ());
			

Kodo JDO stores persistent objects in relational database tables. As you add, remove, or modify your persistent classes, these tables must be updated to reflect the current object model.

To facilitate this process, Kodo JDO provides the schematool. This command-line tool can create, refresh, or drop the relational schema for any persistent types, relieving you from database administration tasks. You can invoke the tool through the included schematool script or via its java class, com.solarmetric.kodo.impl.jdbc.schema.SchemaTool . It accepts the standard set of command-line arguments defined by the configuration framework. It also accepts the following flags:

	Important
	When acting on a persistent type, the schematool automatically extends the action to all known subclasses of the type.

schematool -action refresh
			

schematool -properties hsql.properties -action drop com.solarmetric.examples.Company ../package.jdo
    		

	Note
	It is possible to bypass the schematool step by specifying the com.solarmetric.kodo.impl.jdbc.SynchronizeSchema Kodo property to true. This should never be used on a production database, since automatic schema migration can result in columns being dropped, and thus in data loss. See the Configuration Framework chapter for more details.

Datastore identity objects are typically opaque. Kodo JDO does, however, allow you to manipulate these objects if you need to. All datastore identity objects in Kodo JDO are instances of the public com.solarmetric.util.ObjectIds.Id class. See its Javadoc for details.

Often, it is necessary to retrieve all items in an extent for processing of some sort. The Extent interface provides a mechanism for retrieving an Iterator that can be used to traverse the entire extent, but it does not provide a method for retrieving a collection of all the items in the extent.

Kodo JDO's Extent implementation provides a method that can be used to access the data in an extent via the List interface. See the com.solarmetric.kodo.runtime.ExtentImpl Javadoc for details.

Some advanced users may want to use a custom PersistenceManager in place of Kodo JDO's com.solarmetric.kodo.runtime.PersistenceManagerImpl.

Kodo JDO permits simple extension of the PersistenceManager used by the PersistenceManagerFactory. This can be useful when custom behavior is desired, or when an application needs to receive notification when certain PersistenceManager methods are invoked.

To specify a subclass of PersistenceManagerImpl, use the com.solarmetric.kodo.PersistenceManagerClass property. The class specified must extend com.solarmetric.kodo.runtime.PersistenceManagerImpl -- the method will throw a JDOUserException if it does not. You can also setup your custom PersistenceManager through the com.solarmetric.kodo.PersistenceManagerClass and com.solarmetric.kodo.PersistenceManagerProperties properties, as described in the configuration framework.

At runtime, the values of all second class object fields in persistent and transactional objects are replaced with implementation-specific proxies. On modification, these proxies notify their owning instance that they have been changed, so that the appropriate updates can be made on the data store.

In Kodo JDO, proxies are managed through the com.solarmetric.kodo.util.ProxyManager interface. Kodo JDO includes a default ProxyManager implementation that will meet the needs of most users. For custom behavior, though, Kodo JDO allows you to define your own ProxyManager, and your own proxy classes. See the com.solarmetric.util package Javadoc for details on the interfaces involved, and the utility classes Kodo JDO provides to assist you.

You can plug your custom proxy manager into the Kodo JDO runtime through the com.solarmetric.kodo.ProxyManagerClass and com.solarmetric.kodo.ProxyManagerProperties configuration properties. The configuration framework is described here.

Kodo JDO provides two mechanisms for obtaining a java.sql.Connection object. This can be useful when direct access to the underlying data store is required.

The following code obtains the connection that is currently in use by a particular PersistenceManager. If there is no connection open to the data store for the given thread, then a new one is created and returned. If a data store transaction is in progress, then the connection returned will be transactionally consistent. See the Javadoc for com.solarmetric.kodo.impl.jdbc.runtime.JDBCStoreManager for more details.

PersistenceManagerFactory factory = ...; // obtain a PersistenceManagerFactory
PersistenceManagerImpl pm = 
  (PersistenceManagerImpl) factory.getPersistenceManager ();
JDBCStoreManager storeManager = (JDBCStoreManager) pm.getStoreManager ();
Connection conn = storeManager.getConnection ();

// do stuff

storeManager.releaseConnection (conn);
		

Additionally, a connection that is in no way linked to the current PersistenceManager can be obtained using Kodo JDO:

PersistenceManagerFactory factory = ...;
DataSource dataSource = (DataSource) factory.getConnectionFactory ();
Connection conn = dataSource.getConnection ();
		

Kodo JDO's PersistenceManager implementation includes two API extensions useful when reusing PersistenceManager instances. PersistenceManagerImpl.evictAll(Class) and PersistenceManagerImpl.evictAll(Extent) behave just like PersistenceManager.evictAll(), except that they operate only on instances that are members of the specified class or extent.

By default, Kodo JDO stores the full class name of inserted objects in the database, so that it can determine which type to instantiate when loading data from the database. However, existing databases often have a pre-existing mechanism for storing subclass indicator values. This might be based on a C++ class naming convention, or it might be a numeric indicator. Sometimes, subclass information might not be stored in a single column at all, but might only be determinable by analyzing other values in the result set.

Kodo JDO includes an optional subclass provider that stores integers in the database instead of the full classname. This can be considerably faster than the default provider. To use this alternate provider, set the com.solarmetric.kodo.impl.jdbc.DefaultSubclassProviderClass configuration property to com.solarmetric.kodo.impl.jdbc.ormapping.IntegerSubclassProvider, and set the subclass-indicator-value metadata extension in all your classes to the appropriate integer value. Alternately, this can be performed on a class-by-class basis, by setting the subclass-provider metadata extension to com.solarmetric.kodo.impl.jdbc.ormapping.IntegerSubclassProvider.

A demonstration: these mappings are specified as demonstrated in the following example, in which rows representing com.acme.object.Foo have a value of 1 stored in the JDOCLASSX column, and rows representing com.acme.object.Bar have a value of 2:

<jdo>
	<package name="com.acme.object">
		<class name="Foo">
			<!-- specify that we should use this subclass provider instead
				of the default string-based provider for this class. This
				should only be set in the least-derived type in an
				inheritance hierarchy. -->
			<extension vendor-name="kodo" key="subclass-provider"
				value="com.solarmetric.kodo.impl.jdbc.ormapping.IntegerSubclassProvider"/>

			<!-- set up the mapping for this class. This must be done for
				every class in the inheritance hierarchy, and all values
				must be unique. -->
			<extension vendor-name="kodo" key="subclass-indicator-value"
				value="1"/>
		</class>

		<class name="Bar" persistence-capable-superclass="Foo">
			<!-- set up the mapping for this class. This must be done for
				every class in the inheritance hierarchy, and all values
				must be unique. -->
			<extension vendor-name="kodo" key="subclass-indicator-value"
				value="2"/>
		</class>
	</package>
</jdo>

Kodo JDO also supports customization of this default behavior through the SubclassProvider interface and the com.solarmetric.kodo.impl.jdbc.DefaultSubclassProviderClass configuration property. Additionally, alternate subclass providers can be set on a per-class basis in the JDO metadata. See the Class-level Object-Relational Mapping Extensions documentation for more information on doing this.

Often, it is desirable to be able to do extra processing on a global basis when a change is made to an object. The JDO specification provides the javax.jdo.InstanceCallbacks interface to this end. However, if you wish to perform extra logic regardless of the type of the object, it is not ideal to require developers to make a callback to some global change listener. For example, if your application wished to log all deletes, you could use this callback mechanism to perform this logging without requiring that all your persistence-capable objects implement the jdoPreDelete() method.

The EEPersistenceManager uses the com.solarmetric.kodo.ee.ObjectEventListener interface to permit this type of global callback behavior. See the JavaDoc included with this documentation for more information on this interface.

Similarly, a developer may want to receive notification of transaction events. The EEPersistenceManager uses the com.solarmetric.kodo.ee.TransactionEventListener for this purpose. See the JavaDoc included with this documentation for more information on this interface.

JDOQL is designed to be back-end agnostic, meaning that the query language can be translated into any of a number of back-end languages. This is important for the JDO specification, because it permits true portability among fundamentally different data stores. However, when dealing with a relational data store, it is often necessary to use SQL-specific operations to harness the power and features of the relational data store. Kodo JDO Enterprise Edition allows developers to optimize and customize their datastore queries by adding new custom operations to JDOQL. In addition, Kodo provides some built-in extensions to simplify some common queries outside the JDOQL specification.

Query q = pm.newQuery (City.class, true);
q.setIgnoreCache (true); // extensions work purely upon the datastore
q.setFilter ("name.ext:stringContains (\"ford\"");
Collection c = (Collection) q.execute ();
				

The JDO specification defines a concept of a default fetch group, but it does not touch upon additional, non-default fetch groups.

public class FetchGroupExample
{
	private int 				a;
	private String				b;
	private BigInteger			c;
	private Date 				d;
	private String 				e;
	private String 				f;
	private FetchGroupExample	g;
}
			

<?xml version="1.0"?>
<jdo>
    <package name="">
		<class name="FetchGroupExample">
			<field name="a"/>
			<field name="b"/>
			<field name="c"/>
			<field name="d"/>
			<field name="e"/>
			<field name="f"/>
			<field name="g"/>
		</class>
    </package>
</jdo>

			

Sometimes, data must be loaded from non-standard input feeds, such as from XML input or from ResultSets obtained from custom stored procedures. Kodo JDO's CustomResultObjectProvider interface can be used to load arbitrary data into PersistenceCapable objects associated with a particular PersistenceManager.

Documentation of these interfaces, including some code fragments, can be found in the JavaDoc for the com.solarmetric.kodo.runtime.objectprovider package, and the CustomResultSetResultObjectProvider and ColumnAliasResultObjectProvider. Additionally, an example of how to use the CustomResultObjectProvider interface to load externally obtained SQL data is available in the Kodo JDO distribution.

The ColumnAliasResultObjectProvider implementation is useful when loading data via a custom SELECT statement from tables that Kodo JDO is already configured to map to. In this situation, the Kodo JDO metadata contains enough information for Kodo JDO to do all the data loading of the result set without any application-specific code.

When more application-specific result sets must be processed, the CustomResultSetResultObjectProvider abstract class should be extended. The subclass must provide an implementation of the getFieldValues method, which creates a Map of field names to field values, which will then be loaded into a StateManagerImpl by the Kodo JDO framework.

The custom data processing feature described above is useful when loading data from externally obtained data feeds, but often, this is only half of the story. Once that data is initially loaded, requests to reload all or part of a particular object may be made by the Kodo JDO runtime framework. Additionally, requests to insert, update or delete data may be issued.

Kodo JDO often makes requests to the JDBC subsystem to find information about a particular object. For example, when a user invokes PersistenceManager.getObjectById, Kodo JDO will make a request to the JDBC subsystem to load that particular object. Similarly, Kodo JDO will occasionally make a request to see if a particular object exists in the data store, or if the optimistic lock version information indicates an optimistic lock violation. To intercept these calls and provide custom logic to load the data, extend com.solarmetric.kodo.impl.jdbc.ormapping.ClassMapping and override the appropriate methods. Following is a brief discussion of some commonly overridden APIs in ClassMapping.

Alternate ClassMapping implementations can be specified on a system-wide basis using the DefaultClassMappingClass property, or on a per-class basis with the custom-mapping metadata extension.

Kodo provides a number of mechanisms for integrating with third-party tools. The following chapter will illustrate these integration features.

Ant is a very popular tool for building java projects. It is similar to the make command, but is java-centric and has more modern features. Ant is open-source, and can be downloaded from Apache's Ant web page at http://jakarta.apache.org/ant/. Ant has become the de-facto standard build tool for java, and many commercial integrated development environments provide some support for using ant build files. The remainder of this section assumes familiarity with writing Ant build.xml files.

Kodo provides three pre-built Ant task definitions for use in build.xml files:

<schematool action="refresh" ignoreErrors="true">
  <fileset dir="${basedir}">
    <include name="**/*.jdo" />
  </fileset>
  <config connectionUsername="scott" connectionPassword="tiger"
    licenseKey="1234-5678-90ab-cdef"
    connectionUrl="jdbc:oracle:thin:@saturn:1521:solarsid"
    connectionDriverName="oracle.jdbc.driver.OracleDriver" />
</schematool>
			

<jdoc>
  <fileset dir="${basedir}/source">
    <include name="**/*.jdo" />
  </fileset>
  <classpath>
    <pathelement location="${basedir}/classes"/>
    <pathelement location="${basedir}/source"/>
    <pathelement path="${java.class.path}"/>
  </classpath>
</jdoc>
			

<target name="enhanceAll">
  <!-- Define the jdoc task definition. This can
       be done at the top of the build.xml file,
       so it will be available for all targets. -->
  <taskdef name="jdoc"
    classname="com.solarmetric.modules.integration.ant.JDOEnhancerTask"/>

  <!-- Invoke the JDOEnhancer on all .jdo files
       below the current directory. -->
  <jdoc>
    <fileset dir=".">
      <include name="**/*.jdo" />
    </fileset>
  </jdoc>
</target>
			

<target name="refreshDataStore">
  <!-- Define the schematool task definition. This can
       be done at the top of the build.xml file,
       so it will be available for all targets. -->
  <taskdef name="schematool"
    classname="com.solarmetric.modules.integration.ant.SchemaToolTask"/>

  <!-- Locate all the .jdo files below this, and
       refresh the data store's schema to be in synch
       with the current state of the metadata. --> 
  <schematool action="refresh" ignoreErrors="true">
    <fileset dir=".">
      <include name="**/*.jdo" />
    </fileset>
  </schematool>
</target>
			

XDoclet is an open-source project hosted at http://xdoclet.sourceforge.net. It is an extension of Sun's javadoc tool that allows you to embed well-formed tags in java source code and output metadata of a particular type. In the case of the JDODoclet, you can generate a filename.jdo file based on various tags starting with @jdo:. Any class that has the @jdo:persist class-level tag will be processed. This allows for all refactoring to be done in just one place (the java source code file), without the developer needing to manually ensure that the .jdo metadata file is always synchronized with the state of the java source code.

In order to utilize the XDoclet task, you will need to download the XDoclet libraries separately from http://xdoclet.sourceforge.net and add them to your CLASSPATH. The JDODoc task can then be executed from the build.xml as follows:

<target name="generateJdoMetadata">
  <taskdef name="jdodoclet"
    classname="com.solarmetric.modules.integration.ant.KodoDocletTask"/>

  <jdodoclet sourcepath="${basedir}" destdir="${classes}">
    <fileset dir="${basedir}">
      <include name="**/*.java"/>
    </fileset>

    <!-- perform the actual transformation here -->
    <jdotags/>

  </jdodoclet>
</target>
		

An example of a commented file is as follows:

package samples.xdoclet;

import java.util.*;

/**
 *  This is the TestDoclet example class. It is used to
 *  demonstrate automatic generation of the
 *  TestDoclet.jdo file based on the jdo: tags
 *  in the source code.
 *
 *  Note that the double-$ for inner class names is required
 *  in order to escape ant variable handling.
 *
 *  The jdo:persist tag is required for the XDoclet to know that we
 *  should generate persistence information for this class.
 *
 *  @jdo:persist
 *  @jdo:identity-type     application
 *  @jdo:objectid-class    TestDoclet$$Id
 *  @jdo:requires-extent   false
 *  @jdo:extension         vendor-name="kodo" key="table"
 *                         value="DOCLET_TEST_TABLE"
 *  @jdo:extension         vendor-name="kodo" key="pk-column"
 *                         value="TEST_PK_COLUMN"
 *  @jdo:extension         vendor-name="kodo" key="lock-column"
 *                         value="TEST_LOCK_COLUMN"
 *  @jdo:extension         vendor-name="kodo" key="class-column"
 *                         value="TEST_CLASS_COLUMN"
 *
 *  @author                Marc Prud'hommeaux
 */
public class TestDoclet
{
  /**
   *  @jdo:primary-key      true
   *  @jdo:extension        vendor-name="kodo" key="column-length"
   *                        value="10"
   */
  private String pk1;

  /**
   *  @jdo:primary-key      true
   *  @jdo:extension        vendor-name="kodo" key="column-length"
   *                        value="20"
   */
  private String pk2;

  /**
   *  @jdo:persistence-modifier  transactional
   *  @jdo:null-value            exception
   *  @jdo:default-fetch-group   true
   *  @jdo:embedded              true
   *  @jdo:extension             vendor-name="kodo" key="data-column"
   *                             value="NAME_DATA"
   */
  private String name;

  /**
   *  @jdo:extension    vendor-name="kodo" key="data-column"
   *                    value="MEMO_COLUMN"
   *  @jdo:extension    vendor-name="kodo" key="column-length"
   *                    value="-1"
   */
  private String memo;

  /**
   *  @jdo:extension    vendor-name="kodo" key="data-column"
   *                    value="AGE_DATA"
   */
  private int age;

  /**
   *  @jdo:collection   element-type="TestDocletChild"
   *                    embedded-element="false"
   *  @jdo:extension    vendor-name="kodo" key="table"
   *                    value="TEST_XREF_DOCLET_TABLE"
   *  @jdo:extension    vendor-name="kodo" key="ref-column"
   *                    value="TEST_CHILDREN_REF_COLUMN"
   *  @jdo:extension    vendor-name="kodo" key="order-column"
   *                    value="TEST_CHILDREN_ORDER_COLUMN"
   *  @jdo:extension    vendor-name="kodo" key="inverse"
   *                    value="childInverse"
   */
  private Collection children = new ArrayList ();

  /**
   *  @jdo:map          key-type="String" embedded-key="false"
   *                    value-type="Integer" embedded-key="false"
   *  @jdo:extension    vendor-name="kodo" key="key-column"
   *                    value="TEST_MAP_KEY"
   */
  private Map testMap = new HashMap ();

  /**
   *  Application identity class.
   */
  public static class Id
  {
    public String pk1;
    public String pk2;

    public boolean equals (Object other)
    {
      return other.getClass () == this.getClass () &&
        ((Id)other).pk1.equals (pk1) &&
        ((Id)other).pk2.equals (pk2);
    }

    public int hashCode ()
    {
      return pk1.hashCode () + pk2.hashCode ();
    }
  }
}
		

<?xml version="1.0" encoding="UTF-8"?>
<!--
  This file is auto-generated by the
  com.solarmetric.modules.integration.ant.JDODoclet ant task.
  Bear in mind that any changes to this file will be overwritten
  if the task is re-run.
-->
<jdo>
  <package name="samples.xdoclet">
    <class name="TestDoclet" identity-type="application"
     objectid-class="TestDoclet$Id" requires-extent="false" >
      <extension vendor-name="kodo" key="table"
        value="DOCLET_TEST_TABLE" />
      <extension vendor-name="kodo" key="pk-column"
        value="TEST_PK_COLUMN" />
      <extension vendor-name="kodo" key="lock-column"
        value="TEST_LOCK_COLUMN" />
      <extension vendor-name="kodo" key="class-column"
        value="TEST_CLASS_COLUMN" />
      <field name="age">
        <extension vendor-name="kodo" key="data-column"
          value="AGE_DATA" />
      </field>
      <field name="children">
        <collection element-type="TestDocletChild" embedded-element="false" />
        <extension vendor-name="kodo" key="table"
          value="TEST_XREF_DOCLET_TABLE" />
        <extension vendor-name="kodo" key="ref-column"
          value="TEST_CHILDREN_REF_COLUMN" />
        <extension vendor-name="kodo" key="order-column"
          value="TEST_CHILDREN_ORDER_COLUMN" />
        <extension vendor-name="kodo" key="inverse"
          value="childInverse" />
      </field>
      <field name="memo">
        <extension vendor-name="kodo" key="data-column"
          value="MEMO_COLUMN" />
        <extension vendor-name="kodo" key="column-length"
          value="-1" />
      </field>
      <field persistence-modifier="transactional" null-value="exception"
       default-fetch-group="true" embedded="true" name="name">
        <extension vendor-name="kodo" key="data-column"
          value="NAME_DATA" />
      </field>
      <field primary-key="true" name="pk1">
        <extension vendor-name="kodo" key="column-length"
          value="10" />
      </field>
      <field primary-key="true" name="pk2">
        <extension vendor-name="kodo" key="column-length"
          value="20" />
      </field>
      <field name="testMap">
        <map key-type="String" embedded-key="false" value-type="Integer" />
        <extension vendor-name="kodo" key="key-column"
          value="TEST_MAP_KEY" />
      </field>
    </class>
    </package>
</jdo>
		

Kodo JDO provides integration into JBuilder 7 and higher in the form of a JBuilder OpenTool. The integration features allow the JBuilder user to configure the Kodo runtime, edit .jdo metadata files (both as raw XML and via a specialized editor), automatically run the JDO Enhancer as part of the build process, and perform various schema manipulation tasks.

9.4.1. Installing Kodo into JBuilder

To install Kodo support in JBuilder, just copy all the .jar files from the lib/ directory of your Kodo installation to the lib/ext/ directory of JBuilder, and copy the lib/KodoJDO.library to JBuilder's lib/ directory. For example, if Kodo is installed in C:\development\kodo\ and JBuilder is installed in C:\JBuilder7\, then you would copy all the .jar files from C:\development\kodo\lib\ to C:\JBuilder7\lib\ext\, and then copy the C:\development\kodo\lib\KodoJDO.library file to C:\JBuilder7\lib\.

To validate the installation, you should start (or restart) JBuilder. You should see the Kodo logo in the build toolbar, which is used to configure the Kodo installation.

	Note
	If you use the Windows Installer program to install Kodo, and you elected to perform the "Install Kodo JBuilder extensions", then you do not need to perform the manually file copying or any other additional steps.

	Warning
	The Kodo JBuilder OpenTool only works in JBuilder 7 and 8. It will not work in releases of JBuilder prior to version 7.

9.4.3. Creating and building JDO projects in JBuilder

When right-clicking on a .java in JBuilder, you will see an option to "Create Kodo JDO Metadata". This will create a default .jdo file for the selected .java file. The .jdo file that is created will then be edit-able in the JBuilder interface, either manually as an XML text file, or via the integrated metadata editor. For more details on JDO metadata, please see the Metadata section.

	Note
	Creating and editing package.jdo metadata files for multiple classes is currently not supported in the JBuilder interface.

The JDO enhancer will be automatically run on any .class file that has an associated .jdo metadata file during the JBuilder build process. Furthermore, the .jdo file will be copied over to the output directory, so that it will be available at runtime.

Kodo JDO can integrate with both Sun ONE Studio and NetBeans IDE as an OpenIDE module. The module requires versions 4.0 and 3.4 or higher of Sun ONE Studio and NetBeans IDE respectively. The module provides support for integrating jdo metadata files into the IDE, easy access to the SchemaTool and enhancer, links into the build process to support enhancement, and wizards to help in the creation of JDO specific files.

The versions that the plugin has been tested are 1.0 and 2.0 of the Eclipse IDE, and version 4 and 5 of WebSphere Studio Application Developer. While the plugin may work on other IDEs based upon Eclipse technology, they have not been tested and may not be fully supported.

Kodo JDO integrates as a plugin to IDEs based upon the open source Eclipse technology. The plugin provides quick access to many of Kodo's features, including metadata enhancement, SchemaTool, and building projects.

Kodo can be integrated with your J2EE applications in a number of ways. The simplest is just to include the Kodo libraries in a J2EE EAR file and call Kodo directly from there. This will be problematic, however, if you want Kodo to share resources with other beans or if you have multiple beans deployed that need to use the same Kodo resource.

The second way to integrate Kodo is to configure and bind an instance of com.solarmetric.kodo.impl.jdbc.ee.EEPersistenceManagerFactory into JNDI. Although the mechanism by which you do this is up to you, the most common way is to create a startup class according to your application server's documentation that will create an instance of EEPersistenceManagerFactory and then bind it in JNDI. For example, in WebLogic you could write a startup class as follows::

package samples.weblogic.kodo;

import javax.naming.*;
import weblogic.common.T3ServicesDef;
import weblogic.common.T3StartupDef;
import java.util.Hashtable;
import com.solarmetric.kodo.impl.jdbc.ee.EEPersistenceManagerFactory;

/**
 * This startup class created and binds an instance of a
 * Kodo EEPersistenceManagerFactory into JNDI.
 */
public class StartKodo
    implements T3StartupDef
{   
    private static String myJNDIName = "my.jndi.name";
    private T3ServicesDef services;

    public void setServices (T3ServicesDef services)
    {
        this.services = services;
    }

    public String startup (String name, Hashtable args) 
        throws Exception 
    {
        String jndi = (String)args.get ("jndiname");
        if (jndi == null || jndi.length () == 0)
            jndi = myJNDIName;

        EEPersistenceManagerFactory factory =
            new EEPersistenceManagerFactory ();

        // you could perform additional configuration of the
        // EEPersistenceManagerFactory here. Otherwise, the values
        // from the Kodo properties or system.prefs will be used.

        InitialContext ic = new InitialContext ();
        ic.bind (jndi, factory);

        // return a message for logging
        return "Bound EEPersistenceManagerFactory to " + jndi;
    }
}
		

PersistenceManagerFactory factory = (PersistenceManagerFactory)
	new InitialContext ().lookup ("java:/MyKodoJNDIName");
PersistenceManager pm = factory.getPersistenceManager ();
			

The third way to integrate Kodo in an application server is to utilize the Java Connector Architecture features of Kodo as described below.

When loading the default fetch group fields into a PersistenceCapable object that is not involved in a transaction, Kodo JDO will set the jdoFlags field of the object to READ_OK. This means that subsequent read operations will not be mediated by the StateManager, reducing the number of method calls and therefore increasing performance.

When loading the default fetch group fields into a PersistenceCapable object that is involved in a transaction, the jdoFlags field of the object to READ_WRITE_OK. This means that subsequent write operations to fields in the default fetch group will not perform checks against the data store, or otherwise access the StateManager. Additionally, when writing the data back out to the data store, all fields in the default fetch group will be written. This is because Kodo JDO does not intercept writes to fields in the default fetch group after they have been loaded, so it is impossible to know which of these fields have been modified. This may result in undesirable data store behavior, including unexpected firing of triggers. Explicitly removing elements from the default fetch group will resolve this.

See section 20.9.3 of the JDO specification for more details about this behavior.

When the javax.jdo.option.Optimistic option is enabled, or optimistic locking is otherwise turned on, Kodo will utilize the value of the lock-column metadata extension (which default to JDOLOCKX) to determine which column to use for its "lock column". The lock column holds an interger which is incremented each time changes are committed to the object, and is utilizied to determine whether an optimistic transaction should succeed or fail.

We have provided an implementation of Animal and Dog classes, plus some helper classes and files to create the initial schema and populate the database with some sample dogs. Let's take a closer look at these classes.