JDO : Annotations

Java provides the ability to use annotations, and JDO provides its own set. When selecting to use annotations please bear in mind the following :-

  • You must have the datanucleus-api-jdo jar available in your CLASSPATH.
  • You must have the jdo-api (or javax.jdo) jar in your CLASSPATH since this provides the annotations
  • Annotations should really only be used for attributes of persistence that you won't be changing at deployment. Things such as table and column names shouldn't really be specified using annotations although it is permitted. Instead it would be better to put such information in an ORM MetaData file.
  • 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. If you annotate fields then the fields are processed for persistence. If you annotate the methods (getters) then the methods (properties) are processed for persistence.
  • Annotations are prefixed by the @ symbol and can take properties (in brackets after the name, comma-separated)

Annotations supported by DataNucleus are shown below. The annotations/attributes coloured in brighter green are ORM and really should be placed in XML rather than directly in the class using annotations.

Annotation Class/Field/Method Description
@PersistenceCapable Class Specifies that the class/interface is persistent. In the case of an interface this would utilise JDO's "persistent-interface" capabilities
@PersistenceAware Class Specifies that the class is not persistent but needs to be able to access fields of persistent classes
@Cacheable Class Specifies whether this class can be cached in a Level 2 cache or not.
@EmbeddedOnly Class Specifies that the class is persistent and can only be persisted embedded in another persistent class
@DatastoreIdentity Class Specifies the details for generating datastore-identity for this class
@Version Class Specifies any versioning process for objects of this class
@FetchPlans Class Defines a series of fetch plans
@FetchPlan Class Defines a fetch plan
@FetchGroups Class Defines a series of fetch groups for this class
@FetchGroup Class Defines a fetch group for this class
@Sequence Class Defines a sequence for use by this class
@Queries Class Defines a series of named queries for this class
@Query Class Defines a named query for this class
@Inheritance Class Specifies the inheritance model for persisting this class
@Discriminator Class Specifies any discriminator for this class to be used for determining object types
@PrimaryKey Class ORM : Defines the primary key constraint for this class
@Indices Class ORM : Defines a series of indices for this class
@Index Class ORM : Defines an index for the class as a whole (typically a composite index)
@Uniques Class ORM : Defines a series of unique constraints for this class
@Unique Class ORM : Defines a unique constraint for the class as a whole (typically a composite)
@ForeignKeys Class ORM : Defines a series of foreign-keys (typically for non-mapped columns/tables)
@ForeignKey Class ORM : Defines a foreign-key for the class as a whole (typically for non-mapped columns/tables)
@Joins Class ORM : Defines a series of joins to secondary tables from this table
@Join Class ORM : Defines a join to a secondary table from this table
@Columns Class ORM : Defines a series of columns that dont have associated fields ("unmapped columns")
@Persistent Field/Method Defines the persistence for a field/property of the class
@Serialized Field/Method Defines this field as being stored serialised
@NotPersistent Field/Method Defines this field as being not persisted
@Transactional Field/Method Defines this field as being transactional (not persisted, but managed)
@Cacheable Field/Method Specifies whether this field/property can be cached in a Level 2 cache or not.
@PrimaryKey Field/Method Defines this field as being (part of) the primary key
@Element Field/Method Defines the details of elements of an array/collection stored in this field
@Key Field/Method Defines the details of keys of a map stored in this field
@Value Field/Method Defines the details of values of a map stored in this field
@Order Field/Method ORM : Defines the details of ordering of an array/collection stored in this field
@Join Field/Method ORM : Defines the join to a join table for a collection/array/map
@Embedded Field/Method ORM : Defines that this field is embedded and how it is embedded
@Columns Field/Method ORM : Defines a series of columns where a field is persisted
@Column Field/Method ORM : Defines a column where a field is persisted
@Index Field/Method ORM : Defines an index for the field
@Unique Field/Method ORM : Defines a unique constraint for the field
@ForeignKey Field/Method ORM : Defines a foreign key for the field
@Convert Field/Method Specify an AttributeConverter for this field/method
@Extensions Class/Field/Method Defines a series of JDO extensions
@Extension Class/Field/Method Defines a JDO extension

@PersistenceCapable

This annotation is used when you want to mark a class as persistent. It equates to the <class> XML element (though with only some of its attributes). Specified on the class.

Attribute Type Description Default
requiresExtent String Whether an extent is required for this class true
embeddedOnly String Whether objects of this class can only be stored embedded in other objects false
detachable String Whether objects of this class can be detached false
identityType IdentityType Type of identity (APPLICATION, DATASTORE, NONDURABLE) DATASTORE
objectIdClass Class Object-id class
table String ORM : Name of the table where this class is persisted
catalog String ORM : Name of the catalog where this table is persisted
schema String ORM : Name of the schema where this table is persisted
cacheable String Whether the class can be L2 cached. true | false
serializeRead String Whether to default reads of this object type to lock the object false
extensions Extension[] Vendor extensions 
@PersistenceCapable(identityType=IdentityType.APPLICATION)
public class MyClass
{
    ...
}


@PersistenceAware

This annotation is used when you want to mark a class as being used in persistence but not being persistable. That is "persistence-aware" in JDO terminology. It has no attributes. Specified on the class. 

@PersistenceAware
public class MyClass
{
    ...
}

See the documentation for Class Mapping



@Cacheable

This annotation is a shortcut for @PersistenceCapable(cacheable={value}) specifying whether the class can be cached in a Level 2 cache. Specified on the class. The default

Attribute Type Description Default
value String Whether the class is cacheable true | false 
@Cacheable("false")
public class MyClass
{
    ...
}

See the documentation for L2 Caching



@EmbeddedOnly

This annotation is a shortcut for @PersistenceCapable(embeddedOnly="true") meaning that the class can only be persisted embedded into another class. It has no attributes. Specified on the class. 

@EmbeddedOnly
public class MyClass
{
    ...
}


@Inheritance

Annotation used to define the inheritance for a class. Specified on the class.

Attribute Type Description Default
strategy InheritanceStrategy The inheritance strategy (NEW_TABLE, SUBCLASS_TABLE, SUPERCLASS_TABLE)
customStrategy String Name of a custom inheritance strategy (DataNucleus supports "complete-table") 
@PersistenceCapable
@Inheritance(strategy=InheritanceStrategy.NEW_TABLE)
public class MyClass
{
    ...
}

See the documentation for Inheritance



@Discriminator

Annotation used to define a discriminator to be stored with instances of this class and is used to determine the types of the objects being stored. Specified on the class.

Attribute Type Description Default
strategy DiscriminatorStrategy The discriminator strategy (VALUE_MAP, CLASS_NAME, NONE)
value String Value to use for instances of this type when using strategy of VALUE_MAP
column String ORM : Name of the column to use to store the discriminator
indexed String ORM : Whether the discriminator column is to be indexed
columns Column[] ORM : Column definitions used for storing the discriminator 
@PersistenceCapable
@Inheritance(strategy=InheritanceStrategy.NEW_TABLE)
@Discriminator(strategy=DiscriminatorStrategy.CLASS_NAME)
public class MyClass
{
    ...
}


@DatastoreIdentity

Annotation used to define the identity when using datastore-identity for the class. Specified on the class.

Attribute Type Description Default
strategy IdGeneratorStrategy The inheritance strategy (NATIVE, SEQUENCE, IDENTITY, INCREMENT, UUIDSTRING, UUIDHEX)
customStrategy String Name of a custom id generation strategy (e.g "max", "auid"). This overrides the value of "strategy"
sequence String Name of the sequence to use (when using SEQUENCE strategy) - refer to @Sequence
column String ORM : Name of the column for the datastore identity
columns Column[] ORM : Column definition for the column(s) for the datastore identity
extensions Extension[] Vendor extensions 
@PersistenceCapable
@DatastoreIdentity(strategy=IdGeneratorStrategy.INCREMENT)
public class MyClass
{
    ...
}

See the documentation for Datastore Identity



@Version

Annotation used to define the versioning details for use with optimistic transactions. Specified on the class.

Attribute Type Description Default
strategy VersionStrategy The version strategy (NONE, STATE_IMAGE, DATE_TIME, VERSION_NUMBER)
indexed String Whether the version column(s) is indexed
column String ORM : Name of the column for the version
columns Column[] ORM : Column definition for the column(s) for the version
extensions Extension[] Vendor extensions 
@PersistenceCapable
@Version(strategy=VersionStrategy.VERSION_NUMBER)
public class MyClass
{
    ...
}

See the documentation for Optimistic Transactions



@PrimaryKey

Annotation used to define the primary key constraint for a class. Maps across to the <primary-key> XML element. Specified on the class.

Attribute Type Description Default
name String ORM : Name of the primary key constraint
column String ORM : Name of the column for this key
columns Column[] ORM : Column definition for the column(s) of this key 
@PersistenceCapable
@PrimaryKey(name="MYCLASS_PK")
public class MyClass
{
    ...
}


@FetchPlans

Annotation used to define a set of fetch plans. Specified on the class. Used by named queries

Attribute Type Description Default
value FetchPlan[] Array of fetch plans - see @FetchPlan annotation 
@PersistenceCapable
@FetchPlans({@FetchPlan(name="plan_3", maxFetchDepth=3, fetchGroups={"group1", "group4"}),
             @FetchPlan(name="plan_4", maxFetchDepth=2, fetchGroups={"group1", "group2"})})
public class MyClass
{
    ...
}

See the documentation for FetchGroups



@FetchPlan

Annotation used to define a fetch plan Is equivalent to the <fetch-plan> XML element. Specified on the class. Used by named queries

Attribute Type Description Default
name String Name of the FetchPlan
maxFetchDepth int Maximum fetch depth 1
fetchSize int Size hint for fetching query result sets 0
fetchGroups String[] Names of the fetch groups included in this FetchPlan. 
@PersistenceCapable
@FetchPlan(name="plan_3", maxFetchDepth=3, fetchGroups={"group1", "group4"})
public class MyClass
{
    ...
}

See the documentation for FetchGroups



@FetchGroups

Annotation used to define a set of fetch groups for a class. Specified on the class.

Attribute Type Description Default
value FetchGroup[] Array of fetch groups - see @FetchGroup annotation 
@PersistenceCapable
@FetchGroups({@FetchGroup(name="one_two", members={@Persistent(name="field1"), @Persistent(name="field2")}),
              @FetchGroup(name="three", members={@Persistent(name="field3")})})
public class MyClass
{
    @Persistent
    String field1;

    @Persistent
    String field2;

    @Persistent
    String field3;
    ...
}

See the documentation for FetchGroups



@FetchGroup

Annotation used to define a fetch group. Is equivalent to the <fetch-group> XML element. Specified on the class.

Attribute Type Description Default
name String Name of the fetch group
postLoad String Whether to call jdoPostLoad after loading this fetch group
members Persistent[] Definitions of the fields/properties to include in this fetch group 
@PersistenceCapable
@FetchGroup(name="one_two", members={@Persistent(name="field1"), @Persistent(name="field2")})
public class MyClass
{
    @Persistent
    String field1;

    @Persistent
    String field2;
    ...
}

See the documentation for FetchGroups



@Sequence

Annotation used to define a sequence generator. Is equivalent to the <sequence> XML element. Specified on the class.

Attribute Type Description Default
name String Name of the sequence
strategy SequenceStrategy Strategy for the sequence (NONTRANSACTIONAL, CONTIGUOUS, NONCONTIGUOUS)
datastoreSequence String Name of a datastore sequence that this maps to
factoryClass Class Factory class to use to generate the sequence
initialValue int Initial value of the sequence 1
allocationSize int Allocation size of the sequence 50
extensions Extension[] Vendor extensions

See the documentation for Sequences



@Queries

Annotation used to define a set of named queries for a class. Specified on the class.

Attribute Type Description Default
value Query[] Array of queries - see @Query annotation 
@PersistenceCapable
@Queries({@Query(name="PeopleCalledSmith", language="JDOQL", 
                 value="SELECT FROM org.datanucleus.samples.Person WHERE surname == \"Smith\""),
          @Query(name="PeopleCalledJones", language="JDOQL", 
                 value="SELECT FROM org.datanucleus.samples.Person WHERE surname == \"Jones\"")})
public class Person
{
    @Persistent
    String surname;

    ...
}

See the documentation for Named Queries



@Query

Annotation used to define a named query. Is equivalent to the <query> XML element. Specified on the class.

Attribute Type Description Default
name String Name of the query
value String The query string itself
language String Language of the query (JDOQL, SQL, ...) JDOQL
unmodifiable String Whether the query is not modifiable at runtime
unique String Whether the query returns unique results (for SQL queries only)
resultClass Class Result class to use (for SQL queries only)
fetchPlan String Name of a named FetchPlan to use with this query
extensions Extension[] Vendor extensions 
@PersistenceCapable
@Query(name="PeopleCalledSmith", language="JDOQL", 
       value="SELECT FROM org.datanucleus.samples.Person WHERE surname == \"Smith\"")
public class Person
{
    @Persistent
    String surname;

    ...
}

See the documentation for Named Queries



@Indices

Annotation used to define a set of indices for a class. Specified on the class.

Attribute Type Description Default
value Index[] Array of indices - see @Index annotation 
@PersistenceCapable
@Indices({@Index(name="MYINDEX_1", members={"field1","field2"}), @Index(name="MYINDEX_2", members={"field3"})})
public class Person
{
    ...
}

See the documentation for Schema Constraints



@Index

Annotation used to define an index for the class as a whole typically being a composite index across multiple columns or fields/properties. Is equivalent to the <index> XML element when specified under class. Specified on the class.

Attribute Type Description Default
name String ORM : Name of the index
table String ORM : Name of the table for the index
unique String ORM : Whether the index is unique
members String[] ORM : Names of the fields/properties that make up this index
columns Column[] ORM : Columns that make up this index 
@PersistenceCapable
@Index(name="MY_COMPOSITE_IDX", members={"field1", "field2"})
public class MyClass
{
    @Persistent
    String field1;

    @Persistent
    String field2;

    ...
}

See the documentation for Schema Constraints



@Uniques

Annotation used to define a set of unique constraints for a class. Specified on the class.

Attribute Type Description Default
value Unique[] Array of constraints - see @Unique annotation 
@PersistenceCapable
@Uniques({@Unique(name="MYCONST_1", members={"field1","field2"}), @Unique(name="MYCONST_2", members={"field3"})})
public class Person
{
    ...
}

See the documentation for Schema Constraints



@Unique

Annotation used to define a unique constraints for the class as a whole typically being a composite constraint across multiple columns or fields/properties. Is equivalent to the <unique> XML element when specified under class. Specified on the class.

Attribute Type Description Default
name String ORM : Name of the constraint
table String ORM : Name of the table for the constraint
deferred String ORM : Whether the constraint is deferred
members String[] ORM : Names of the fields/properties that make up this constraint
columns Column[] ORM : Columns that make up this constraint 
@PersistenceCapable
@Unique(name="MY_COMPOSITE_IDX", members={"field1", "field2"})
public class MyClass
{
    @Persistent
    String field1;

    @Persistent
    String field2;

    ...
}

See the documentation for Schema Constraints



@ForeignKeys

Annotation used to define a set of foreign-key constraints for a class. Specified on the class.

Attribute Type Description Default
value ForeignKey[] Array of FK constraints - see @ForeignKey annotation

See the documentation for Schema Constraints



@ForeignKey

Annotation used to define a foreign-key constraint for the class. Specified on the class.

Attribute Type Description Default
name String ORM : Name of the constraint
table String ORM : Name of the table that the FK is to
deferred String ORM : Whether the constraint is deferred
unique String ORM : Whether the constraint is unique
deleteAction ForeignKeyAction ORM : Action to apply to the FK to be used on deleting ForeignKeyAction.RESTRICT
updateAction ForeignKeyAction ORM : Action to apply to the FK to be used on updating ForeignKeyAction.RESTRICT
members String[] ORM : Names of the fields/properties that compose this FK.
columns Column[] ORM : Columns that compose this FK.

See the documentation for Schema Constraints



@Joins

Annotation used to define a set of joins (to secondary tables) for a class. Specified on the class.

Attribute Type Description Default
value Join[] Array of joins - see @Join annotation 
@PersistenceCapable
@Joins({@Join(table="MY_OTHER_TABLE", column="MY_PK_COL"),
        @Join(table="MY_SECOND_TABLE", column="MY_PK_COL")})
public class MyClass
{
    @Persistent(table="MY_OTHER_TABLE")
    String myField;

    @Persistent(table="MY_SECOND_TABLE")
    String myField2;
    ...
}


@Join

Annotation used to specify a join for a secondary table. Specified on the class.

Attribute Type Description Default
table String ORM : Table name used when joining the PK of a FCO class table to a secondary table.
column String ORM : Name of the column used to join to the PK of the primary table (when only one column used)
outer String ORM : Whether to use an outer join when retrieving fields/properties stored in the secondary table
columns Column[] ORM : Name of the colums used to join to the PK of the primary table (when multiple columns used)
extensions Extension[] Vendor extensions 
@PersistenceCapable(name="MYTABLE")
@Join(table="MY_OTHER_TABLE", column="MY_PK_COL")
public class MyClass
{
    @Persistent(name="MY_OTHER_TABLE")
    String myField;
    ...
}


@Columns

Annotation used to define the columns which have no associated field in the class. User should specify a minimum of @Column "name", "jdbcType", and "insertValue". Specified on the class.

Attribute Type Description Default
value Column[] Array of columns - see @Column annotation 
@PersistenceCapable
@Columns(@Column(name="MY_OTHER_COL", jdbcType="VARCHAR", insertValue="N/A")
public class MyClass
{
    ...
}


@Persistent

Annotation used to define the fields/properties to be persisted. Is equivalent to the <field> and <property> XML elements. Specified on the field/method.

Attribute Type Description Default
persistenceModifier PersistenceModifier Whether the field is persistent (PERSISTENT, TRANSACTIONAL, NONE) [depends on field type]
defaultFetchGroup String Whether the field is part of the DFG
nullValue NullValue Required behaviour when inserting a null value for this field (NONE, EXCEPTION, DEFAULT). NONE
embedded String Whether this field as a whole is embedded. Use @Embedded to specify details.
embeddedElement String Whether the element stored in this collection/array field/property is embedded
embeddedKey String Whether the key stored in this map field/property is embedded
embeddedValue String Whether the value stored in this map field/property is embedded
serialized String Whether this field/property as a whole is serialised
serializedElement String Whether the element stored in this collection/array field/property is serialised
serializedKey String Whether the key stored in this map field/property is serialised
serializedValue String Whether the value stored in this map field/property is serialised
dependent String Whether this field is dependent, deleting the related object when deleting this object
dependentElement String Whether the element stored in this field/property is dependent
dependentKey String Whether the key stored in this field/property is dependent
dependentValue String Whether the value stored in this field/property is dependent
primaryKey String Whether this field is (part of) the primary key false
valueStrategy IdGeneratorStrategy Strategy to use when generating values for the field (NATIVE, SEQUENCE, IDENTITY, INCREMENT, UUIDSTRING, UUIDHEX)
customValueStrategy String Name of a custom id generation strategy (e.g "max", "auid"). This overrides the value of "valueStrategy"
sequence String Name of the sequence when using valueStrategy of SEQUENCE - refer to @Sequence
types Class[] Type(s) of field (when using interfaces/reference types). DataNucleus currently only supports the first value although in the future it is hoped to support multiple.
mappedBy String Field in other class when the relation is bidirectional to signify the owner of the relation
table String ORM : Name of the table where this field is persisted. If this field is a collection/map/array then the table refers to a join table, otherwise this refers to a secondary table.
name String Name of the field when defining an embedded field.
columns Column[] ORM : Column definition(s) for the columns into which this field is persisted. This is only typically used when specifying columns of a field of an embedded class.
cacheable String Whether the field/property can be L2 cached. true | false
extensions Extension[] Vendor extensions
recursionDepth int Recursion depth for this field when fetching. Only applicable when specified within @FetchGroup 1
loadFetchGroup String Name of a fetch group to activate when a load of this field is initiated (due to it being currently unloaded). Not used for getObjectById, queries, extents etc. Better to use @FetchGroup and define your groups
converter Class Converter class that implements javax.jdo.AttributeConverter
useDefaultConversion boolean Whether we should disable any default conversion for this field false 
@PersistenceCapable
public class MyClass
{
    @Persistent(primaryKey="true")
    String myField;
    ...
}

See the documentation for Fields/Properties



@Serialized

This annotation is a shortcut for @Persistent(serialized="true") meaning that the field is stored serialized. It has no attributes. Specified on the field/method. 

@PersistenceCapable
public class MyClass
{
    @Serialized
    Object myField;
    ...
}

See the documentation for Serialising



@NotPersistent

This annotation is a shortcut for @Persistent(persistenceModifier=PersistenceModifier.NONE) meaning that the field/property is not persisted. It has no attributes. Specified on the field/method. 

@PersistenceCapable
public class MyClass
{
    @NotPersistent
    String myOtherField;
    ...
}

See the documentation for Fields/Properties



@Transactional

This annotation is a shortcut for @Persistent(persistenceModifier=PersistenceModifier.TRANSACTIONAL) meaning that the field/property is not persisted yet managed. It has no attributes. Specified on the field/method. 

@PersistenceCapable
public class MyClass
{
    @Transactional
    String myOtherField;
    ...
}

See the documentation for Fields/Properties



@Cacheable

This annotation is a shortcut for @Persistent(cacheable={value}) specifying whether the field/property can be cached in a Level 2 cache. Specified on the field/property. The default

Attribute Type Description Default
value String Whether the field/property is cacheable true | false 
public class MyClass
{
    @Cacheable("false")
    Collection elements;
    ...
}

See the documentation for L2 Caching



@PrimaryKey

This annotation is a shortcut for @Persistent(primaryKey="true") meaning that the field/property is part of the primary key for the class. No attributes are needed when specified like this. Specified on the field/method. 

@PersistenceCapable
public class MyClass
{
    @PrimaryKey
    String myOtherField;
    ...
}

See the documentation for Schema Constraints



@Element

Annotation used to define the element for any collection/array to be persisted. Maps across to the <collection>, <array> and <element> XML elements. Specified on the field/method.

Attribute Type Description Default
types Class[] Type(s) of element. While the attribute allows multiple values DataNucleus currently only supports the first type value When using an array is not needed. When using a collection will be taken from the collection definition if using generics, otherwise must be specified.
embedded String Whether the element is embedded into a join table
serialized String Whether the element is serialised into the join table
dependent String Whether the element objects are dependent when deleting the owner collection/array
mappedBy String Field in the element class that represents this object (when the relation is bidirectional)
embeddedMapping Embedded[] Definition of any embedding of the (persistable) element. Only 1 "Embedded" should be provided
table String ORM : Name of the table for this element
column String ORM : Name of the column for this element
foreignKey String ORM : Name of any foreign-key constraint to add
generateForeignKey String ORM : Whether to generate a FK constraint for the element (when not specifying the name)
deleteAction ForeignKeyAction ORM : Action to be applied to the foreign key for this element for action upon deletion
updateAction ForeignKeyAction ORM : Action to be applied to the foreign key for this element for action upon update
index String ORM : Name of any index constraint to add
indexed String ORM : Whether this element column is indexed
unique String ORM : Whether this element column is unique
uniqueKey String ORM : Name of any unique key constraint to add
columns Column[] ORM : Column definition for the column(s) of this element
converter Class Converter class that implements javax.jdo.AttributeConverter
useDefaultConversion boolean Whether we should disable any default conversion for this element false
extensions Extension[] Vendor extensions 
@PersistenceCapable
public class MyClass
{
    @Element(types=org.datanucleus.samples.MyElementClass.class, dependent="true")
    Collection myField;
    ...
}


@Order

Annotation used to define the ordering of an order-based Collection/array to be persisted. Maps across to the <order> XML element. Specified on the field/method.

Attribute Type Description Default
mappedBy String ORM : Field in the element class that represents the ordering of the collection/array
column String ORM : Name of the column for this order
columns Column[] ORM : Column definition for the column(s) of this order
extensions Extension[] Vendor extensions 
@PersistenceCapable
public class MyClass
{
    @Element(types=org.datanucleus.samples.MyElementClass.class, dependent="true")
    @Order(column="ORDER_IDX")
    Collection myField;
    ...
}


@Key

Annotation used to define the key for any map to be persisted. Maps across to the <map> and <key> XML elements. Specified on the field/method.

Attribute Type Description Default
types Class[] Type(s) of key. While the attribute allows multiple values DataNucleus currently only supports the first type value When using generics will be taken from the Map definition, otherwise must be specified
embedded String Whether the key is embedded into a join table
serialized String Whether the key is serialised into the join table
dependent String Whether the key objects are dependent when deleting the owner map
mappedBy String Used to specify the field in the value class where the key is stored (optional).
embeddedMapping Embedded[] Definition of any embedding of the (persistable) key. Only 1 "Embedded" should be provided
table String ORM : Name of the table for this key
column String ORM : Name of the column for this key
foreignKey String ORM : Name of any foreign-key constraint to add
generateForeignKey String ORM : Whether to generate a FK constraint for the key (when not specifying the name)
deleteAction ForeignKeyAction ORM : Action to be applied to the foreign key for this key for action upon deletion
updateAction ForeignKeyAction ORM : Action to be applied to the foreign key for this key for action upon update
index String ORM : Name of any index constraint to add
indexed String ORM : Whether this key column is indexed
uniqueKey String ORM : Name of any unique key constraint to add
unique String ORM : Whether this key column is unique
columns Column[] ORM : Column definition for the column(s) of this key
converter Class Converter class that implements javax.jdo.AttributeConverter
useDefaultConversion boolean Whether we should disable any default conversion for this key false
extensions Extension[] Vendor extensions 
@PersistenceCapable
public class MyClass
{
    @Key(types=java.lang.String.class)
    Map myField;
    ...
}


@Value

Annotation used to define the value for any map to be persisted. Maps across to the <map> and <value> XML elements. Specified on the field/method.

Attribute Type Description Default
types Class[] Type(s) of value. While the attribute allows multiple values DataNucleus currently only supports the first type value When using generics will be taken from the Map definition, otherwise must be specified
embedded String Whether the value is embedded into a join table
serialized String Whether the value is serialised into the join table
dependent String Whether the value objects are dependent when deleting the owner map
mappedBy String Used to specify the field in the key class where the value is stored (optional).
embeddedMapping Embedded[] Definition of any embedding of the (persistable) value. Only 1 "Embedded" should be provided
table String ORM : Name of the table for this value
column String ORM : Name of the column for this value
foreignKey String ORM : Name of any foreign-key constraint to add
deleteAction ForeignKeyAction ORM : Action to be applied to the foreign key for this value for action upon deletion
generateForeignKey String ORM : Whether to generate a FK constraint for the value (when not specifying the name)
updateAction ForeignKeyAction ORM : Action to be applied to the foreign key for this value for action upon update
index String ORM : Name of any index constraint to add
indexed String ORM : Whether this value column is indexed
uniqueKey String ORM : Name of any unique key constraint to add
unique String ORM : Whether this value column is unique
columns Column[] ORM : Column definition for the column(s) of this value
converter Class Converter class that implements javax.jdo.AttributeConverter
useDefaultConversion boolean Whether we should disable any default conversion for this value false
extensions Extension[] Vendor extensions 
@PersistenceCapable
public class MyClass
{
    @Key(types=java.lang.String.class)
    @Value(types=org.datanucleus.samples.MyValueClass.class, dependent="true")
    Map myField;
    ...
}


@Join

Annotation used to specify a join to a join table for a collection/array/map. Specified on the field/method.

Attribute Type Description Default
table String ORM : Name of the table
column String ORM : Name of the column to join our PK to in the join table (when only one column used)
primaryKey String ORM : Name of any primary key constraint to add for the join table
generatePrimaryKey String ORM : Whether to generate a PK constraint on the join table (when not specifying the name)
foreignKey String ORM : Name of any foreign-key constraint to add
generateForeignKey String ORM : Whether to generate a FK constraint on the join table (when not specifying the name)
index String ORM : Name of any index constraint to add
indexed String ORM : Whether the join column(s) is indexed
uniqueKey String ORM : Name of any unique constraint to add
unique String ORM : Whether the join column(s) has a unique constraint
columns Column[] ORM : Name of the columns to join our PK to in the join table (when multiple columns used)
extensions Extension[] Vendor extensions 
@PersistenceCapable
public class MyClass
{
    @Persistent
    @Element(types=org.datanucleus.samples.MyElement.class)
    @Join(table="MYCLASS_ELEMENTS", column="MYCLASS_ELEMENTS_PK")
    Collection myField;
    ...
}


@Embedded

Annotation used to define that the field contents is embedded into the same table as this field Maps across to the <embedded> XML element. Specified on the field/method.

Attribute Type Description Default
ownerMember String ORM : The field/property in the embedded object that links back to the owning object (where it has a bidirectional relation)
nullIndicatorColumn String ORM : The column in the embedded object used to judge if the embedded object is null.
nullIndicatorValue String ORM : The value in the null column to interpret the object as being null.
members Persistent[] ORM : Field/property definitions for this embedding. 
@PersistenceCapable
public class MyClass
{
    @Embedded(members={
            @Persistent(name="field1", columns=@Column(name="OTHER_FLD_1")),
            @Persistent(name="field2", columns=@Column(name="OTHER_FLD_2"))
        })
    MyOtherClass myField;
    ...
}

@PersistenceCapable
@EmbeddedOnly
public class MyOtherClass
{
    @Persistent
    String field1;

    @Persistent
    String field2;
}


@Columns

Annotation used to define the columns into which a field is persisted. If the field is persisted into a single column then @Column should be used. Specified on the field/method.

Attribute Type Description Default
value Column[] Array of columns - see @Columns annotation 
@PersistenceCapable
public class MyClass
{
    @Persistent
    @Columns({@Column(name="RED"), @Column(name="GREEN"), @Column(name="BLUE"), @Column(name="ALPHA")})
    Color myField;
    ...
}


@Column

Annotation used to define that the colum where a field is persisted. Is equivalent to the <column> XML element when specified under field. Specified on the field/method (and within other annotations).

Attribute Type Description Default
name String ORM : Name of the column
target String ORM : Column in the other class that this maps to
targetMember String ORM : Field/Property in the other class that this maps to
jdbcType String ORM : JDBC Type to use for persisting into this column
sqlType String ORM : SQL Type to use for persisting into this column
length int ORM : Max length of data to store in this column
scale int ORM : Max number of floating points of data to store in this column
allowsNull String ORM : Whether null is allowed to be persisted into this column
defaultValue String ORM : Default value to persist into this column. If you want the default to be NULL, then put this as "#NULL"
insertValue String ORM : Value to insert into this column when it is an "unmapped" column. If you want the inserted value to be NULL, then put this as "#NULL"
position int Position of this column in the owning table (0 = first)
extensions Extension[] Vendor extensions 
@PersistenceCapable
public class MyClass
{
    @Persistent
    @Column(name="MYCOL", jdbcType="VARCHAR", length=40)
    String field1;

    ...
}


@Index

Annotation used to define that this field is indexed. Is equivalent to the <index> XML element when specified under field. Specified on the field/method.

Attribute Type Description Default
name String ORM : Name of the index
unique String ORM : Whether the index is unique 
@PersistenceCapable
public class MyClass
{
    @Persistent
    @Index(name="MYFIELD1_IDX")
    String field1;

    @Persistent
    @Index(name="MYFIELD2_IDX", unique="true")
    String field2;

    ...
}

See the documentation for Schema Constraints



@Unique

Annotation used to define that this field has a unique constraint. Is equivalent to the <unique> XML element when specified under field. Specified on the field/method.

Attribute Type Description Default
name String ORM : Name of the constraint
deferred String ORM : Whether the constraint is deferred 
@PersistenceCapable
public class MyClass
{
    @Persistent
    @Unique(name="MYFIELD1_IDX")
    String field1;

    ...
}

See the documentation for Schema Constraints



@ForeignKey

Annotation used to define the foreign key for a relationship field. Is equivalent to the <foreign-key> XML element when specified under field. Specified on the field/method.

Attribute Type Description Default
name String ORM : Name of the constraint
deferred String ORM : Whether the constraint is deferred
unique String ORM : Whether the constraint is unique
deleteAction ForeignKeyAction ORM : Action to apply to the FK to be used on deleting ForeignKeyAction.RESTRICT
updateAction ForeignKeyAction ORM : Action to apply to the FK to be used on updating ForeignKeyAction.RESTRICT 
@PersistenceCapable
public class MyClass
{
    @Persistent
    @ForeignKey(name="MYFIELD1_FK", deleteAction=ForeignKeyAction.RESTRICT)
    String field1;

    ...
}

See the documentation for Schema Constraints



@Convert

Annotation used to mark a field for conversion using an AttributeConverter Specified on the field/method.

Attribute Type Description Default
value Class Class for the AttributeConverter to use for this field
enabled boolean Setting this to false allows us to disable (default) conversion (for this type) that was defined at PMF level true 
@PersistenceCapable
public class MyClass
{
    @Persistent
    @Convert(MyURLConverter.class)
    URL url;

    ...
}


@Extensions

Annotation used to define a set of extensions specific to the JDO implementation being used. Specified on the class or field.

Attribute Type Description Default
value Extension[] Array of extensions - see @Extension annotation 
@PersistenceCapable
@Extensions({@Extension(vendorName="datanucleus", key="firstExtension", value="myValue"),
             @Extension(vendorName="datanucleus", key="secondExtension", value="myValue")})
public class Person
{
    ...
}


@Extension

Annotation used to define an extension specific to a particular JDO implementation. Is equivalent to the <extension> XML element. Specified on the class or field.

Attribute Type Description Default
vendorName String Name of the JDO vendor
key String Key for the extension
value String Value of the extension 
@PersistenceCapable
@Extension(vendorName="DataNucleus", key="RunFast", value="true")
public class Person
{
    ...
}