One of the things that JDK 1.5 provides that can be of some use to JPOX is annotations. JPOX provides a level of support for JDO annotations from JPOX version 1.1.2 onwards and this support is currently considered experimental work-in-progress so please report any issues found.

Things to bear in mind when considering using this facility

• You must be using JDK 1.5 or above. Annotations are not available in earlier JDKs
• You must have the JPOX Java5 plugin available in your CLASSPATH.
• Annotations should really only be used for attributes of persistence that you wont be changing at deployment. Things such as table and column names shouldn't really be specified using annotations although it is permitted.

The principal idea behind annotations in JPOX is that you can store the basic persistence information that you embody in a JDO MetaData file instead in the Java file alongside the fields of the class. We do not recommend storing the information storable in an ORM MetaData file as annotations since this is the type of information that you would typically change at deployment time to match the RDBMS in use etc. Some general rules for annotations are

• These annotations are designed to be JDO2 and it is likely that they will be adopted in some form into the Apache JDO project in a future release of JDO
• You have to import "org.jpox.annotations.XXX" where XXX is the annotation name of a JPOX annotation
• Annotations can be added in two places - for the class as a whole, or for a field in particular.
• You can annotate fields or getters with field-level information. It doesn't matter which.
• Annotations are prefixed by the @ symbol and can take properties (in brackets after the name, comma-separated)

Annotating classes

Let's start with some sample classes, and add some annotations.

public class Person
{
    String firstName;
    String lastName;

    public String getFirstName()
    {
        return firstName;
    }

    public String getLastName()
    {
        return lastName;
    }
}

public class Manager extends Person
{
    HashSet employees;
    Department department;

    public Department getDepartment()
    {
         return department;
    }
}

So we firstly want to mark Person and Manager as persistent. We do this using the @PersistenceCapable annotation.

@PersistenceCapable
public class Person
{
    ...
}

@PersistenceCapable
public class Manager extends Person
{
    ...
}

Now that we know our classes are going to be persisted ("PersistenceCapable") we need to configure how the fields will be persisted. By default our simple fields like "firstName", "lastName" will be persisted, but we can reenforce this using the @Field annotation

@PersistenceCapable
public class Person
{
    @Field
    String firstName;

    @Field
    String lastName;

    ...
}

We should point out that we could have added the annotations to the "getter" method instead of the field itself. Both places serve the same purpose. Next we want to configure that our Person and Manager classes each have their own table. We use the @Inheritance annotation

@PersistenceCapable
@Inheritance(strategy=InheritanceStrategyType.NEW_TABLE)
public class Person
{
    ...
}

@PersistenceCapable
@Inheritance(strategy=InheritanceStrategyType.NEW_TABLE)
public class Manager extends Person
{
    ...
}

Enhancing

Enhancing the annotated classes operates in a very similar way as enhancing a normal class with MetaData except that you supply the class files and not MetaData files to JPOX Enhancer.

SchemaTool

Generating the schema for annotated classes operates in a very similar way as generating the schema for a normal class with MetaData except that you supply the class files and not MetaData files to JPOX SchemaTool.

Supported Annotations

This section lists the JDO annotations supported by JPOX. Until we have time to provide full docs on these annotations please refer to the

Annotation	JDO/JPOX	Class/Field	Description
PersistenceCapable	JPOX	Class	Marks the class as "PersistenceCapable" and allows specification general persistence options (equivalent to the <class> element in MetaData).
PersistenceAware	JPOX	Class	Marks the class as "PersistenceAware".
Inheritance	JPOX	Class	Identifies the inheritance strategy etc for the class. (equivalent to the <inheritance> element in MetaData)
Discriminator	JPOX	Class	Specifies the details of any discriminator (equivalent to the <discriminator> element in MetaData)
DatastoreIdentity	JPOX	Class	Specifies the datastore identity details (strategy, column etc) (equivalent to the <datastore-identity> element in MetaData)
Version	JPOX	Class	Specifies the use of a version column for optimistic handling (equivalent to the <version> element in MetaData).
Queries/Query	JPOX	Class	Specifies the use of named queries for a class (equivalent to the <query> element in MetaData).
FetchGroups/FetchGroup	JPOX	Class	Specifies the use of fetch groups for a class (equivalent to the <fetch-group> element in MetaData). Note that nested fetch-groups are not supported with annotations
PrimaryKey	JPOX	Class	Specifies the details of any primary key for the table of this class (equivalent to the <primary-key> element in MetaData).
Implements	JPOX	Class	Specifies the details of any interfaces implemented by this persistence class (equivalent to the <implements> element in MetaData).
Sequence	JPOX	Class	Specifies a datastore sequence for use. (equivalent to the <sequence> element in MetaData).
Field	JPOX	Field	Defines the field for persistence. (equivalent to the <field> element in MetaData).
Collection	JPOX	Field	Provides the definition for collection fields. (equivalent to the <collection> element in MetaData).
Map	JPOX	Field	Provides the definition for map fields. (equivalent to the <map> element in MetaData).
Array	JPOX	Field	Provides the definition for array fields. (equivalent to the <array> element in MetaData).
Element	JPOX	Field	Provides the definition for collection/array elements. (equivalent to the <element> element in MetaData).
Key	JPOX	Field	Provides the definition for map keys (equivalent to the <key> element in MetaData).
Value	JPOX	Field	Provides the definition for map values (equivalent to the <value> element in MetaData).
Order	JPOX	Field	Provides the definition for ordering (equivalent to the <order> element in MetaData).
Join	JPOX	Field	Provides the definition for container fields using a join table (equivalent to the <join> element in MetaData).
Column	JPOX	Field	Provides the column details for the field (equivalent to the <column> element in MetaData).
Embedded	JPOX	Field	Defines whether the field is embedded. (equivalent to the <embedded> element in MetaData).