This document is intended for Kodo users. It is divided into several parts:

<sales@solarmetric.com>

+1 202-595-2064 x2

This download includes the commercially available release of Kodo version 4.0.0. Kodo is an implementation of the Java Persistence API and Java Data Objects specifications for relational databases. A copy of each specification is provided in the documentation.

You just downloaded one of the following:

This document is intended for developers who want to learn about EJB persistence in order to use it in their applications. It assumes that you have a strong knowledge of object-oriented concepts and Java, including Java 5 annotations and generics. It also assumes some experience with relational databases and the Structured Query Language (SQL).

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.

Lightweight 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 lightweight persistence because it can be used to persist Java objects directly to a file with very little effort. The capabilities of serialization as a lightweight persistence mechanism pale, however, in comparison to those provided by EJB. The next chapter compares EJB to serialization and other available persistence mechanisms.

The diagram above depicts the EJB persistence exception architecture. All exceptions are unchecked. EJB persistence uses standard exceptions where appropriate, most notably IllegalArgumentExceptions and IllegalStateExceptions. The specification also provides a few EJB-specific exceptions in the javax.persistence package. These exceptions should be self-explanatory. See the Javadoc for additional details on EJB exceptions.

	Note
	All exceptions thrown by Kodo implement kodo.util.ExceptionInfo to provide you with additional error information.

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

4.1.1. Default or No-Arg Constructor

The JPA specification requires that all persistent classes have a no-arg constructor. This constructor may be public or protected. Because the compiler automatically creates a default no-arg constructor when no other constructor is defined, only classes that define constructors must also include a no-arg constructor.

	Note
	Kodo's enhancer will automatically add a protected no-arg constructor to your class when required. Therefore, this restriction does not apply when using Kodo. See Section 5.2, “Enhancement” of the Reference Guide for details.

4.1.2. Final

Entity classes may not be final. No method of an entity class can be final.

	Note
	Kodo supports final classes and final methods.

4.1.3. Identity Fields

All entity classes must declare one or more fields which together form the persistent identity of an instance. These are called identity or primary key fields. In our Magazine class, isbn and title are identity fields, because no two magazine records in the datastore can have the same isbn and title values. Section 5.2.2, “Id” will show you how to denote your identity fields in JPA metadata. Section 4.2, “Entity Identity” below examines persistent identity.

	Note
	Kodo fully supports identity fields, but does not require them. See Section 5.3, “Object Identity” of the Reference Guide for details.

4.1.4. Version Field

The version field in our Magazine class may seem out of place. JPA uses a version field in your entity to detect concurrent modifications to the same datastore record. When the JPA runtime detects an attempt to concurrently modify the same record, it throws an exception to the transaction attempting to commit last. This prevents overwriting the previous commit with stale data.

The version field is not required, but without one concurrent threads or processes might succeed in making conflicting changes to the same record at the same time. This is unacceptable to most applications. Section 5.2.5, “Version” shows you how to designate a version field in JPA metadata.

The version field must be an integral type ( int, Long, etc) or a java.sql.Timestamp. You should consider version fields immutable. Changing the field value has undefined results.

	Note
	Kodo fully supports version fields, but does not require them for concurrency detection. Kodo can maintain surrogate version values or use state comparisons to detect concurrent modifications. See Section 7.7, “Additional JPA Mappings” in the Reference Guide.

4.1.6. Persistent Fields

JPA manages the state of all persistent fields. Before you access persistent state, the JPA runtime makes sure that it has been loaded from the datastore. When you set a field, the runtime 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 JPA's transparency.

JPA does not support static or final fields. It does, however, include 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. JPA supports the following immutable types:

• 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

JPA also supports byte[] and char[] as immutable types. That is, you can persist fields of these types, but you should not manipulate individual array indexes without resetting the array into the persistent field.

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 JPA specification requires that implementations support the following mutable field types:

• java.util.Date

• java.util.Calendar

• java.sql.Date

• java.sql.Timestamp

• Enums

• Entity types (relations between entities)

• Embeddable types

• java.util.Collections of entities

• java.util.Sets of entities

• java.util.Lists of entities

• java.util.Maps in which each entry maps the value of one of an entity's fields to that entity.

Collection and map types may be parameterized.

Most JPA implementations also have support for persisting serializable values as binary data in the datastore. Chapter 5, Metadata has more information on persisting serializable types.

	Note
	Kodo also supports arrays, java.lang.Number, java.util.Locale, all JDK 1.2 Set, List, and Map types, collections and maps of immutable and embedded as well as entity types, and many other mutable and immutable field types. Kodo also allows you to plug in support for custom types.

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 numeric identity.

JPA introduces another form of object identity called entity identity or persistent identity. Entity identity tests whether two persistent objects represent the same state in the datastore.

The entity identity of each persistent instance is encapsulated in its identity field(s). If two entities of the same type have the same identity field values, then the two entities represent the same state in the datastore. Each entity's identity field values must be unique among all other entites of the same type.

Identity fields must be primitives, primitive wrappers, Strings, Dates, Timestamps, or embeddable types. Notably, other entities instances can not be used as identity fields.

	Note
	For legacy schemas with binary primary key columns, Kodo also supports using identity fields of type byte[]. When you use a byte[] identity field, you must create an identity class. Identity classes are covered below.

	Warning
	Changing the fields of an embeddable instance while it is assigned to an identity field has undefined results. Always treat embeddable identity instances as immutable objects in your applications.

If you are dealing with a single persistence context (see Section 7.3, “Persistence Context”), then you do not have to compare identity fields to test whether two entity references represent the same state in the datastore. There is a much easier way: the == operator. JPA requires that each persistence context maintain only one JVM object to represent each unique datastore record. Thus, entity identity is equivalent to numeric identity within a persistence context. 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 in the same transaction 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 datastore? 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.

4.2.1. Identity Class

4.2.1.1. Identity Hierarchies

If your entity has only one identity field, you can use the value of that field as the entity's identity object in all EntityManager APIs. Otherwise, you must supply an identity class to use for identity objects. Your identity class must meet the following criteria:

• The class must be public.

• The class must be serializable.

• The class must have a public no-args constructor.

• The names of the non-static fields or properties of the class must be the same as the names of the identity fields or properties of the corresponding entity class, and the types must be identical.

• The equals and hashCode methods of the class must use the values of all fields or properties corresponding to identity fields or properties in the entity class.

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

• All entity classes related by inheritance must use the same identity class, or else each entity class must have its own identity class whose inheritance hierarchy mirrors the inheritance hierarchy of the owning entity classes (see Section 4.2.1.1, “Identity Hierarchies”).

	Note
	Though you may still create identity classes by hand, Kodo provides the appidtool to automatically generate proper identity classes based on your identity fields. See Section 5.3.2, “Application Identity Tool” of the Reference Guide.

Example 4.2. Identity Class

This example illustrates a proper identity class for an entity with multiple identity fields.

/**
 * Persistent class using application identity.
 */
public class Magazine
{
    private String isbn;    // identity field
    private String title;   // identity field

    // rest of fields and methods omitted


    /**
     * Application identity class for Magazine.
     */
    public static class MagazineId
    {
        // each identity field in the Magazine class must have a
        // corresponding field in the identity class
        public String isbn;
        public String title;

        /**
         * Equality must be implemented in terms of identity field
         * equality, and must use instanceof rather than comparing 
         * classes directly (some JPA implementations may subclass the
         * identity class).
         */
        public boolean equals (Object other)
        {
            if (other == this)
                return true;
            if (!(other instanceof MagazineId))
                return false;
    
            MagazineId mi = (MagazineId) other;
            return (isbn == mi.isbn
                || (isbn != null && isbn.equals (mi.isbn)))
                && (title == mi.title
                || (title != null && title.equals (mi.title)));
        }
     
        /**
         * Hashcode must also depend on identity values.
         */
        public int hashCode ()
        {
            return ((isbn == null) ? 0 : isbn.hashCode ())
                ^ ((title == null) ? 0 : title.hashCode ());
        } 

        public String toString ()
        {
            return isbn + ":" + title;
        }
    }
}

4.2.1.1. Identity Hierarchies

An alternative to having a single identity class for an entire inheritance hierarchy is to have one identity class per level in the inheritance hierarchy. The requirements for using a hierarchy of identity classes are as follows:

• The inheritance hierarchy of identity classes must exactly mirror the hierarchy of the persistent classes that they identify. In the example pictured above, abstract class Person is extended by abstract class Employee, which is extended by non-abstract class FullTimeEmployee, which is extended by non-abstract class Manager. The corresponding identity classes, then, are an abstract PersonId class, extended by an abstract EmployeeId class, extended by a non-abstract FullTimeEmployeeId class, extended by a non-abstract ManagerId class.

• Subclasses in the identity hierarchy may define additional identity fields until the hierarchy becomes non-abstract. In the aforementioned example, Person defines an identity field ssn, Employee defines additional identity field userName, and FullTimeEmployee adds a final identity field, empId. However, Manager may not define any additional identity fields, since it is a subclass of a non-abstract class. The hierarchy of identity classes, of course, must match the identity field definitions of the persistent class hierarchy.

• It is not necessary for each abstract class to declare identity fields. In the previous example, the abstract Person and Employee classes could declare no identity fields, while the first concrete subclass, FullTimeEmployee, could define one or more identity fields.

• All subclasses of a concrete identity class must be equals and hashCode-compatible with the concrete superclass. This means that in our example, a ManagerId instance and a FullTimeEmployeeId instance with the same identity field values should have the same hash code, and should compare equal to each other using the equals method of either one. In practice, this requirement reduces to the following coding practices:

  1. Use instanceof instead of comparing Class objects in the equals methods of your identity classes.

  2. An identity class that extends another non-abstract identity class should not override equals or hashCode.

It is often necessary to perform various actions at different stages of a persistent object's lifecycle. JPA includes a variety of callback methods for monitoring changes in the lifecycle of your persistent objects. These callbacks can be defined on the persistent classes themselves and on non-persistent listener classes.

4.3.2. Using Callback Methods

When declaring callback methods on a persistent class, any method may be used which takes no arguments and is not shared with any property access fields. Multiple events can be assigned to a single method as well.

Below is an example of how to declare callback methods on persistent classes:

/**
 * Example persistent class declaring our entity listener.
 */
@Entity
public class Magazine
{
    @Transient 
    private byte[][] data;

    @ManyToMany
    private List<Photo> photos;

    @PostLoad
    public void convertPhotos ()
    {
        data = new byte[photos.size ()][];
        for (int i = 0; i < photos.size (); i++)
            data[i] = photos.get (i).toByteArray ();
    }

    @PreDelete
    public void logMagazineDeletion ()
    {
        getLog ().debug ("deleting magazine containing" + photos.size () 
            + " photos.");
    }
}

In an XML mapping file, we can define the same methods without annotations:

<entity class="Magazine">
    <pre-remove>logMagazineDeletion</pre-remove>
    <post-load>convertPhotos</post-load>
</entity>

	Note
	We fully explore persistence metadata annotations and XML in Chapter 5, Metadata.

/**
 * Example persistent class declaring our entity listener.
 */
@Entity
@EntityListeners({ MagazineLogger.class, ... })
public class Magazine
{
    // ... //
}


/**
 * Example entity listener.
 */
public class MagazineLogger
{
    @PostPersist
    public void logAddition (Object pc)
    {
        getLog ().debug ("Added new magazine:" + ((Magazine) pc).getTitle ());
    }


    @PreRemove
    public void logDeletion (Object pc)
    {
        getLog ().debug ("Removing from circulation:" + 
            ((Magazine) pc).getTitle ());
    }
}

<entity class="Magazine">
    <entity-listeners>
        <entity-listener class="MagazineLogger">
            <post-persist>logAddition</post-persist>
            <pre-remove>logDeletion</pre-remove>
        </entity-listener>
    </entity-listeners>
</entity>

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

The following metadata annotations and XML elements apply to persistent class declarations.

5.1.1. Entity

The Entity annotation denotes an entity class. All entity classes must have this annotation. The Entity annotation takes one optional property:

• String name: Name used to refer to the entity in queries. It must not be a reserved literal in JPQL. It defaults to the unqualified name of the entity class.

The equivalent XML element is entity. It has the following attributes:

• class: The entity class. This attribute is required.

• name: Named used to refer to the class in queries. See the name property above.

• access: The access type to use for the class. It must either be FIELD or PROPERTY. For details on access types, see Section 5.2, “Field and Property Metadata”.

	Note
	Kodo uses a process called enhancement to modify the bytecode of entities for transparent lazy loading and immediate dirty tracking. See Section 5.2, “Enhancement” in the Reference Guide for details on enhancement.

5.1.3. Mapped Superclass

A mapped superclass is a non-entity class that can define persistent state and mapping information for entity subclasses. Mapped superclasses are usually abstract. Unlike true entities, you cannot query a mapped superclass, pass a mapped superclass instance to any EntityManager or Query methods, or declare a persistent relation with a mapped superclass target. You denote a mapped superclass with the MappedSuperclass marker annotation.

The equivalent XML element is mapped-superclass. It expects the following attributes:

• class: The entity class. This attribute is required.

• access: The access type to use for the class. It must either be FIELD or PROPERTY. For details on access types, see Section 5.2, “Field and Property Metadata”.

	Note
	Kodo allows you to query on mapped superclasses. A query on a mapped superclass will return all matching subclass instances. Kodo also allows you to declare relations to mapped superclass types; however, you cannot query across these relations.

5.1.4. Embeddable

The Embeddable annotation designates an embeddable persistent class. Embeddable instances are stored as part of the record of their owning instance. All embeddable classes must have this annotation.

A persistent class can either be an entity or an embeddable class, but not both.

The equivalent XML element is embeddable. It understands the following attributes:

• class: The entity class. This attribute is required.

• access: The access type to use for the class. It must either be FIELD or PROPERTY. For details on access types, see Section 5.2, “Field and Property Metadata”.

Note

Kodo allows a persistent class to be both an entity and an embeddable class. Instances of the class will act as entites when persisted explicitly or assigned to non-embedded fields of entities. Instances will act as embedded values when assigned to embedded fields of entities. To signal that a class is both an entity and an embeddable class in Kodo, simply add both the @Entity and the @Embeddable annotations to the class.

package org.mag;

@Entity
@IdClass(Magazine.MagazineId.class)
public class Magazine
{
    ...

    public static class MagazineId
    {
        ...
    }
}

@Entity
public class Article
{
    ...
}


package org.mag.pub;

@Entity
public class Company
{
    ...
}

@Entity
public class Author
{
    ...
}

@Embeddable
public class Address
{
    ...
}


package org.mag.subscribe;

@MappedSuperclass
public abstract class Document
{
    ...
}

@Entity
public class Contract
    extends Document
{
    ...
}

@Entity
public class Subscription
{
    ...

    @Entity
    public static class LineItem
        extends Contract
    {
        ...
    }
}

@Entity(name="Lifetime")
public class LifetimeSubscription
    extends Subscription
{
    ...
}

@Entity(name="Trial")
public class TrialSubscription
    extends Subscription
{
    ...
}

<entity-mappings xmlns="http://java.sun.com/xml/ns/persistence/orm" 
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    xsi:schemaLocation="http://java.sun.com/xml/ns/persistence/orm orm_1_0.xsd"
    version="1.0">
    <mapped-superclass class="org.mag.subscribe.Document">
        ...
    </mapped-superclass>
    <entity class="org.mag.Magazine">
        <id-class class="org.mag.Magazine$MagazineId"/>
        ...
    </entity>
    <entity class="org.mag.Article">
        ...
    </entity>
    <entity class="org.mag.pub.Company">
        ...
    </entity>
    <entity class="org.mag.pub.Author">
        ...
    </entity>
    <entity class="org.mag.subscribe.Contract">
        ...
    </entity>
    <entity class="org.mag.subscribe.LineItem">
        ...
    </entity>
    <entity class="org.mag.subscribe.LifetimeSubscription" name="Lifetime">
        ...
    </entity>
    <entity class="org.mag.subscribe.TrialSubscription" name="Trial">
        ...
    </entity>
    <embeddable class="org.mag.pub.Address">
        ...
    </embeddable>
</entity-mappings>

The persistence implementation must be able to retrieve and set the persistent state of your entities, mapped superclasses, and embeddable types. JPA offers two modes of persistent state access: field access, and property access. Under field access, the implementation injects state directly into your persistent fields, and retrieves changed state from your fields as well. To declare field access on an entity with XML metadata, set the access attribute of your entity XML element to FIELD. To use field access for an entity using annotation metadata, simply place your metadata and mapping annotations on your field declarations:

@ManyToOne
private Company publisher;

Property access, on the other hand, retrieves and loads state through JavaBean "getter" and "setter" methods. For a property p of type T, you must define the following getter method:

T getP ();

For boolean properties, this is also acceptable:

boolean isP ();

You must also define the following setter method:

void setP (T value);

To use property access, set your entity element's access attribute to PROPERTY, or place your metadata and mapping annotations on the getter method:

@ManyToOne
private Company getPublisher () { ... }

private void setPublisher (Company publisher) { ... }

Warning

When using property access, only the getter and setter method for a property should ever access the underlying persistent field directly. Other methods, including internal business methods in the persistent class, should go through the getter and setter methods when manipulating persistent state. Also, take care when adding business logic to your getter and setter methods. Consider that they are invoked by the persistence implementation to load and retrieve all persistent state; other side effects might not be desirable.

Each class must use either field access or property access for all state; you cannot use both access types within the same class. Additionally, a subclass must use the same access type as its superclass.

The remainder of this document uses the term "persistent field" to refer to either a persistent field or a persistent property.

5.2.3. Generated Value

The previous section showed you how to declare your identity fields with the Id annotation. It is often convenient to allow the persistence implementation to assign a unique value to your identity fields automatically. JPA includes the the GeneratedValue annotation for this purpose. You can only apply the GeneratedValue annotation to numeric fields. It has the following properties:

• GenerationType strategy: Enum value specifying how to auto-generate the field value. The GenerationType enum has the following values:

  • GeneratorType.AUTO: The default. Assign the field a generated value, leaving the details to the JPA vendor.

  • GenerationType.IDENTITY: The database will assign an identity value on insert.

  • GenerationType.SEQUENCE: Use a datastore sequence to generate a field value.

  • GenerationType.TABLE: Use a sequence table to generate a field value.

• String generator: The name of a generator defined in mapping metadata. We show you how to define named generators in Section 12.5, “Generators”. If the GenerationType is set but this property is unset, the JPA implementation uses appropriate defaults for the selected generation type.

The equivalent XML element is generated-value, which includes the following attributes:

• strategy: One of TABLE, SEQUENCE, IDENTITY, or AUTO, defaulting to AUTO.

• generator: Equivalent to the generator property listed above.

Note

Kodo allows you to use the GeneratedValue annotation on any field, not just identity fields. Before using the IDENTITY generation strategy, however, read Section 5.3.3, “Autoassign / Identity Strategy Caveats” in the Reference Guide. Kodo also offers two additional generator strategies for non-numeric fields, which you can access by setting strategy to AUTO (the default), and setting the generator string to: uuid-string: Kodo will generate a 128-bit UUID unique within the network, represented as a 16-character string. For more information on UUIDs, see the IETF UUID draft specification at: http://www1.ics.uci.edu/~ejw/authoring/uuid-guid/ uuid-hex: Same as uuid-string, but represents the UUID as a 32-character hexadecimal string. These string constants are defined in kodo.persistence.Generator.

5.2.6. Basic

5.2.6.1. Fetch Type

Basic signifies a standard value persisted as-is to the datastore. You can use the Basic annotation on persistent fields of the following types: primitives, primitive wrappers, java.lang.String, byte[], Byte[], char[], Character[], java.math.BigDecimal, java.math.BigInteger, java.util.Date, java.util.Calendar, java.sql.Date, java.sql.Timestamp, Enums, and Serializable types.

Basic declares these properties:

• FetchType fetch: Whether to load the field eagerly (FetchType.EAGER) or lazily (FetchType.LAZY). The default is FetchType.EAGER.

• boolean optional: Whether the datastore allows null values. The defaults is true.

The equivalent XML element is basic. It has the following attributes:

• name: The name of the field or property. This attribute is required.

• fetch: One of EAGER orLAZY.

• optional: Boolean indicating whether the field value may be null.

5.2.6.1. Fetch Type

Many metadata annotations in JPA have a fetch property. This property can take on one of two values: FetchType.EAGER or FetchType.LAZY. FetchType.EAGER means that the field is loaded by the JPA implementation before it returns the persistent object to you. Whenever you retrieve an entity from a query or from the EntityManager, you are guaranteed that all of its eager fields are populated with datastore data.

FetchType.LAZY is a hint to the JPA runtime that you want to defer loading of the field until you access it. This is called lazy loading. Lazy loading is completely transparent; when you attempt to read the field for the first time, the JPA runtime will load the value from the datastore and populate the field automatically. Lazy loading is only a hint and not a directive because some JPA implementations cannot lazy-load certain field types.

With a mix of eager and lazily-loaded fields, you can ensure that commonly-used fields load efficiently, and that other state loads transparently when accessed. As you will see in Section 7.3, “Persistence Context”, you can also use eager fetching to ensure that entites have all needed data loaded before they become detached at the end of a persistence context.

	Note
	Kodo can lazy-load any field type. Kodo also allows you to dynamically change which fields are eagerly or lazily loaded at runtime. See Section 5.6, “Fetch Groups” in the Reference Guide for details. The Reference Guide details Kodo's eager fetching behavior in Section 5.7, “Eager Fetching”.

@ManyToOne(cascade={CascadeType.PERSIST,CascadeType.REMOVE,
    CascadeType.REFRESH,CascadeType.MERGE})
private Company publisher;

@ManyToOne(cascade=CascadeType.ALL)
private Company publisher;

<many-to-one name="publisher">
    <cascade>
        <cascade-persist/>
        <cascade-merge/>
        <cascade-remove/>
        <cascade-refresh/>
    </cascade>
</many-to-one>

<many-to-one name="publisher">
    <cascade>
        <cascade-all/>
    </cascade>
</many-to-one>

5.2.9. One-To-Many

5.2.9.1. Bidirectional Relations

When an entity A references multiple B entities, and no two As reference the same B, we say there is a one-to-many relation from A to B.

One-to-many relations are the exact inverse of the many-to-one relations we detailed in the preceding section. In that section, we said that the Magazine.publisher field is a many-to-one relation from magazines to publishers. But now we see that the Company.mags field is the inverse - a one-to-many relation from publishers to magazines. Each company may publish multiple magazines, but each magazine can have only one publisher.

JPA indicates one-to-many relations between entities with the OneToMany annotation. This annotation has the following properties:

• Class targetEntity: The class of the related entity type. This information is usually taken from the parameterized collection or map element type. You must supply it explicitly, however, if your field isn't a parameterized type.

• String mappedBy: Names the many-to-one field in the related entity that maps this bidirectional relation. We explain bidirectional relations below. Leaving this property unset signals that this is a standard unidirectional relation.

• CascadeType[] cascade: Array of enum values defining cascade behavior for the collection elements. We explore cascades above in Section 5.2.8.1, “Cascade Type”. The defaults is an empty array.

• FetchType fetch: Whether to load the field eagerly (FetchType.EAGER) or lazily (FetchType.LAZY). The defaults is FetchType.LAZY. See Section 5.2.6.1, “Fetch Type” above for details on fetch types.

The equivalent XML element is one-to-many, which includes the following attributes:

• name: The name of the field or property. This attribute is required.

• target-entity: The class of the related type.

• fetch: Either EAGER or LAZY.

• mapped-by: The name of the field or property that owns the relation. See Section 5.2, “Field and Property Metadata”.

You may also nest the cascade element within a one-to-many element.

5.2.9.1. Bidirectional Relations

When two fields are logical inverses of each other, they form a bidirectional relation. Our model contains two bidirectional relations: Magazine.publisher and Company.mags form one bidirectional relation, and Article.authors and Author.articles form the other. In both cases, there is a clear link between the two fields that form the relationship. A magazine refers to its publisher while the publisher refers to all its published magazines. An article refers to its authors while each author refers to his or her written articles.

When the two fields of a bidirectional relation share the same datastore mapping, JPA formalizes the connection with the mappedBy property. Marking Company.mags as mappedBy Magazine.publisher means two things:

1. Company.mags uses the datastore mapping for Magazine.publisher, but inverses it. In fact, it is illegal to specify any additional mapping information when you use the mappedBy property. All mapping information is read from the referenced field. We explore mapping in depth in Chapter 12, Mapping Metadata.

2. Magazine.publisher is the "owner" of the relation. The field that specifies the mapping data is always the owner. This means that changes to the Magazine.publisher field are reflected in the datastore, while changes to the Company.mags field alone are not. Changes to Company.mags may still affect the JPA implementation's cache, however. Thus, it is very important that you keep your object model consistent by properly maintaining both sides of your bidirectional relations at all times.

You should always take advantage of the mappedBy property rather than mapping each field of a bidirectional relation independently. Failing to do so may result in the JPA implementation trying to update the database with conflicting data. Be careful, however, to only mark one side of the relation as mappedBy. One side has to actually do the mapping!

	Note
	You can configure Kodo to automatically synchronize both sides of a bidirectional relation, or to perform various actions when it detects inconsistent relations. See Section 5.4, “Managed Inverses” in the Reference Guide for details.

5.2.12. Order By

Datastores such as relational databases do not preserve the order of records. Your persistent List fields might be ordered one way the first time you retrieve an object from the datastore, and a completely different way the next. To ensure consistent ordering of collection fields, you must use the OrderBy annotation. The OrderBy annotation's value is a string defining the order of the collection elements. An empty value means to sort on the identity value(s) of the elements in ascending order. Any other value must be of the form:

<field name>[ ASC|DESC][, ...]

Each <field name> is the name of a persistent field in the collection's element type. You can optionally follow each field by the keyword ASC for ascending order, or DESC for descending order. If the direction is omitted, it defaults to ascending.

The equivalent XML element is order-by, which can be listed as a sub-element of the one-to-many or many-to-many elements. The text within this element is parsed as the order by string.

	Note
	Kodo expands the available ordering syntax. See Section 6.4.2.3, “Order-By” in the Reference Guide for details.

We present the complete XML schema below. Many of the elements relate to object/relational mapping rather than metadata; these elements are discussed in Chapter 12, Mapping Metadata.

<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema targetNamespace="http://java.sun.com/xml/ns/persistence/orm" 
  xmlns:orm="http://java.sun.com/xml/ns/persistence/orm" 
  xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
  elementFormDefault="qualified" 
  attributeFormDefault="unqualified" 
  version="1.0">

  <xsd:annotation>
    <xsd:documentation>
      @(#)orm_1_0.xsd 1.0  Feb 14 2006
    </xsd:documentation>
  </xsd:annotation>
  <xsd:annotation>
     <xsd:documentation>

       This is the XML Schema for the persistence object-relational 
       mapping file.
       The file may be named "META-INF/orm.xml" in the persistence 
       archive or it may be named some other name which would be 
       used to locate the file as resource on the classpath.

     </xsd:documentation>
  </xsd:annotation>

  <xsd:complexType name="emptyType"/>

  <xsd:simpleType name="versionType">
    <xsd:restriction base="xsd:token">
      <xsd:pattern value="[0-9]+(\.[0-9]+)*"/>
    </xsd:restriction>
  </xsd:simpleType>

  <!-- **************************************************** -->

  <xsd:element name="entity-mappings">
    <xsd:complexType>
      <xsd:annotation>
        <xsd:documentation>

        The entity-mappings element is the root element of an mapping
        file. It contains the following four types of elements:

        1. The persistence-unit-metadata element contains metadata
        for the entire persistence unit. It is undefined if this element
        occurs in multiple mapping files within the same persistence unit.
        
        2. The package, schema, catalog and access elements apply to all of
        the entity, mapped-superclass and embeddable elements defined in
        the same file in which they occur.

        3. The sequence-generator, table-generator, named-query,
        named-native-query and sql-result-set-mapping elements are global
        to the persistence unit. It is undefined to have more than one
        sequence-generator or table-generator of the same name in the same
        or different mapping files in a persistence unit. It is also 
        undefined to have more than one named-query or named-native-query
        of the same name in the same or different mapping files in a 
        persistence unit.

        4. The entity, mapped-superclass and embeddable elements each define
        the mapping information for a managed persistent class. The mapping
        information contained in these elements may be complete or it may
        be partial.

        </xsd:documentation>
      </xsd:annotation>
      <xsd:sequence>
        <xsd:element name="description" type="xsd:string"
                     minOccurs="0"/>
        <xsd:element name="persistence-unit-metadata" 
                     type="orm:persistence-unit-metadata"
                     minOccurs="0"/>
        <xsd:element name="package" type="xsd:string"
                     minOccurs="0"/>
        <xsd:element name="schema" type="xsd:string"
                     minOccurs="0"/>
        <xsd:element name="catalog" type="xsd:string"
                     minOccurs="0"/>
        <xsd:element name="access" type="orm:access-type"
                     minOccurs="0"/>
        <xsd:element name="sequence-generator" type="orm:sequence-generator"
                     minOccurs="0" maxOccurs="unbounded"/>
        <xsd:element name="table-generator" type="orm:table-generator" 
                     minOccurs="0" maxOccurs="unbounded"/>
        <xsd:element name="named-query" type="orm:named-query" 
                     minOccurs="0" maxOccurs="unbounded"/>
        <xsd:element name="named-native-query" type="orm:named-native-query"
                     minOccurs="0" maxOccurs="unbounded"/>
        <xsd:element name="sql-result-set-mapping" 
                     type="orm:sql-result-set-mapping" 
                     minOccurs="0" maxOccurs="unbounded"/>
        <xsd:element name="mapped-superclass" type="orm:mapped-superclass" 
                     minOccurs="0" maxOccurs="unbounded"/>
        <xsd:element name="entity" type="orm:entity" 
                     minOccurs="0" maxOccurs="unbounded"/>
        <xsd:element name="embeddable" type="orm:embeddable" 
                     minOccurs="0" maxOccurs="unbounded"/>
      </xsd:sequence>
      <xsd:attribute name="version" type="orm:versionType" 
                     fixed="1.0" use="required"/>
    </xsd:complexType>
  </xsd:element>

  <!-- **************************************************** -->

  <xsd:complexType name="persistence-unit-metadata">
    <xsd:annotation>
      <xsd:documentation>

        Metadata that applies to the persistence unit and not just to 
        the mapping file in which it is contained. 

        If the xml-mapping-metadata-complete element is specified then 
        the complete set of mapping metadata for the persistence unit 
        is contained in the XML mapping files for the persistence unit.

      </xsd:documentation>
    </xsd:annotation>
    <xsd:sequence>
      <xsd:element name="xml-mapping-metadata-complete" type="orm:emptyType"
                   minOccurs="0"/>
      <xsd:element name="persistence-unit-defaults" 
                   type="orm:persistence-unit-defaults"
                   minOccurs="0"/>
    </xsd:sequence>
  </xsd:complexType>

  <!-- **************************************************** -->

  <xsd:complexType name="persistence-unit-defaults">
    <xsd:annotation>
      <xsd:documentation>

        These defaults are applied to the persistence unit as a whole 
        unless they are overridden by local annotation or XML 
        element settings. 
        
        schema - Used as the schema for all tables or secondary tables
            that apply to the persistence unit
        catalog - Used as the catalog for all tables or secondary tables
            that apply to the persistence unit
        access - Used as the access type for all managed classes in
            the persistence unit
        cascade-persist - Adds cascade-persist to the set of cascade options
            in entity relationships of the persistence unit
        entity-listeners - List of default entity listeners to be invoked 
            on each entity in the persistence unit. 

      </xsd:documentation>
    </xsd:annotation>
    <xsd:sequence>
        <xsd:element name="schema" type="xsd:string"
                     minOccurs="0"/>
        <xsd:element name="catalog" type="xsd:string"
                     minOccurs="0"/>
        <xsd:element name="access" type="orm:access-type"
                     minOccurs="0"/>
        <xsd:element name="cascade-persist" type="orm:emptyType" 
                     minOccurs="0"/>
        <xsd:element name="entity-listeners" type="orm:entity-listeners"
                     minOccurs="0"/>
    </xsd:sequence>
  </xsd:complexType>

  <!-- **************************************************** -->

  <xsd:complexType name="entity">
    <xsd:annotation>
      <xsd:documentation>

        Defines the settings and mappings for an entity. Is allowed to be
        sparsely populated and used in conjunction with the annotations.
        Alternatively, the metadata-complete attribute can be used to 
        indicate that no annotations on the entity class (and its fields
        or properties) are to be processed. If this is the case then 
        the defaulting rules for the entity and its subelements will 
        be recursively applied.

        @Target(TYPE) @Retention(RUNTIME)
          public @interface Entity {
          String name() default "";
        }

      </xsd:documentation>
    </xsd:annotation>
    <xsd:sequence>
      <xsd:element name="description" type="xsd:string" minOccurs="0"/>
      <xsd:element name="table" type="orm:table" 
                   minOccurs="0"/>
      <xsd:element name="secondary-table" type="orm:secondary-table" 
                   minOccurs="0" maxOccurs="unbounded"/>
      <xsd:element name="primary-key-join-column" 
                   type="orm:primary-key-join-column" 
                   minOccurs="0" maxOccurs="unbounded"/>
      <xsd:element name="id-class" type="orm:id-class" minOccurs="0"/>
      <xsd:element name="inheritance" type="orm:inheritance" minOccurs="0"/>
      <xsd:element name="discriminator-value" type="orm:discriminator-value" 
                   minOccurs="0"/>
      <xsd:element name="discriminator-column" 
                   type="orm:discriminator-column" 
                   minOccurs="0"/>
      <xsd:element name="sequence-generator" type="orm:sequence-generator" 
                   minOccurs="0"/>
      <xsd:element name="table-generator" type="orm:table-generator" 
                   minOccurs="0"/>
      <xsd:element name="named-query" type="orm:named-query" 
                   minOccurs="0" maxOccurs="unbounded"/>
      <xsd:element name="named-native-query" type="orm:named-native-query" 
                   minOccurs="0" maxOccurs="unbounded"/>
      <xsd:element name="sql-result-set-mapping" 
                   type="orm:sql-result-set-mapping" 
                   minOccurs="0" maxOccurs="unbounded"/>
      <xsd:element name="exclude-default-listeners" type="orm:emptyType" 
                   minOccurs="0"/>
      <xsd:element name="exclude-superclass-listeners" type="orm:emptyType" 
                   minOccurs="0"/>
      <xsd:element name="entity-listeners" type="orm:entity-listeners" 
                   minOccurs="0"/>
      <xsd:element name="pre-persist" type="orm:pre-persist" minOccurs="0"/>
      <xsd:element name="post-persist" type="orm:post-persist" 
                   minOccurs="0"/>
      <xsd:element name="pre-remove" type="orm:pre-remove" minOccurs="0"/>
      <xsd:element name="post-remove" type="orm:post-remove" minOccurs="0"/>
      <xsd:element name="pre-update" type="orm:pre-update" minOccurs="0"/>
      <xsd:element name="post-update" type="orm:post-update" minOccurs="0"/>
      <xsd:element name="post-load" type="orm:post-load" minOccurs="0"/>
      <xsd:element name="attribute-override" type="orm:attribute-override" 
                   minOccurs="0" maxOccurs="unbounded"/>
      <xsd:element name="association-override" 
                   type="orm:association-override"
                   minOccurs="0" maxOccurs="unbounded"/>
      <xsd:element name="attributes" type="orm:attributes" minOccurs="0"/>
    </xsd:sequence>
    <xsd:attribute name="name" type="xsd:string"/>
    <xsd:attribute name="class" type="xsd:string" use="required"/>
    <xsd:attribute name="access" type="orm:access-type"/>
    <xsd:attribute name="metadata-complete" type="xsd:boolean"/>
  </xsd:complexType>

  <!-- **************************************************** -->

  <xsd:complexType name="attributes">
    <xsd:annotation>
      <xsd:documentation>

        This element contains the entity field or property mappings.
        It may be sparsely populated to include only a subset of the
        fields or properties. If metadata-complete for the entity is true
        then the remainder of the attributes will be defaulted according
        to the default rules.

      </xsd:documentation>
    </xsd:annotation>
    <xsd:sequence>
      <xsd:choice>
        <xsd:element name="id" type="orm:id" 
                     minOccurs="0" maxOccurs="unbounded"/>
        <xsd:element name="embedded-id" type="orm:embedded-id" 
                     minOccurs="0"/>
      </xsd:choice>
      <xsd:element name="basic" type="orm:basic"
                   minOccurs="0" maxOccurs="unbounded"/>
      <xsd:element name="version" type="orm:version"
                   minOccurs="0" maxOccurs="unbounded"/>
      <xsd:element name="many-to-one" type="orm:many-to-one"
                   minOccurs="0" maxOccurs="unbounded"/>
      <xsd:element name="one-to-many" type="orm:one-to-many"
                   minOccurs="0" maxOccurs="unbounded"/>
      <xsd:element name="one-to-one" type="orm:one-to-one"
                   minOccurs="0" maxOccurs="unbounded"/>
      <xsd:element name="many-to-many" type="orm:many-to-many" 
                   minOccurs="0" maxOccurs="unbounded"/>
      <xsd:element name="embedded" type="orm:embedded"
                   minOccurs="0" maxOccurs="unbounded"/>
      <xsd:element name="transient" type="orm:transient"
                   minOccurs="0" maxOccurs="unbounded"/>
    </xsd:sequence>
  </xsd:complexType>

  <!-- **************************************************** -->

  <xsd:simpleType name="access-type">
    <xsd:annotation>
      <xsd:documentation>

        This element determines how the persistence provider accesses the
        state of an entity or embedded object.

      </xsd:documentation>
    </xsd:annotation>
    <xsd:restriction base="xsd:token">
      <xsd:enumeration value="PROPERTY"/>
      <xsd:enumeration value="FIELD"/>
    </xsd:restriction>
  </xsd:simpleType>

  <!-- **************************************************** -->

  <xsd:complexType name="entity-listeners">
    <xsd:annotation>
      <xsd:documentation>

        @Target({TYPE}) @Retention(RUNTIME)
        public @interface EntityListeners {
          Class[] value();
        }

      </xsd:documentation>
    </xsd:annotation>
    <xsd:sequence>
      <xsd:element name="entity-listener" type="orm:entity-listener" 
                   minOccurs="0" maxOccurs="unbounded"/>
    </xsd:sequence>
  </xsd:complexType>

  <!-- **************************************************** -->

  <xsd:complexType name="entity-listener">
    <xsd:annotation>
      <xsd:documentation>

        Defines an entity listener to be invoked at lifecycle events
        for the entities that list this listener.

      </xsd:documentation>
    </xsd:annotation>
    <xsd:sequence>
      <xsd:element name="pre-persist" type="orm:pre-persist" minOccurs="0"/>
      <xsd:element name="post-persist" type="orm:post-persist" 
                   minOccurs="0"/>
      <xsd:element name="pre-remove" type="orm:pre-remove" minOccurs="0"/>
      <xsd:element name="post-remove" type="orm:post-remove" minOccurs="0"/>
      <xsd:element name="pre-update" type="orm:pre-update" minOccurs="0"/>
      <xsd:element name="post-update" type="orm:post-update" minOccurs="0"/>
      <xsd:element name="post-load" type="orm:post-load" minOccurs="0"/>
    </xsd:sequence>
    <xsd:attribute name="class" type="xsd:string" use="required"/>
  </xsd:complexType>

  <!-- **************************************************** -->

  <xsd:complexType name="pre-persist">
    <xsd:annotation>
      <xsd:documentation>

        @Target({METHOD}) @Retention(RUNTIME)
        public @interface PrePersist {}

      </xsd:documentation>
    </xsd:annotation>
    <xsd:attribute name="method-name" type="xsd:string" use="required"/>
  </xsd:complexType>

  <!-- **************************************************** -->

  <xsd:complexType name="post-persist">
    <xsd:annotation>
      <xsd:documentation>

        @Target({METHOD}) @Retention(RUNTIME)
        public @interface PostPersist {}

      </xsd:documentation>
    </xsd:annotation>
    <xsd:attribute name="method-name" type="xsd:string" use="required"/>
  </xsd:complexType>

  <!-- **************************************************** -->

  <xsd:complexType name="pre-remove">
    <xsd:annotation>
      <xsd:documentation>

        @Target({METHOD}) @Retention(RUNTIME)
        public @interface PreRemove {}

      </xsd:documentation>
    </xsd:annotation>
    <xsd:attribute name="method-name" type="xsd:string" use="required"/>
  </xsd:complexType>

  <!-- **************************************************** -->

  <xsd:complexType name="post-remove">
    <xsd:annotation>
      <xsd:documentation>

        @Target({METHOD}) @Retention(RUNTIME)
        public @interface PostRemove {}

      </xsd:documentation>
    </xsd:annotation>
    <xsd:attribute name="method-name" type="xsd:string" use="required"/>
  </xsd:complexType>

  <!-- **************************************************** -->

  <xsd:complexType name="pre-update">
    <xsd:annotation>
      <xsd:documentation>

        @Target({METHOD}) @Retention(RUNTIME)
        public @interface PreUpdate {}

      </xsd:documentation>
    </xsd:annotation>
    <xsd:attribute name="method-name" type="xsd:string" use="required"/>
  </xsd:complexType>

  <!-- **************************************************** -->

  <xsd:complexType name="post-update">
    <xsd:annotation>
      <xsd:documentation>

        @Target({METHOD}) @Retention(RUNTIME)
        public @interface PostUpdate {}

      </xsd:documentation>
    </xsd:annotation>
    <xsd:attribute name="method-name" type="xsd:string" use="required"/>
  </xsd:complexType>

  <!-- **************************************************** -->

  <xsd:complexType name="post-load">
    <xsd:annotation>
      <xsd:documentation>

        @Target({METHOD}) @Retention(RUNTIME)
        public @interface PostLoad {}

      </xsd:documentation>
    </xsd:annotation>
    <xsd:attribute name="method-name" type="xsd:string" use="required"/>
  </xsd:complexType>

  <!-- **************************************************** -->

  <xsd:complexType name="query-hint">
    <xsd:annotation>
      <xsd:documentation>

        @Target({}) @Retention(RUNTIME) 
        public @interface QueryHint {
          String name();
          String value();
        }

      </xsd:documentation>
    </xsd:annotation>
    <xsd:attribute name="name" type="xsd:string" use="required"/>
    <xsd:attribute name="value" type="xsd:string" use="required"/>
  </xsd:complexType>

  <!-- **************************************************** -->

  <xsd:complexType name="named-query">
    <xsd:annotation>
      <xsd:documentation>

        @Target({TYPE}) @Retention(RUNTIME)
        public @interface NamedQuery {
          String name();
          String query();
          QueryHint[] hints() default {};
        }

      </xsd:documentation>
    </xsd:annotation>
    <xsd:sequence>
      <xsd:element name="query" type="xsd:string"/>
      <xsd:element name="hint" type="orm:query-hint" 
                   minOccurs="0" maxOccurs="unbounded"/>
    </xsd:sequence>
    <xsd:attribute name="name" type="xsd:string" use="required"/>
  </xsd:complexType>

  <!-- **************************************************** -->

  <xsd:complexType name="named-native-query">
    <xsd:annotation>
      <xsd:documentation>

        @Target({TYPE}) @Retention(RUNTIME)
        public @interface NamedNativeQuery {
          String name();
          String query();
          QueryHint[] hints() default {};
          Class resultClass() default void.class;
          String resultSetMapping() default ""; //named SqlResultSetMapping
        }

      </xsd:documentation>
    </xsd:annotation>
    <xsd:sequence>
      <xsd:element name="query" type="xsd:string"/>
      <xsd:element name="hint" type="orm:query-hint" 
                   minOccurs="0" maxOccurs="unbounded"/>
    </xsd:sequence>
    <xsd:attribute name="name" type="xsd:string" use="required"/>
    <xsd:attribute name="result-class" type="xsd:string"/>
    <xsd:attribute name="result-set-mapping" type="xsd:string"/>
  </xsd:complexType>

  <!-- **************************************************** -->

  <xsd:complexType name="sql-result-set-mapping">
    <xsd:annotation>
      <xsd:documentation>

        @Target({TYPE}) @Retention(RUNTIME)
        public @interface SqlResultSetMapping {
          String name();
          EntityResult[] entities() default {};
          ColumnResult[] columns() default {};
        }

      </xsd:documentation>
    </xsd:annotation>
    <xsd:sequence>
      <xsd:element name="entity-result" type="orm:entity-result" 
                   minOccurs="0" maxOccurs="unbounded"/>
      <xsd:element name="column-result" type="orm:column-result" 
                   minOccurs="0" maxOccurs="unbounded"/>
    </xsd:sequence>
    <xsd:attribute name="name" type="xsd:string" use="required"/>
  </xsd:complexType>

  <!-- **************************************************** -->

  <xsd:complexType name="entity-result">
    <xsd:annotation>
      <xsd:documentation>

        @Target({}) @Retention(RUNTIME)
        public @interface EntityResult {
          Class entityClass();
          FieldResult[] fields() default {};
          String discriminatorColumn() default "";
        }

      </xsd:documentation>
    </xsd:annotation>
    <xsd:sequence>
      <xsd:element name="field-result" type="orm:field-result" 
                   minOccurs="0" maxOccurs="unbounded"/>
    </xsd:sequence>
    <xsd:attribute name="entity-class" type="xsd:string" use="required"/>
    <xsd:attribute name="discriminator-column" type="xsd:string"/>
  </xsd:complexType>

  <!-- **************************************************** -->

  <xsd:complexType name="field-result">
    <xsd:annotation>
      <xsd:documentation>

        @Target({}) @Retention(RUNTIME)
        public @interface FieldResult {
          String name();
          String column();
        }

      </xsd:documentation>
    </xsd:annotation>
    <xsd:attribute name="name" type="xsd:string" use="required"/>
    <xsd:attribute name="column" type="xsd:string" use="required"/>
  </xsd:complexType>

  <!-- **************************************************** -->

  <xsd:complexType name="column-result">
    <xsd:annotation>
      <xsd:documentation>

        @Target({}) @Retention(RUNTIME)
        public @interface ColumnResult {
          String name();
        }

      </xsd:documentation>
    </xsd:annotation>
    <xsd:attribute name="name" type="xsd:string" use="required"/>
  </xsd:complexType>

  <!-- **************************************************** -->

  <xsd:complexType name="table">
    <xsd:annotation>
      <xsd:documentation>

        @Target({TYPE}) @Retention(RUNTIME)
        public @interface Table {
          String name() default "";
          String catalog() default "";
          String schema() default "";
          UniqueConstraint[] uniqueConstraints() default {};
        }

      </xsd:documentation>
    </xsd:annotation>
    <xsd:sequence>
      <xsd:element name="unique-constraint" type="orm:unique-constraint" 
                   minOccurs="0" maxOccurs="unbounded"/>
    </xsd:sequence>
    <xsd:attribute name="name" type="xsd:string"/>
    <xsd:attribute name="catalog" type="xsd:string"/>
    <xsd:attribute name="schema" type="xsd:string"/>
  </xsd:complexType>

  <!-- **************************************************** -->

  <xsd:complexType name="secondary-table">
    <xsd:annotation>
      <xsd:documentation>

        @Target({TYPE}) @Retention(RUNTIME)
        public @interface SecondaryTable {
          String name();
          String catalog() default "";
          String schema() default "";
          PrimaryKeyJoinColumn[] pkJoinColumns() default {};
          UniqueConstraint[] uniqueConstraints() default {};
         }

       </xsd:documentation>
     </xsd:annotation>
     <xsd:sequence>
       <xsd:element name="primary-key-join-column" 
                    type="orm:primary-key-join-column" 
                    minOccurs="0" maxOccurs="unbounded"/>
       <xsd:element name="unique-constraint" type="orm:unique-constraint" 
                    minOccurs="0" maxOccurs="unbounded"/>
    </xsd:sequence>
    <xsd:attribute name="name" type="xsd:string" use="required"/>
    <xsd:attribute name="catalog" type="xsd:string"/>
    <xsd:attribute name="schema" type="xsd:string"/>
  </xsd:complexType>

  <!-- **************************************************** -->

  <xsd:complexType name="unique-constraint">
    <xsd:annotation>
      <xsd:documentation>

        @Target({}) @Retention(RUNTIME)
        public @interface UniqueConstraint {
          String[] columnNames();
        }

      </xsd:documentation>
    </xsd:annotation>
    <xsd:sequence>
      <xsd:element name="column-name" type="xsd:string" 
                   maxOccurs="unbounded"/>
    </xsd:sequence>
  </xsd:complexType>

  <!-- **************************************************** -->

  <xsd:complexType name="column">
    <xsd:annotation>
      <xsd:documentation>

        @Target({METHOD, FIELD}) @Retention(RUNTIME)
        public @interface Column {
          String name() default "";
          boolean unique() default false;
          boolean nullable() default true;
          boolean insertable() default true;
          boolean updatable() default true;
          String columnDefinition() default "";
          String table() default "";
          int length() default 255;
          int precision() default 0; // decimal precision
          int scale() default 0; // decimal scale
        }

      </xsd:documentation>
    </xsd:annotation>
    <xsd:attribute name="name" type="xsd:string"/>
    <xsd:attribute name="unique" type="xsd:boolean"/>
    <xsd:attribute name="nullable" type="xsd:boolean"/>
    <xsd:attribute name="insertable" type="xsd:boolean"/>
    <xsd:attribute name="updatable" type="xsd:boolean"/>
    <xsd:attribute name="column-definition" type="xsd:string"/>
    <xsd:attribute name="table" type="xsd:string"/>
    <xsd:attribute name="length" type="xsd:int"/>
    <xsd:attribute name="precision" type="xsd:int"/>
    <xsd:attribute name="scale" type="xsd:int"/>
  </xsd:complexType>

  <!-- **************************************************** -->

  <xsd:complexType name="join-column">
    <xsd:annotation>
      <xsd:documentation>

        @Target({METHOD, FIELD}) @Retention(RUNTIME)
        public @interface JoinColumn {
          String name() default "";
          String referencedColumnName() default "";
          boolean unique() default false;
          boolean nullable() default true;
          boolean insertable() default true;
          boolean updatable() default true;
          String columnDefinition() default "";
          String table() default "";
        }

      </xsd:documentation>
    </xsd:annotation>
    <xsd:attribute name="name" type="xsd:string"/>
    <xsd:attribute name="referenced-column-name" type="xsd:string"/>
    <xsd:attribute name="unique" type="xsd:boolean"/>
    <xsd:attribute name="nullable" type="xsd:boolean"/>
    <xsd:attribute name="insertable" type="xsd:boolean"/>
    <xsd:attribute name="updatable" type="xsd:boolean"/>
    <xsd:attribute name="column-definition" type="xsd:string"/>
    <xsd:attribute name="table" type="xsd:string"/>
  </xsd:complexType>

  <!-- **************************************************** -->

  <xsd:simpleType name="generation-type">
    <xsd:annotation>
      <xsd:documentation>

        public enum GenerationType { TABLE, SEQUENCE, IDENTITY, AUTO };

      </xsd:documentation>
    </xsd:annotation>
    <xsd:restriction base="xsd:token">
      <xsd:enumeration value="TABLE"/>
      <xsd:enumeration value="SEQUENCE"/>
      <xsd:enumeration value="IDENTITY"/>
      <xsd:enumeration value="AUTO"/>
    </xsd:restriction>
  </xsd:simpleType>

  <!-- **************************************************** -->

  <xsd:complexType name="attribute-override">
    <xsd:annotation>
      <xsd:documentation>

        @Target({TYPE, METHOD, FIELD}) @Retention(RUNTIME)
        public @interface AttributeOverride {
          String name();
          Column column();
        }

      </xsd:documentation>
    </xsd:annotation>
    <xsd:sequence>
      <xsd:element name="column" type="orm:column"/>
    </xsd:sequence>
    <xsd:attribute name="name" type="xsd:string" use="required"/>
  </xsd:complexType>

  <!-- **************************************************** -->

  <xsd:complexType name="association-override">
    <xsd:annotation>
      <xsd:documentation>

        @Target({TYPE, METHOD, FIELD}) @Retention(RUNTIME)
        public @interface AssociationOverride {
          String name();
          JoinColumn[] joinColumns();
        }

      </xsd:documentation>
    </xsd:annotation>
    <xsd:sequence>
      <xsd:element name="join-column" type="orm:join-column"
                   maxOccurs="unbounded"/>
    </xsd:sequence>
    <xsd:attribute name="name" type="xsd:string" use="required"/>
  </xsd:complexType>

  <!-- **************************************************** -->

  <xsd:complexType name="id-class">
    <xsd:annotation>
      <xsd:documentation>

        @Target({TYPE}) @Retention(RUNTIME)
        public @interface IdClass {
          Class value();
        }

      </xsd:documentation>
    </xsd:annotation>
    <xsd:attribute name="class" type="xsd:string" use="required"/>
  </xsd:complexType>

  <!-- **************************************************** -->

  <xsd:complexType name="id">
    <xsd:annotation>
      <xsd:documentation>

        @Target({METHOD, FIELD}) @Retention(RUNTIME)
        public @interface Id {}

      </xsd:documentation>
    </xsd:annotation>
    <xsd:sequence>
      <xsd:element name="column" type="orm:column" 
                   minOccurs="0"/>
      <xsd:element name="generated-value" type="orm:generated-value"
                   minOccurs="0"/>
      <xsd:element name="temporal" type="orm:temporal" 
                   minOccurs="0"/>
      <xsd:element name="table-generator" type="orm:table-generator" 
                   minOccurs="0"/>
      <xsd:element name="sequence-generator" type="orm:sequence-generator"
                   minOccurs="0"/>
    </xsd:sequence>
    <xsd:attribute name="name" type="xsd:string" use="required"/>
  </xsd:complexType>

  <!-- **************************************************** -->

  <xsd:complexType name="embedded-id">
    <xsd:annotation>
      <xsd:documentation>

        @Target({METHOD, FIELD}) @Retention(RUNTIME)
        public @interface EmbeddedId {}

      </xsd:documentation>
    </xsd:annotation>
    <xsd:sequence>
      <xsd:element name="attribute-override" type="orm:attribute-override" 
                   minOccurs="0" maxOccurs="unbounded"/>
    </xsd:sequence>
    <xsd:attribute name="name" type="xsd:string" use="required"/>
  </xsd:complexType>

  <!-- **************************************************** -->

  <xsd:complexType name="transient">
    <xsd:annotation>
      <xsd:documentation>

        @Target({METHOD, FIELD}) @Retention(RUNTIME)
        public @interface Transient {}

      </xsd:documentation>
    </xsd:annotation>
    <xsd:attribute name="name" type="xsd:string" use="required"/>
  </xsd:complexType>

  <!-- **************************************************** -->

  <xsd:complexType name="version">
    <xsd:annotation>
      <xsd:documentation>

        @Target({METHOD, FIELD}) @Retention(RUNTIME)
        public @interface Version {}

      </xsd:documentation>
    </xsd:annotation>
    <xsd:sequence>
      <xsd:element name="column" type="orm:column" minOccurs="0"/>
      <xsd:element name="temporal" type="orm:temporal" minOccurs="0"/>
    </xsd:sequence>
    <xsd:attribute name="name" type="xsd:string" use="required"/>
  </xsd:complexType>

  <!-- **************************************************** -->

  <xsd:complexType name="basic">
    <xsd:annotation>
      <xsd:documentation>

        @Target({METHOD, FIELD}) @Retention(RUNTIME)
        public @interface Basic {
          FetchType fetch() default EAGER;
          boolean optional() default true;
        }

      </xsd:documentation>
    </xsd:annotation>
    <xsd:sequence>
      <xsd:element name="column" type="orm:column" minOccurs="0"/>
      <xsd:choice>
        <xsd:element name="lob" type="orm:lob" minOccurs="0"/>
        <xsd:element name="temporal" type="orm:temporal" minOccurs="0"/>
        <xsd:element name="enumerated" type="orm:enumerated" minOccurs="0"/>
      </xsd:choice>
    </xsd:sequence>
    <xsd:attribute name="name" type="xsd:string" use="required"/>
    <xsd:attribute name="fetch" type="orm:fetch-type"/>
    <xsd:attribute name="optional" type="xsd:boolean"/>
  </xsd:complexType>

  <!-- **************************************************** -->

  <xsd:simpleType name="fetch-type">
    <xsd:annotation>
      <xsd:documentation>

        public enum FetchType { LAZY, EAGER };

      </xsd:documentation>
    </xsd:annotation>
    <xsd:restriction base="xsd:token">
      <xsd:enumeration value="LAZY"/>
      <xsd:enumeration value="EAGER"/>
    </xsd:restriction>
  </xsd:simpleType>

  <!-- **************************************************** -->

  <xsd:complexType name="lob">
    <xsd:annotation>
      <xsd:documentation>

        @Target({METHOD, FIELD}) @Retention(RUNTIME)
        public @interface Lob {}

      </xsd:documentation>
    </xsd:annotation>
  </xsd:complexType>

  <!-- **************************************************** -->

  <xsd:simpleType name="temporal">
    <xsd:annotation>
      <xsd:documentation>

        @Target({METHOD, FIELD}) @Retention(RUNTIME)
        public @interface Temporal {
          TemporalType value();
        }

      </xsd:documentation>
    </xsd:annotation>
    <xsd:restriction base="orm:temporal-type"/>
  </xsd:simpleType>

  <!-- **************************************************** -->

  <xsd:simpleType name="temporal-type">
    <xsd:annotation>
      <xsd:documentation>

        public enum TemporalType {
          DATE, // java.sql.Date
          TIME, // java.sql.Time
          TIMESTAMP // java.sql.Timestamp
        }

      </xsd:documentation>
    </xsd:annotation>
      <xsd:restriction base="xsd:token">
        <xsd:enumeration value="DATE"/>
        <xsd:enumeration value="TIME"/>
        <xsd:enumeration value="TIMESTAMP"/>
     </xsd:restriction>
  </xsd:simpleType>

  <!-- **************************************************** -->

  <xsd:simpleType name="enumerated">
    <xsd:annotation>
      <xsd:documentation>

        @Target({METHOD, FIELD}) @Retention(RUNTIME)
        public @interface Enumerated {
          EnumType value() default ORDINAL;
        }

      </xsd:documentation>
    </xsd:annotation>
    <xsd:restriction base="orm:enum-type"/>
  </xsd:simpleType>

  <!-- **************************************************** -->

  <xsd:simpleType name="enum-type">
    <xsd:annotation>
      <xsd:documentation>

        public enum EnumType {
          ORDINAL,
          STRING
        }

      </xsd:documentation>
    </xsd:annotation>
    <xsd:restriction base="xsd:token">
      <xsd:enumeration value="ORDINAL"/>
      <xsd:enumeration value="STRING"/>
    </xsd:restriction>
  </xsd:simpleType>

  <!-- **************************************************** -->

  <xsd:complexType name="many-to-one">
    <xsd:annotation>
      <xsd:documentation>

        @Target({METHOD, FIELD}) @Retention(RUNTIME)
        public @interface ManyToOne {
          Class targetEntity() default void.class;
          CascadeType[] cascade() default {};
          FetchType fetch() default EAGER;
          boolean optional() default true;
        }

      </xsd:documentation>
    </xsd:annotation>
    <xsd:sequence>
      <xsd:choice>       
        <xsd:element name="join-column" type="orm:join-column" 
                     minOccurs="0" maxOccurs="unbounded"/>
        <xsd:element name="join-table" type="orm:join-table" 
                     minOccurs="0"/>
      </xsd:choice>       
      <xsd:element name="cascade" type="orm:cascade-type" 
                   minOccurs="0"/>
    </xsd:sequence>
    <xsd:attribute name="name" type="xsd:string" use="required"/>
    <xsd:attribute name="target-entity" type="xsd:string"/>
    <xsd:attribute name="fetch" type="orm:fetch-type"/>
    <xsd:attribute name="optional" type="xsd:boolean"/>
  </xsd:complexType>

  <!-- **************************************************** -->

  <xsd:complexType name="cascade-type">
    <xsd:annotation>
      <xsd:documentation>

        public enum CascadeType { ALL, PERSIST, MERGE, REMOVE, REFRESH};

      </xsd:documentation>
    </xsd:annotation>
    <xsd:sequence>
      <xsd:element name="cascade-all" type="orm:emptyType"
                   minOccurs="0"/>
      <xsd:element name="cascade-persist" type="orm:emptyType"
                   minOccurs="0"/>
      <xsd:element name="cascade-merge" type="orm:emptyType"
                   minOccurs="0"/>
      <xsd:element name="cascade-remove" type="orm:emptyType"
                   minOccurs="0"/>
      <xsd:element name="cascade-refresh" type="orm:emptyType"
                   minOccurs="0"/>
    </xsd:sequence>
  </xsd:complexType>

  <!-- **************************************************** -->

  <xsd:complexType name="one-to-one">
    <xsd:annotation>
      <xsd:documentation>

        @Target({METHOD, FIELD}) @Retention(RUNTIME)
        public @interface OneToOne {
          Class targetEntity() default void.class;
          CascadeType[] cascade() default {};
          FetchType fetch() default EAGER;
          boolean optional() default true;
          String mappedBy() default "";
        }

      </xsd:documentation>
    </xsd:annotation>
    <xsd:sequence>
      <xsd:choice>
        <xsd:element name="primary-key-join-column" 
                     type="orm:primary-key-join-column" 
                     minOccurs="0" maxOccurs="unbounded"/>
        <xsd:element name="join-column" type="orm:join-column" 
                     minOccurs="0" maxOccurs="unbounded"/>
        <xsd:element name="join-table" type="orm:join-table" 
                     minOccurs="0"/>
      </xsd:choice>
      <xsd:element name="cascade" type="orm:cascade-type" 
                   minOccurs="0"/>
    </xsd:sequence>
    <xsd:attribute name="name" type="xsd:string" use="required"/>
    <xsd:attribute name="target-entity" type="xsd:string"/>
    <xsd:attribute name="fetch" type="orm:fetch-type"/>
    <xsd:attribute name="optional" type="xsd:boolean"/>
    <xsd:attribute name="mapped-by" type="xsd:string"/>
  </xsd:complexType>

  <!-- **************************************************** -->

  <xsd:complexType name="one-to-many">
    <xsd:annotation>
      <xsd:documentation>

        @Target({METHOD, FIELD}) @Retention(RUNTIME)
        public @interface OneToMany {
          Class targetEntity() default void.class;
          CascadeType[] cascade() default {};
          FetchType fetch() default LAZY;
          String mappedBy() default "";
        }

      </xsd:documentation>
    </xsd:annotation>
    <xsd:sequence>
      <xsd:element name="order-by" type="orm:order-by" 
                   minOccurs="0"/>
      <xsd:element name="map-key" type="orm:map-key" 
                   minOccurs="0"/>
      <xsd:choice>       
        <xsd:element name="join-table" type="orm:join-table" 
                     minOccurs="0"/>
        <xsd:element name="join-column" type="orm:join-column" 
                     minOccurs="0" maxOccurs="unbounded"/>
      </xsd:choice>       
      <xsd:element name="cascade" type="orm:cascade-type" 
                   minOccurs="0"/>
    </xsd:sequence>
    <xsd:attribute name="name" type="xsd:string" use="required"/>
    <xsd:attribute name="target-entity" type="xsd:string"/>
    <xsd:attribute name="fetch" type="orm:fetch-type"/>
    <xsd:attribute name="mapped-by" type="xsd:string"/>
  </xsd:complexType>

  <!-- **************************************************** -->

  <xsd:complexType name="join-table">
    <xsd:annotation>
      <xsd:documentation>

        @Target({METHOD, FIELD}) @Retention(RUNTIME)
        public @interface JoinTable {
          String name() default "";
          String catalog() default "";
          String schema() default "";
          JoinColumn[] joinColumns() default {};
          JoinColumn[] inverseJoinColumns() default {};
          UniqueConstraint[] uniqueConstraints() default {};
        }

      </xsd:documentation>
    </xsd:annotation>
    <xsd:sequence>
      <xsd:element name="join-column" type="orm:join-column" 
                   minOccurs="0" maxOccurs="unbounded"/>
      <xsd:element name="inverse-join-column" type="orm:join-column" 
                   minOccurs="0" maxOccurs="unbounded"/>
      <xsd:element name="unique-constraint" type="orm:unique-constraint" 
                   minOccurs="0" maxOccurs="unbounded"/>
    </xsd:sequence>
    <xsd:attribute name="name" type="xsd:string"/>
    <xsd:attribute name="catalog" type="xsd:string"/>
    <xsd:attribute name="schema" type="xsd:string"/>
  </xsd:complexType>

  <!-- **************************************************** -->

  <xsd:complexType name="many-to-many">
    <xsd:annotation>
      <xsd:documentation>

        @Target({METHOD, FIELD}) @Retention(RUNTIME)
        public @interface ManyToMany {
          Class targetEntity() default void.class;
          CascadeType[] cascade() default {};
          FetchType fetch() default LAZY;
          String mappedBy() default "";
        }

      </xsd:documentation>
    </xsd:annotation>
    <xsd:sequence>
      <xsd:element name="order-by" type="orm:order-by" 
                   minOccurs="0"/>
      <xsd:element name="map-key" type="orm:map-key" 
                   minOccurs="0"/>
      <xsd:element name="join-table" type="orm:join-table" 
                   minOccurs="0"/>
      <xsd:element name="cascade" type="orm:cascade-type" 
                   minOccurs="0"/>
    </xsd:sequence>
    <xsd:attribute name="name" type="xsd:string" use="required"/>
    <xsd:attribute name="target-entity" type="xsd:string"/>
    <xsd:attribute name="fetch" type="orm:fetch-type"/>
    <xsd:attribute name="mapped-by" type="xsd:string"/>
  </xsd:complexType>

  <!-- **************************************************** -->

  <xsd:complexType name="generated-value">
    <xsd:annotation>
      <xsd:documentation>

        @Target({METHOD, FIELD}) @Retention(RUNTIME)
        public @interface GeneratedValue {
          GenerationType strategy() default AUTO;
          String generator() default "";
        }

      </xsd:documentation>
    </xsd:annotation>
    <xsd:attribute name="strategy" type="orm:generation-type"/>
    <xsd:attribute name="generator" type="xsd:string"/>
  </xsd:complexType>

  <!-- **************************************************** -->

  <xsd:complexType name="map-key">
    <xsd:annotation>
      <xsd:documentation>

        @Target({METHOD, FIELD}) @Retention(RUNTIME)
        public @interface MapKey {
          String name() default "";
        }

      </xsd:documentation>
    </xsd:annotation>
    <xsd:attribute name="name" type="xsd:string"/>
  </xsd:complexType>

  <!-- **************************************************** -->

  <xsd:simpleType name="order-by">
    <xsd:annotation>
      <xsd:documentation>

        @Target({METHOD, FIELD}) @Retention(RUNTIME)
        public @interface OrderBy {
          String value() default "";
        }

      </xsd:documentation>
    </xsd:annotation>
    <xsd:restriction base="xsd:string"/>
  </xsd:simpleType>

  <!-- **************************************************** -->

  <xsd:complexType name="inheritance">
    <xsd:annotation>
      <xsd:documentation>

        @Target({TYPE}) @Retention(RUNTIME)
        public @interface Inheritance {
          InheritanceType strategy() default SINGLE_TABLE;
        }

      </xsd:documentation>
    </xsd:annotation>
    <xsd:attribute name="strategy" type="orm:inheritance-type"/>
  </xsd:complexType>

  <!-- **************************************************** -->

  <xsd:simpleType name="inheritance-type">
    <xsd:annotation>
      <xsd:documentation>

        public enum InheritanceType
          { SINGLE_TABLE, JOINED, TABLE_PER_CLASS};

      </xsd:documentation>
    </xsd:annotation>
    <xsd:restriction base="xsd:token">
      <xsd:enumeration value="SINGLE_TABLE"/>
      <xsd:enumeration value="JOINED"/>
      <xsd:enumeration value="TABLE_PER_CLASS"/>
    </xsd:restriction>
  </xsd:simpleType>

  <!-- **************************************************** -->

  <xsd:simpleType name="discriminator-value">
    <xsd:annotation>
      <xsd:documentation>

        @Target({TYPE}) @Retention(RUNTIME)
        public @interface DiscriminatorValue {
          String value();
        }

      </xsd:documentation>
    </xsd:annotation>
    <xsd:restriction base="xsd:string"/>
  </xsd:simpleType>

  <!-- **************************************************** -->

  <xsd:simpleType name="discriminator-type">
    <xsd:annotation>
      <xsd:documentation>

        public enum DiscriminatorType { STRING, CHAR, INTEGER };

      </xsd:documentation>
    </xsd:annotation>
    <xsd:restriction base="xsd:token">
      <xsd:enumeration value="STRING"/>
      <xsd:enumeration value="CHAR"/>
      <xsd:enumeration value="INTEGER"/>
    </xsd:restriction>
  </xsd:simpleType>

  <!-- **************************************************** -->

  <xsd:complexType name="primary-key-join-column">
    <xsd:annotation>
      <xsd:documentation>

        @Target({TYPE, METHOD, FIELD}) @Retention(RUNTIME)
        public @interface PrimaryKeyJoinColumn {
          String name() default "";
          String referencedColumnName() default "";
          String columnDefinition() default "";
        }

      </xsd:documentation>
    </xsd:annotation>
    <xsd:attribute name="name" type="xsd:string"/>
    <xsd:attribute name="referenced-column-name" type="xsd:string"/>
    <xsd:attribute name="column-definition" type="xsd:string"/>
  </xsd:complexType>

  <!-- **************************************************** -->

  <xsd:complexType name="discriminator-column">
    <xsd:annotation>
      <xsd:documentation>

        @Target({TYPE}) @Retention(RUNTIME)
        public @interface DiscriminatorColumn {
          String name() default "DTYPE";
          DiscriminatorType discriminatorType() default STRING;
          String columnDefinition() default "";
          int length() default 31;
        }

      </xsd:documentation>
    </xsd:annotation>
    <xsd:attribute name="name" type="xsd:string"/>
    <xsd:attribute name="discriminator-type" type="orm:discriminator-type"/>
    <xsd:attribute name="column-definition" type="xsd:string"/>
    <xsd:attribute name="length" type="xsd:int"/>
  </xsd:complexType>

  <!-- **************************************************** -->

  <xsd:complexType name="embeddable">
    <xsd:annotation>
      <xsd:documentation>

        Defines the settings and mappings for embeddable objects. Is 
        allowed to be sparsely populated and used in conjunction with 
        the annotations. Alternatively, the metadata-complete attribute 
        can be used to indicate that no annotations are to be processed 
        in the class. If this is the case then the defaulting rules will 
        be recursively applied.

        @Target({TYPE}) @Retention(RUNTIME)
        public @interface Embeddable {}

      </xsd:documentation>
    </xsd:annotation>
    <xsd:sequence>
      <xsd:element name="description" type="xsd:string" minOccurs="0"/>
      <xsd:element name="attributes" type="orm:embeddable-attributes" 
                   minOccurs="0"/>
    </xsd:sequence>
    <xsd:attribute name="class" type="xsd:string" use="required"/>
    <xsd:attribute name="access" type="orm:access-type"/>
    <xsd:attribute name="metadata-complete" type="xsd:boolean"/>
  </xsd:complexType>

  <!-- **************************************************** -->

  <xsd:complexType name="embeddable-attributes">
    <xsd:sequence>
      <xsd:element name="basic" type="orm:basic" 
                   minOccurs="0" maxOccurs="unbounded"/>
      <xsd:element name="transient" type="orm:transient" 
                   minOccurs="0" maxOccurs="unbounded"/>
    </xsd:sequence>
  </xsd:complexType>

  <!-- **************************************************** -->

  <xsd:complexType name="embedded">
    <xsd:annotation>
      <xsd:documentation>

        @Target({METHOD, FIELD}) @Retention(RUNTIME)
        public @interface Embedded {}

      </xsd:documentation>
    </xsd:annotation>
    <xsd:sequence>
      <xsd:element name="attribute-override" type="orm:attribute-override" 
                   minOccurs="0" maxOccurs="unbounded"/>
    </xsd:sequence>
    <xsd:attribute name="name" type="xsd:string" use="required"/>
  </xsd:complexType>

  <!-- **************************************************** -->

  <xsd:complexType name="mapped-superclass">
    <xsd:annotation>
      <xsd:documentation>

        Defines the settings and mappings for a mapped superclass. Is 
        allowed to be sparsely populated and used in conjunction with 
        the annotations. Alternatively, the metadata-complete attribute 
        can be used to indicate that no annotations are to be processed 
        If this is the case then the defaulting rules will be recursively 
        applied.

        @Target(TYPE) @Retention(RUNTIME)
        public @interface MappedSuperclass{}

      </xsd:documentation>
    </xsd:annotation>
    <xsd:sequence>
      <xsd:element name="description" type="xsd:string" minOccurs="0"/>
      <xsd:element name="id-class" type="orm:id-class" minOccurs="0"/>
      <xsd:element name="exclude-default-listeners" type="orm:emptyType" 
                   minOccurs="0"/>
      <xsd:element name="exclude-superclass-listeners" type="orm:emptyType" 
                   minOccurs="0"/>
      <xsd:element name="entity-listeners" type="orm:entity-listeners" 
                   minOccurs="0"/>
      <xsd:element name="pre-persist" type="orm:pre-persist" minOccurs="0"/>
      <xsd:element name="post-persist" type="orm:post-persist" 
                   minOccurs="0"/>
      <xsd:element name="pre-remove" type="orm:pre-remove" minOccurs="0"/>
      <xsd:element name="post-remove" type="orm:post-remove" minOccurs="0"/>
      <xsd:element name="pre-update" type="orm:pre-update" minOccurs="0"/>
      <xsd:element name="post-update" type="orm:post-update" minOccurs="0"/>
      <xsd:element name="post-load" type="orm:post-load" minOccurs="0"/>
      <xsd:element name="attributes" type="orm:attributes" minOccurs="0"/>
    </xsd:sequence>
    <xsd:attribute name="class" type="xsd:string" use="required"/>
    <xsd:attribute name="access" type="orm:access-type"/>
    <xsd:attribute name="metadata-complete" type="xsd:boolean"/>
  </xsd:complexType>

  <!-- **************************************************** -->

  <xsd:complexType name="sequence-generator">
    <xsd:annotation>
      <xsd:documentation>

        @Target({TYPE, METHOD, FIELD}) @Retention(RUNTIME)
        public @interface SequenceGenerator {
          String name();
          String sequenceName() default "";
          int initialValue() default 1;
          int allocationSize() default 50;
        }

      </xsd:documentation>
    </xsd:annotation>
    <xsd:attribute name="name" type="xsd:string" use="required"/>
    <xsd:attribute name="sequence-name" type="xsd:string"/>
    <xsd:attribute name="initial-value" type="xsd:int"/>
    <xsd:attribute name="allocation-size" type="xsd:int"/>
  </xsd:complexType>

  <!-- **************************************************** -->

  <xsd:complexType name="table-generator">
    <xsd:annotation>
      <xsd:documentation>

        @Target({TYPE, METHOD, FIELD}) @Retention(RUNTIME)
        public @interface TableGenerator {
          String name();
          String table() default "";
          String catalog() default "";
          String schema() default "";
          String pkColumnName() default "";
          String valueColumnName() default "";
          String pkColumnValue() default "";
          int initialValue() default 0;
          int allocationSize() default 50;
          UniqueConstraint[] uniqueConstraints() default {};
        }

      </xsd:documentation>
    </xsd:annotation>
    <xsd:sequence>
      <xsd:element name="unique-constraint" type="orm:unique-constraint" 
                   minOccurs="0" maxOccurs="unbounded"/>
    </xsd:sequence>
    <xsd:attribute name="name" type="xsd:string" use="required"/>
    <xsd:attribute name="table" type="xsd:string"/>
    <xsd:attribute name="catalog" type="xsd:string"/>
    <xsd:attribute name="schema" type="xsd:string"/>
    <xsd:attribute name="pk-column-name" type="xsd:string"/>
    <xsd:attribute name="value-column-name" type="xsd:string"/>
    <xsd:attribute name="pk-column-value" type="xsd:string"/>
    <xsd:attribute name="initial-value" type="xsd:int"/>
    <xsd:attribute name="allocation-size" type="xsd:int"/>
  </xsd:complexType>

</xsd:schema>

That exhausts persistence metadata annotations. We present the class definitions for our sample model below:

package org.mag;

@Entity
@IdClass(Magazine.MagazineId.class)
public class Magazine
{
    @Id private String isbn;
    @Id private String title;
    @Version private int version;

    private double price;   // defaults to @Basic
    private int copiesSold; // defaults to @Basic

    @OneToOne(fetch=FetchType.LAZY, 
        cascade={CascadeType.PERSIST,CascadeType.REMOVE})
    private Article coverArticle;

    @OneToMany(cascade={CascadeType.PERSIST,CascadeType.REMOVE})
    @OrderBy
    private Collection<Article> articles;

    @ManyToOne(fetch=FetchType.LAZY, cascade=CascadeType.PERSIST)
    private Company publisher; 

    @Transient private byte[] data;

    ...

    public static class MagazineId
    {
        ...
    }
}

@Entity
public class Article
{
    @Id private long id;
    @Version private int version;
    
    private String title;   // defaults to @Basic
    private byte[] content; // defaults to @Basic

    @ManyToMany(cascade=CascadeType.PERSIST)
    @OrderBy("lastName, firstName")
    private Collection<Author> authors;

    ...
}


package org.mag.pub;

@Entity
public class Company
{
    @Id private long id;
    @Version private int version;

    private String name;     // defaults to @Basic
    private double revenue;  // defaults to @Basic
    private Address address; // defaults to @Embedded
    
    @OneToMany(mappedBy="publisher", cascade=CascadeType.PERSIST)
    private Collection<Magazine> mags;

    @OneToMany(cascade={CascadeType.PERSIST,CascadeType.REMOVE})
    private Collection<Subscription> subscriptions;

    ...
}

@Entity
public class Author
{
    @Id private long id;
    @Version private int version;

    private String firstName; // defaults to @Basic
    private double lastName;  // defaults to @Basic
    private Address address;  // defaults to @Embedded
    
    @ManyToMany(mappedBy="authors", cascade=CascadeType.PERSIST)
    private Collection<Article> arts;

    ...
}

@Embeddable
public class Address
{
    private String street; // defaults to @Basic
    private String city;   // defaults to @Basic
    private String state;  // defaults to @Basic
    private String zip;    // defaults to @Basic

    ...
}


package org.mag.subscribe;

@MappedSuperclass
public abstract class Document
{
    @Id private long id;
    @Version private int version;

    ...
}

@Entity
public class Contract
    extends Document
{
    private String terms; // defaults to @Basic

    ...
}

@Entity
public class Subscription
{
    @Id private long id;
    @Version private int version;

    private Date startDate; // defaults to @Basic
    private double payment; // defaults to @Basic

    @OneToMany(cascade={CascadeType.PERSIST,CascadeType.REMOVE})
    @MapKey(name="num")
    private Map<Long,LineItem> lineItems;

    ...

    @Entity
    public static class LineItem
        extends Contract
    {
        private String comments; // defaults to @Basic
        private double price;    // defaults to @Basic
        private long num;        // defaults to @Basic

        @ManyToOne
        private Magazine magazine;

        ...
    }
}

@Entity(name="Lifetime")
public class LifetimeSubscription
    extends Subscription
{
    @Basic(fetch=FetchType.LAZY)
    private boolean getEliteClub () { ... }
    public void setEliteClub (boolean elite) { ... }

    ...
}

@Entity(name="Trial")
public class TrialSubscription
    extends Subscription
{
    public Date getEndDate () { ... }
    public void setEndDate (Date end) { ... }

    ...
}

<entity-mappings>
    <!-- declares a default access type for all entities -->
    <access-type>FIELD</access-type>
    <mapped-superclass class="org.mag.subscribe.Document">
        <attributes>
            <id name="id">
                <generated-value strategy="IDENTITY"/>
            </id>
            <version name="version"/>
        </attributes>
    </mapped-superclass>
    <entity class="org.mag.Magazine">
        <id-class="org.mag.Magazine$MagazineId"/>
        <attributes>
            <id name="isbn"/>
            <id name="title"/>
            <basic name="name"/>
            <basic name="price"/>
            <basic name="copiesSold"/>
            <version name="version"/>
            <many-to-one name="publisher" fetch="LAZY">
                <cascade>
                    <cascade-persist/>
                </cascade>
            </many-to-one>
            <one-to-many name="articles">
                <order-by/>
                <cascade>
                    <cascade-persist/>
                    <cascade-remove/>
                </cascade>
            </one-to-many>
            <one-to-one name="coverArticle" fetch="LAZY">
                <cascade>
                    <cascade-persist/>
                    <cascade-remove/>
                </cascade>
            </one-to-one>
            <transient name="data"/>
        </attributes>
    </entity>
    <entity class="org.mag.Article">
        <attributes>
            <id name="id"/>
            <basic name="title"/>
            <basic name="content"/>
            <version name="version"/>
            <many-to-many name="articles">
                <order-by>lastName, firstName</order-by>
            </many-to-many>
        </attributes>
    </entity>
    <entity class="org.mag.pub.Company">
        <attributes>
            <id name="id"/>
            <basic name="name"/>
            <basic name="revenue"/>
            <version name="version"/>
            <one-to-many name="mags" mapped-by="publisher">
                <cascade>
                    <cascade-persist/>
                </cascade>
            </one-to-many>
            <one-to-many name="subscriptions">
                <cascade>
                    <cascade-persist/>
                    <cascade-remove/>
                </cascade>
            </one-to-many>
        </attributes>
    </entity>
    <entity class="org.mag.pub.Author">
        <attributes>
            <id name="id"/>
            <basic name="firstName"/>
            <basic name="lastName"/>
            <version name="version"/>
            <many-to-many name="arts" mapped-by="authors">
                <cascade>
                    <cascade-persist/>
                </cascade>
            </many-to-many>
        </attributes>
    </entity>
    <entity class="org.mag.subcribe.Contract">
        <attributes>
            <basic name="terms"/>
        </attributes>
    </entity>
    <entity class="org.mag.subcribe.Subscription">
        <attributes>
            <id name="id"/>
            <basic name="payment"/>
            <basic name="startDate"/>
            <version name="version"/>
            <one-to-many name="items">
                <map-key name="num">
                <cascade>
                    <cascade-persist/>
                    <cascade-remove/>
                </cascade>
            </one-to-many>
        </attributes>
    </entity>
    <entity class="org.mag.subscribe.Subscription.LineItem">
        <attributes>
            <basic name="comments"/>
            <basic name="price"/>
            <basic name="num"/>
            <many-to-one name="magazine"/>
        </attributes>
    </entity>
    <entity class="org.mag.subscribe.LifetimeSubscription" name="Lifetime"
        access="PROPERTY">
        <attributes>
            <basic name="eliteClub" fetch="LAZY"/>
        </attributes>
    </entity>
    <entity class="org.mag.subscribe.TrialSubscription" name="Trial">
        <attributes>
            <basic name="endDate"/>
        </attributes>
    </entity>
    <embeddable class="org.mag.pub.Address">
        <attributes>
            <basic name="street"/>
            <basic name="city"/>
            <basic name="state"/>
            <basic name="zip"/>
        </attributes>
    </embeddable>
</entity-mappings>

Chapter 12, Mapping Metadata will show you how to map your persistent classes to the datastore using additional annotations and XML markup. First, however, we turn to the JPA runtime APIs.

The persistence.xml file format obeys the following Document Type Descriptor (DTD):

<!ELEMENT persistence (persistence-unit*)>
<!ELEMENT persistence-unit (description?,provider?,jta-datasource?,
	non-jta-datasource?,(class|jar-file|mapping-file)*,
	exclude-unlisted-classes?,properties?)>
<!ATTLIST persistence-unit name CDATA #REQUIRED>
<!ATTLIST persistence-unit transaction-type (JTA|RESOURCE_LOCAL) "JTA">
<!ELEMENT description (#PCDATA)>
<!ELEMENT provider (#PCDATA)>
<!ELEMENT jta-datasource (#PCDATA)>
<!ELEMENT non-jta-datasource (#PCDATA)>
<!ELEMENT mapping-file (#PCDATA)>
<!ELEMENT jar-file (#PCDATA)>
<!ELEMENT class (#PCDATA)>
<!ELEMENT exclude-unlisted-classes EMPTY>
<!ELEMENT properties (property*)>
<!ELEMENT property EMPTY>
<!ATTLIST property name CDATA #REQUIRED>
<!ATTLIST property value CDATA #REQUIRED>

The root element of a persistence.xml file is persistence, which then contains one or more persistence-unit definitions. Each persistence unit describes the configuration for the entity managers created by the persistence unit's entity manager factory. The persistence unit can specify these elements and attribtues.

Here is a typical persistence.xml file for a non-EE environment:

<?xml version="1.0"?>
<persistence>
	<persistence-unit name="kodo">
		<provider>kodo.persistence.PersistenceProviderImpl</provider>
		<class>tutorial.Animal</class>
		<class>tutorial.Dog</class>
		<class>tutorial.Rabbit</class>
		<class>tutorial.Snake</class>
		<properties>
			<property name="kodo.ConnectionURL" value="jdbc:hsqldb:tutorial_database"/>
			<property name="kodo.ConnectionDriverName" value="org.hsqldb.jdbcDriver"/>
			<property name="kodo.ConnectionUserName" value="sa"/>
			<property name="kodo.ConnectionPassword" value=""/>
			<property name="kodo.Log" value="DefaultLevel=WARN, Tool=INFO"/>
		</properties>
	</persistence-unit>
</persistence>

The example below demonstrates the Persistence class in action. You will typically execute code like this on application startup, then cache the resulting factory for future use. This bootstrapping code is only necessary in non-EE environments; in an EE environment EntityManagerFactories are typically injected.

// if your persistence.xml file does not contain all settings already, you
// can add vendor settings to a map 
Properties props = new Properties ();
...

// create the factory defined by the "kodo" entity-manager entry
EntityManagerFactory emf = Persistence.createEntityManagerFactory ("kodo", props);

Within a container, you will typically use injection to access an EntityManagerFactory. There are, however, alternative mechanisms for EntityManagerFactory construction.

Some vendors may supply public constructors for their EntityManagerFactory implementations, but we recommend: using the Java Connector Architecture (JCA) in a managed environment; using the Persistence class's createEntityManagerFactory methods in an unmanaged environment, as described in Chapter 6, Persistence. These strategies allow vendors to pool factories, cutting down on resource utilization.

JPA allows you to create and configure an EntityManagerFactory, then store it in a Java Naming and Directory Interface (JNDI) tree for later retrieval and use.

public EntityManager createEntityManager ();
public EntityManager createEntityManager (Map map);

The two createEntityManager methods above create a new EntityManager each time they are invoked. The optional Map is used to to supply vendor-specific settings. If you have configured your implementation for JTA transactions and a JTA transaction is active, the returned EntityManager will be synchronized with that transaction.

Note

Kodo recognizes the following string keys in the map supplied to createEntityManager: kodo.ConnectionUserName kodo.ConnectionPassword kodo.ConnectionRetainMode kodo.TransactionMode kodo.<property>, where <property> is any JavaBean property of the kodo.persistence.KodoEntityManager. The last option uses reflection to configure any property of Kodo's EntityManager implementation with the value supplied in your map. The first options correspond exactly to the same-named Kodo configuration keys described in Chapter 2, Configuration of the Reference Guide.

A persistence context is a set of entities such that for any persistent identity there is a unique entity instance. Within a persistence context, entities are managed. The EntityManager controls their lifecycle, and they can access datastore resources.

When a persistence context ends, previously-managed entities become detached. A detached entity is no longer under the control of the EntityManager, and no longer has access to datastore resources. We discuss detachment is detail in Section 8.2, “Entity Lifecycle Management”. For now, it is sufficient to know that detachment has two obvious consequences:

	Note
	Kodo offers several features related to detaching entities. See Section 11.1, “Detach and Attach” in the Reference Guide. In particular, Section 11.1.3, “Defining the Detached Object Graph” describes how to use the DetachState setting to boost the performance of merging detached entities.

Injected EntityManagers use a transaction persistence context, while EntityManagers obtained through the EntityManagerFactory have an extended persistence context. We describe these persistence context types below.

EntityManager em; // Injected
...

// Outside a transaction:

// Each operation occurs in a separate persistence context and returns 
// a new detached instance.
Magazine mag1 = em.find (Magazine.class, magId);
Magazine mag2 = em.find (Magazine.class, magId);
assertTrue (mag2 != mag1);
...

// Transaction begins:

// Within a transaction, a subsequent lookup doesn't return any of the
// detached objects.  However, two lookups within the same transaction
// return the same instanc, because the persistence context spans the
// transaction.
Magazine mag3 = em.find (Magazine.class, magId);
assertTrue (mag3 != mag1 && mag3 != mag2);
Magazine mag4 = em.find (Magazine.class (magId);
assertTrue (mag4 == mag3);
...

// Transaction commits:

// Once again, each operation returns a new instance.
Magazine mag5 = em.find (Magazine.class, magId);
assertTrue (mag5 != mag3);

EntityManagerFactory emf = ...
EntityManager em = emf.createEntityManager (PersistenceContextType.EXTENDED);

// The persistence context is active for the entire life of the EM, so there is
// only one entity for a given persistent identity.
Magazine mag1 = em.find (Magazine.class, magId);
Magazine mag2 = em.find (Magazine.class, magId);
assertTrue (mag2 == mag1);

em.getTransaction ().begin ();

// The same persistence context is active within the transaction.
Magazine mag3 = em.find (Magazine.class, magId);
assertTrue (mag3 == mag1);
Magazine mag4 = em.find (Magazine.class (magId);
assertTrue (mag4 == mag1);

em.getTransaction.commit ();

// When the transaction commits, the instance is still managed.
Magazine mag5 = em.find (Magazine.class, magId);
assertTrue (mag5 == mag1);

// The instance finally becomes detached when the EM closes.
em.close ();

public boolean isOpen ();
public void close ();

EntityManagerFactory instances are heavyweight objects. Each factory might maintain a metadata cache, object state cache, EntityManager pool, connection pool, and more. If your application no longer needs an EntityManagerFactory, you should close it to free these resources. When an EntityManagerFactory closes, all EntityManagers from that factory, and by extension all entities managed by those EntityManagers, become invalid. Attempting to close an EntityManagerFactory while one or more of its EntityManagers has an active transaction may result in an IllegalStateException.

Closing an EntityManagerFactory should not be taken lightly. It is much better to keep a factory open for a long period of time than to repeatedly create and close new factories. Thus, most applications will never close the factory, or only close it when the application is exiting. Only applications that require multiple factories with different configurations have an obvious reason to create and close multiple EntityManagerFactory instances. Once a factory is closed, all methods except isOpen throw an IllegalStateException.

public EntityTransaction getTransaction ();

Every EntityManager has a one-to-one relation with an EntityTransaction instance. In fact, many vendors use a single class to implement both the EntityManager and EntityTransaction interfaces. If your application requires multiple concurrent transactions, you will use multiple EntityManagers.

You can retrieve the EntityTransaction associated with an EntityManager through the getTransaction method. Note that most EJB persistence implementations can integrate with an application server's managed transactions. If you take advantage of this feature, you will control transactions by declarative demarcation or through the Java Transaction API (JTA) rather than through the EntityTransaction.

EntityManagers perform several actions that affect the lifecycle state of entity instances.

public void persist (Object entity);

The above method transitions new instances to managed instances. On the next flush or commit, the newly persisted instances will be inserted into the datastore.

For a given entity A, the persist method behaves as follows:

This action can only be used in the context of an active transaction.

public void remove (Object entity);

The above method transitions managed instances to removed instances. The instances will be deleted from the datastore on the next flush or commit. Accessing a removed entity has undefined results.

For a given entity A, the remove method behaves as follows:

This action can only be used in the context of an active transaction.

public void refresh (Object entity);

Use the refresh method to make sure the persistent state of an instance is synchronized with the values in the datastore. refresh is intended for long-running optimistic transactions in which there is a danger of seeing stale data.

For a given entity A, the refresh method behaves as follows:

public Object merge (Object entity);

A common use case for an application running in a servlet or application server is to "detach" objects from all server resources, modify them, and then "attach" them again. For example, a servlet might store persistent data in a user session between a modification based on a series of web forms. Between each form request, the web container might decide to serialize the session, requiring that the stored persistent state be disassociated from any other resources. Similarly, a client/server application might transfer persistent objects to a client via serialization, allow the client to modify their state, and then have the client return the modified data in order to be saved. This is sometimes referred to as the data transfer object or value object pattern, and it allows fine-grained manipulation of data objects without incurring the overhead of multiple remote method invocations.

EJB persistence provides support for this pattern by automatically detaching entities when they are serialized or when a persistence context ends (see Section 7.3, “Persistence Context” for an exploration of persistence contexts). The EJB persistence merge API re-attaches detached entities. This allows you to detach a persistent instance, modify the detached instance offline, and merge the instance back into an EntityManager (either the same one that detached the instance, or a new one). The changes will then be applied to the existing instance from the datastore.

A detached entity maintains its persistent identity, but cannot load additional state from the datastore. Accessing any persistent field or property that was not loaded at the time of detachment has undefined results.

	Note
	Be sure to not alter the version or identity fields of detached instances if you plan on merging them later.

The merge method returns a managed copy of the given detached entity. Changes made to the persistent state of the detached entity are applied to this managed instance. Because merging involves changing persistent state, you can only merge within a transaction.

If you attempt to merge an instance whose representation has changed in the datastore since detachment, the merge operation will throw an exception, or the transaction in which you perform the merge will fail on commit, just as if a normal optimistic conflict were detected.

	Note
	Kodo offers enhancements to EJB persistence detachment functionality, including additional options to control which fields are detached. See Section 11.1, “Detach and Attach” in the Reference Guide for details.

For a given entity A, the merge method behaves as follows:

public void lock (Object entity, LockModeType mode);

This method locks the given entity using the named mode. The javax.persistence.LockModeType enum defines two modes:

	Note
	Kodo has additional APIs for controlling object locking. See Section 9.4, “Object Locking” in the Reference Guide for details.

The following diagram illustrates the lifecycle of an entity with respect to the APIs presented in this section.

The examples below demonstrate how to use the lifecycle methods presented in the previous section. The examples are appropriate for out-of-container use. Within a container, EntityManagers are usually injected, and transactions are usually managed. You would therefore omit the createEntityManager and close calls, as well as all transaction demarcation code.

// Create some objects.
Magazine mag = new Magazine ("1B78-YU9L", "JavaWorld");

Company pub = new Company ("Weston House");
pub.setRevenue (1750000D);
mag.setPublisher (pub);
pub.addMagazine (mag);

Article art = new Article ("EJB Rules!", "Transparent Object Persistence");
art.addAuthor (new Author ("Fred", "Hoyle"));
mag.addArticle (art);

// Persist them.
EntityManager em = emf.createEntityManager ();
em.getTransaction ().begin ();
em.persist (mag);
em.persist (pub);
em.persist (art);
em.getTransaction ().commit ();

// Or we could continue using the EntityManager ...
em.close ();

Magazine.MagazineId mi = new Magazine.MagazineId ();
mi.isbn = "1B78-YU9L";
mi.title = "JavaWorld";

// Updates should always be made within transactions. Note that
// there is no code explicitly linking the magazine or company
// with the transaction; EJB automatically tracks all changes.
EntityManager em = emf.createEntityManager ();
em.getTransaction ().begin ();
Magazine mag = em.find (Magazine.class, mi);
mag.setPrice (5.99);
Company pub = mag.getPublisher ();
pub.setRevenue (1750000D);
em.getTransaction ().commit ();

// Or we could continue using the EntityManager ...
em.close ();

// Assume we have an object id for the company whose subscriptions
// we want to delete.
Object oid = ...;

// Deletes should always be made within transactions.
EntityManager em = emf.createEntityManager ();
em.getTransaction ().begin ();
Company pub = (Company) em.find (Company.class, oid);
for (Subscription sub : pub.getSubscriptions ())
    em.remove (sub);
pub.getSubscriptions ().clear ();
em.getTransaction ().commit ();

// Or we could continue using the EntityManager ...
em.close ();

// CLIENT:
// Requests an object with a given oid.
Record detached = (Record) getFromServer (oid);

...

// SERVER:
// Sends object to client; object detaches on EM close.
Object oid = processClientRequest ();
EntityManager em = emf.createEntityManager ();
Record record = em.find (Record.class, oid);
em.close ();
sendToClient (record);

...

// CLIENT:
// Makes some modifications and sends back to server.
detached.setSomeField ("bar");
sendToServer (detached);

...

// SERVER:
// Merges the instance and commits the changes.
Record modified = (Record) processClientRequest ();
EntityManager em = emf.createEntityManager ();
em.getTransaction ().begin ();
Record merged = (Record) em.merge (modified);
merged.setLastModified (System.currentTimeMillis ());
merged.setModifier (getClientIdentityCode ());
em.getTransaction ().commit ();
em.close ();

Each EntityManager is responsible for managing the persistent identities of the managed objects in the persistence context. The following methods allow you to interact with the management of persistent identities. The behavior of these methods is deeply affected by the persistence context type of the EntityManager; see Section 7.3, “Persistence Context” for an explanation of persistence contexts.

public <T> T find (Class<T> cls, Object oid);

This method returns the persistent instance of the given type with the given persistent identity. If the instance is already present in the current persistence context, the cached version will be returned. Otherwise, a new instance will be constructed and loaded with state from the datastore. If no entity with the given type and identity exists in the datastore, this method returns null.

public <T> T getReference (Class<T> cls, Object oid);

This method is similar to find, but does not necessarily go to the database when the entity is not found in cache. The implementation may construct a hollow entity and return it to you instead. Hollow entities do not have any state loaded. The state only gets loaded when you attempt to access a persistent field. At that time, the implementation may throw an EntityNotFoundException if it discovers that the entity does not exist in the datastore. The implementation may also throw an EntityNotFoundException from the getReference method itself. Unlike find, getReference does not return null.

public boolean contains (Object entity);

Returns true if the given entity is part of the current persistence context, and false otherwise. Removed entities are not considered part of the current persistence context.

public void flush ();

The flush method writes any changes that have been made in the current transaction to the datastore. If the EntityManager does not already have a connection to the datastore, it obtains one for the flush and retains it for the duration of the transaction. Any exceptions during flush cause the transaction to be marked for rollback. See Chapter 9, Transaction.

Flushing requires an active transaction. If there isn't a transaction in progress, the flush method throws a TransactionRequiredException.

public FlushModeType getFlushMode ();
public void setFlushMode (FlushModeType flushMode);

The EntityManager's FlushMode property controls whether to flush transactional changes before executing queries. This allows the query results to take into account changes you have made during the current transaction. Available javax.persistence.FlushModeType constants are:

You can also set the flush mode on individual Query instances.

	Note
	Kodo only flushes before a query if the query might be affected by data changed in the current transaction. Additionally, Kodo allows fine-grained control over flushing behavior. See the Reference Guide's Section 4.8, “Configuring the Use of JDBC Connections”.

public void clear ();

Clearing the EntityManager effectively ends the persistence context. All entities managed by the EntityManager become detached.

public Query createQuery (String query);

Query objects are used to find entities matching certain criteria. The createQuery method creates a query using the given EJB Query Language (JPQL) string. See Chapter 10, JPA Query for details.

public Query createNamedQuery (String name);

This method retrieves a query defined in metadata by name. The returned Query instance is initialized with the information declared in metadata. For more information on named queries, read Section 10.1.9, “Named Queries”.

public Query createNativeQuery (String sql);
public Query createNativeQuery (String sql, Class resultCls);
public Query createNativeQuery (String sql, String resultMapping);

Native queries are queries in the datastore's native language. For relational databases, this is the Structured Query Language (SQL). Chapter 11, SQL Queries elaborates on EJB persistence's native query support.

public boolean isOpen ();
public void close ();

When an EntityManager is no longer needed, you should call its close method. Closing an EntityManager releases any resources it is using. The persistence context ends, and the entities managed by the EntityManager become detached. Any Query instances the EntityManager created become invalid. Calling any method other than isOpen on a closed EntityManager results in an IllegalStateException. You cannot close an EntityManager that is in the middle of a transaction.

If you are in a managed environment using injected entity managers, you should not close them.

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

Pessimistic transactions generally lock the datastore records they act on, preventing other concurrent transactions from using the same data. This avoids conflicts between transactions, but consumes 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 datastore-dependent; usually one transaction is forcefully rolled back after some specified timeout interval, and an exception is thrown.

This document will often use the term datastore transaction in place of pessimistic transaction. This is to acknowledge that some datastores do not support pessimistic semantics, and that the exact meaning of a non-optimistic JPA transaction is dependent on the datastore. Most of the time, a datastore transaction is equivalent to a pessimistic transaction.

Optimistic transactions consume less resources than pessimistic/datastore transactions, but only at the expense of reliability. Because optimistic transactions do not lock datastore 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 flush or 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.

Despite their drawbacks, optimistic transactions are the best choice for most applications. They offer better performance, better scalability, and lower risk of hanging due to deadlock.

Note

Kodo uses optimistic semantics by default, but supports both optimistic and datastore transactions. Kodo also offers advanced locking and versioning APIs for fine-grained control over database resource allocation and object versioning. See Section 9.4, “Object Locking” and Section 5.8, “Lock Groups” of the Reference Guide for details on locking. Section 5.2.5, “Version” of this document covers standard object versioning.

JPA integrates with your container's managed transactions, allowing you to use the container's declarative transaction demarcation and its Java Transaction API (JTA) implementation for transaction management. Outside of a container, though, you must demarcate transactions manually through JPA. The EntityTransaction interface controls unmanaged transactions in JPA.

	Note
	Kodo offers additional transaction-related functionality in KodoEntityManager. See Section 8.2, “Integrating with the Transaction Manager” for how to configure Kodo to use managed transactions.

public void begin ();
public void commit ();
public void rollback ();

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 datastore, and rollback aborts the transaction, in which case the datastore is "rolled back" to its previous state. JPA implementations will automatically roll back transactions if any exception is thrown during the commit process.

Unless you are using an extended persistence context, committing or rolling back also ends the persistence context. All managed entites will be detached from the EntityManager.

public boolean isActive ();

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 (EntityManager em, User from, User to, double amnt)
{
    // Note: It would be better practice to move the transaction demarcation
    // code out of this method. The code below is for example purposes only.
    Transaction trans = em.getTransaction ();
    trans.begin ();
    try
    {
        from.decrementAccount (amnt);
        to.incrementAccount (amnt);
        trans.commit ();
    }
    catch (RuntimeException re)
    {
        if (trans.isActive ())
            trans.rollback ();   // Alternative: Fix error and retry.
        throw re;
    }
}