Whilst JPOX was always intended as a JDO implementation, it is intended also to implement the Java Persistence API (JPA) specification when time permits. This specification is a subset of the JDO2 specification but does provide for a few JDK 1.5 features that can be useful in some situations. One of these is the use of JDK 1.5 annotations. JPOX provides a level of support for JPA 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.
• You must have the jpa.jar available in your CLASSPATH (available from SUN)
• 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

• JPA doesn't provide for some key JDO concepts and JPOX provides its own annotations for these cases.
• You have to import "javax.persistence.XXX" where XXX is the annotation name of a JPA annotation
• You have to import "org.jpox.annotations.jpa.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 @Entity JPA annotation.

@Entity
public class Person
{
    ...
}
                
@Entity
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 @Basic annotation

@Entity
public class Person
{
    @Basic
    String firstName;

    @Basic
    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

@Entity
@Inheritance(strategy=InheritanceType.TABLE_PER_CLASS)
public class Person
{
    ...
}

@Entity
@Inheritance(strategy=InheritanceType.TABLE_PER_CLASS)
public class Manager extends Person
{
    ...
}

It is worth mentioning that Eclipse users can benefit from the "Dali" plugin that allows generation of JPA annotations. Please refer to the JPOX Eclipse-Dali tutorial.

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 JPA annotations supported by JPOX, as well as the custom annotations added by JPOX to fill holes that JPA doesnt provide for (where JDO is a more complete specification than JPA).

Annotation	JPA/JPOX	Class/Field	Description
Entity	JPA	Class	Marks the class as "PersistenceCapable".
PersistenceAware	JPOX	Class	Marks the class as "PersistenceAware".
Inheritance	JPA	Class	Identifies the inheritance strategy etc for the class.
DiscriminatorColumn	JPA	Class	Specifies the details of any discriminator column
DiscriminatorValue	JPA	Class	Specifies the value to be used in any discriminator
Table	JPA	Class	Specifies the table to be used when persisting this class
Embeddable	JPA	Class	Marks the class as being embedded-only
Detachable	JPOX	Class	Marks the class as being detachable
RequiresExtent	JPOX	Class	Marks the class as requiring an extent or not (use "value" as "false" to set it false)
IdentityType	JPOX	Class	Sets the identity type of the class (datastore, application etc).
IdClass	JPA	Class	Defines the object identity class (PK class) when using composite primary-key for this class
Id	JPA	Field	Defines the field as being part of the PK
Basic	JPA	Field	Defines the persistence of basic fields (primitives, wrappers, String etc)
OneToOne	JPA	Field	Defines the field as being part of a 1-1 relation
OneToMany	JPA	Field	Defines the field as being part of a 1-N relation
ManyToOne	JPA	Field	Defines the field as being part of a N-1 relation
ManyToMany	JPA	Field	Defines the field as being part of a M-N relation
JoinTable	JPA	Field	Defines that the field uses a join-table (for 1-N, M-N relations), and the contents of the join table
Lob	JPA	Field	Defines that the field should use BLOB/CLOB jdbc-type
Temporal	JPA	Field	Defines that the field (Date, Time, Timestamp, Calendar) should use DATE/TIME/TIMESTAMP jdbc-type
Enumerated	JPA	Field	Defines that the field (Enum) should use INTEGER/VARCHAR jdbc-type
Column	JPA	Field	Defines the column details for the field