Java provides the ability to use annotations, and DataNucleus supports both JPA and JDO annotations. In this section we will document some of the more important JPA annotations. When selecting to use annotations please bear in mind the following :-
Annotations supported by DataNucleus are shown below. Not all have their documentation written yet. The annotations/attributes coloured in brighter green are ORM and really should be placed in XML rather than directly in the class using annotations. The annotations coloured in blue are DataNucleus extensions and should be used only where you don't mind losing implementation-independence.
Annotation | Class/Field | Description |
---|---|---|
@Entity | Class | Specifies that the class is persistent |
@MappedSuperclass | Class | Specifies that this class contains persistent information to be mapped |
@Embeddable | Class | Specifies that the class is persistent embedded in another persistent class |
@PersistenceAware | Class | Specifies that the class is not persistent but needs to be able to access fields of persistent classes (DataNucleus extension). |
@IdClass | Class | Defines the primary key class for this class |
@Cacheable | Class | Specifies that instances of this class can be cached in the L2 cache |
@DatastoreId | Class | Defines a class as using datastore-identity (DataNucleus extension). |
@EntityListeners | Class | Specifies class(es) that are listeners for events from instances of this class |
@NamedQueries | Class | Defines a series of named JPQL queries for use in the current persistence unit |
@NamedQuery | Class | Defines a named JPQL query for use in the current persistence unit |
@NamedNativeQuery | Class | Defines a named SQL query for use in the current persistence unit |
@NamedNativeQueries | Class | Defines a series of named SQL queries for use in the current persistence unit |
@NamedStoredProcedureQuery | Class | Defines a named stored procedure query for use in the current persistence unit |
@NamedStoredProcedureQueries | Class | Defines a series of named stored procedure queries for use in the current persistence unit |
@SqlResultSetMapping | Class | Defines a result mapping for an SQL query for use in the current persistence unit |
@SqlResultSetMappings | Class | Defines a series of mappings for SQL queries for use in the current persistence unit |
@NamedEntityGraph | Class | Defines a named entity graph with root of the class it is specifed on |
@NamedEntityGraphs | Class | Defines named entity graphs with root of the class it is specifed on |
@Converter | Class | Defines a java type converter for a field type |
@Inheritance | Class | Specifies the inheritance model for persisting this class |
@Table | Class | Defines the table where this class will be stored |
@SecondaryTable | Class | Defines a secondary table where some fields of this class will be stored |
@DiscriminatorColumn | Class | Defines the column where any discriminator will be stored |
@DiscriminatorValue | Class | Defines the value to be used in the discriminator for objects of this class |
@PrimaryKeyJoinColumns | Class | Defines the names of the PK columns when this class has a superclass |
@PrimaryKeyJoinColumn | Class | Defines the name of the PK column when this class has a superclass |
@AttributeOverride | Class | Defines a field in a superclass that will have its column overridden |
@AttributeOverrides | Class | Defines the field(s) of superclasses that will have their columns overridden |
@AssociationOverride | Class | Defines a N-1/1-1 field in a superclass that will have its column overridden |
@AssociationOverrides | Class | Defines the N-1/1-1 field(s) of superclasses that will have their columns overridden |
@SequenceGenerator | Class/Field/Method | Defines a generator of values using sequences in the datastore for use with persistent entities |
@TableGenerator | Class/Field/Method | Defines a generator of sequences using a table in the datastore for use with persistent entities |
@Embedded | Field/Method | Defines this field as being embedded |
@Id | Field/Method | Defines this field as being (part of) the identity for the class |
@EmbeddedId | Field/Method | Defines this field as being (part of) the identity for the class, and being embedded into this class. |
@Version | Field/Method | Defines this field as storing the version for the class |
@Basic | Field/Method | Defines this field as being persistent |
@Transient | Field/Method | Defines this field as being transient (not persisted) |
@OneToOne | Field/Method | Defines this field as being a 1-1 relation with another persistent entity |
@OneToMany | Field/Method | Defines this field as being a 1-N relation with other persistent entities |
@ManyToMany | Field/Method | Defines this field as being a M-N relation with other persistent entities |
@ManyToOne | Field/Method | Defines this field as being a N-1 relation with another persistent entity |
@ElementCollection | Field/Method | Defines this field as being a 1-N relation of Objects that are not Entities. |
@Index | Field/Method | Specifies an index on this field/property (DataNucleus extension). |
@JdbcType | Field/Method | Specifies the JDBC Type to use on this field/property (DataNucleus extension). |
@ColumnPosition | Field/Method | Specifies the column position to use on this field/property (DataNucleus extension). |
@ValueGenerator | Field/Method | Specifies a non-JPA-standard value generator to use on this field/property (DataNucleus extension). |
@GeneratedValue | Field/Method | Defines that this field has its value generated using a generator |
@MapKey | Field/Method | Defines that this field is the key to a map |
@MapKeyEnumerated | Field/Method | Defines the datastore type for the map key when it is an enum |
@MapKeyTemporal | Field/Method | Defines the datastore type for the map key when it is a temporal type |
@MapKeyColumn | Field/Method | Defines the column details for the map key when stored in a join table |
@OrderBy | Field/Method | Defines the field(s) used for ordering the elements in this collection |
@OrderColumn | Field/Method | Defines that ordering should be attributed by the implementation using a surrogate column. |
@PrePersist | Field/Method | Defines this method as being a callback for pre-persist events |
@PostPersist | Field/Method | Defines this method as being a callback for post-persist events |
@PreRemove | Field/Method | Defines this method as being a callback for pre-remove events |
@PostRemove | Field/Method | Defines this method as being a callback for post-remove events |
@PreUpdate | Field/Method | Defines this method as being a callback for pre-update events |
@PostUpdate | Field/Method | Defines this method as being a callback for post-update events |
@PostLoad | Field/Method | Defines this method as being a callback for post-load events |
@JoinTable | Field/Method | Defines this field as being stored using a join table |
@CollectionTable | Field/Method | Defines this field as being stored using a join table when containing non-entity objects. |
@Lob | Field/Method | Defines this field as being stored as a large object |
@Temporal | Field/Method | Defines this field as storing temporal data |
@Enumerated | Field/Method | Defines this field as storing enumerated data |
@Convert | Field/Method | Defines a converter for this field/property |
@Column | Field/Method | Defines the column where this field is stored |
@JoinColumn | Field/Method | Defines a column for joining to either a join table or foreign key relation |
@JoinColumns | Field/Method | Defines the columns for joining to either a join table or foreign key relation (1-1, 1-N, N-1) |
@Index | - | Defines the details of an index when overriding the provider default. |
@ForeignKey | - | Defines the details of a foreign key when overriding the provider default. |
@Extensions | Class/Field/Method | Defines a series of DataNucleus extensions (DataNucleus extension). |
@Extension | Class/Field/Method | Defines a DataNucleus extension (DataNucleus extension). |
This annotation is used when you want to mark a class as persistent. Specified on the class.
Attribute | Type | Description | Default |
---|---|---|---|
name | String | Name of the entity (used in JPQL to refer to the class) |
@Entity public class MyClass { ... }
See the documentation for Class Mapping
This annotation is used when you want to mark a class as persistent but without a table of its own and being the superclass of the class that has a table, meaning that all of its fields are persisted into the table of its subclass. Specified on the class.
@MappedSuperclass public class MyClass { ... }
See the documentation for Inheritance
This annotation is used when you want to mark a class as knowing about persistence but not persistent itself. That is, it manipulates the fields of a persistent class directly rather than using accessors. This is a DataNucleus extension. Specified on the class.
@PersistenceAware public class MyClass { ... }
See the documentation for Class Mapping
This annotation is used when you want to mark a class as persistent and only storable embedded in another object. Specified on the class.
@Embeddable public class MyClass { ... }
This annotation is used when you want to mark a class so that instance of that class can be cached. Specified on the class.
@Cacheable public class MyClass { ... }
See the documentation for L2 Cache
This annotation is used to define the inheritance persistence for this class. Specified on the class.
Attribute | Type | Description | Default |
---|---|---|---|
strategy | InheritanceType | Inheritance strategy | SINGLE_TABLE | JOINED | TABLE_PER_CLASS |
@Entity @Inheritance(strategy=InheritanceType.JOINED) public class MyClass { ... }
See the documentation for Inheritance
This annotation is used to define the table where objects of a class will be stored. Specified on the class.
Attribute | Type | Description | Default |
---|---|---|---|
name | String | Name of the table | |
catalog | String | Name of the catalog | |
schema | String | Name of the schema | |
uniqueConstraints | UniqueConstraint[] | Any unique constraints to apply to the table | |
indexes | Index[] | Details of indexes if wanting to override provider default |
@Entity @Table(name="MYTABLE", schema="PUBLIC") public class MyClass { ... }
This annotation is used to define a secondary table where some fields of this class are stored in another table. Specified on the class.
Attribute | Type | Description | Default |
---|---|---|---|
name | String | Name of the table | |
catalog | String | Name of the catalog | |
schema | String | Name of the schema | |
pkJoinColumns | PrimaryKeyJoinColumns[] | Join columns for the PK of the secondary table back to the primary table | |
uniqueConstraints | UniqueConstraint[] | Any unique constraints to apply to the table | |
indexes | Index[] | Details of indexes if wanting to override provider default | |
foreignKey | ForeignKey | Foreign key details if wanting to override provider default |
@Entity @Table(name="MYTABLE", schema="PUBLIC") @SecondaryTable(name="MYOTHERTABLE", schema="PUBLIC", columns={@PrimaryKeyJoinColumn(name="MYCLASS_ID")}) public class MyClass { ... }
See the documentation for Secondary Tables
This annotation is used to define a primary-key class for the identity of this class. Specified on the class.
Attribute | Type | Description | Default |
---|---|---|---|
value | Class | Identity class |
@Entity @IdClass(org.datanucleus.samples.MyIdentity.class) public class MyClass { ... }
See the documentation for Primary Keys
This DataNucleus-extension annotation is used to define that the class uses datastore-identity. Specified on the class.
Attribute | Type | Description | Default |
---|---|---|---|
generationType | GenerationType | Strategy to use when generating the values for this field. Has possible values of GenerationType TABLE, SEQUENCE, IDENTITY, AUTO. | AUTO | TABLE | SEQUENCE |
generator | String | Name of the generator to use. See @TableGenerator and @SequenceGenerator | |
column | String | Name of the column for persisting the datastore identity value |
@Entity @DatastoreId(column="MY_ID") public class MyClass { ... }
This annotation is used to define a class or classes that are listeners for events from instances of this class. Specified on the class.
Attribute | Type | Description | Default |
---|---|---|---|
value | Class[] | Entity listener class(es) |
@Entity @EntityListeners(org.datanucleus.MyListener.class) public class MyClass { ... }
See the documentation for Lifecycle Callbacks
This annotation is used to define a series of named (JPQL) queries that can be used in this persistence unit. Specified on the class.
Attribute | Type | Description | Default |
---|---|---|---|
value | NamedQuery[] | The named queries |
@Entity @NamedQueries({ @NamedQuery(name="AllPeople", query="SELECT p FROM Person p"), @NamedQuery(name="PeopleCalledJones", query="SELECT p FROM Person p WHERE p.surname = 'Jones'")}) public class Person { ... }
See the documentation for Named Queries
This annotation is used to define a named (JPQL) query that can be used in this persistence unit. Specified on the class.
Attribute | Type | Description | Default |
---|---|---|---|
name | String | Symbolic name for the query. The query will be referred to under this name | |
query | String | The JPQL query |
@Entity @NamedQuery(name="AllPeople", query="SELECT p FROM Person p") public class Person { ... }
See the documentation for Named Queries
This annotation is used to define a series of named native (SQL) queries that can be used in this persistence unit. Specified on the class.
Attribute | Type | Description | Default |
---|---|---|---|
value | NamedNativeQuery[] | The named native queries |
@Entity @NamedNativeQueries({ @NamedNativeQuery(name="AllPeople", query="SELECT * FROM PERSON WHERE SURNAME = 'Smith'"), @NamedNativeQuery(name="PeopleCalledJones", query="SELECT * FROM PERSON WHERE SURNAME = 'Jones')}) public class Person { ... }
See the documentation for Named Native Queries
This annotation is used to define a named (SQL) query that can be used in this persistence unit. Specified on the class.
Attribute | Type | Description | Default |
---|---|---|---|
name | String | Symbolic name for the query. The query will be referred to under this name | |
query | String | The SQL query | |
resultClass | Class | Class into which the result rows will be placed | void.class |
@Entity @NamedNativeQuery(name="PeopleCalledSmith", query="SELECT * FROM PERSON WHERE SURNAME = 'Smith'") public class Person { ... }
See the documentation for Named Native Queries
This annotation is used to define a series of named native stored procedure queries that can be used in this persistence unit. Specified on the class.
Attribute | Type | Description | Default |
---|---|---|---|
value | NamedStoredProcedureQuery[] | The named stored procedure queries |
@Entity @NamedStoredProcedureQueries({ @NamedStoredProcedureQuery(name="MyProc", procedureName="MY_PROC_SP1", parameters={@StoredProcedureParameter(name="PARAM1", mode=ParameterMode.IN, type=String.class)}), @NamedStoredProcedureQuery(name="MyProc2", procedureName="MY_PROC_SP2", parameters={@StoredProcedureParameter(name="PARAM1", mode=ParameterMode.IN, type=Long.class)})}) public class Person { ... }
See the documentation for Named Stored procedures
This annotation is used to define a named stored procedure query that can be used in this persistence unit. Specified on the class.
Attribute | Type | Description | Default |
---|---|---|---|
name | String | Symbolic name for the query. The query will be referred to under this name | |
procedureName | String | Name of the stored procedure in the datastore | |
parameters | StoredProcedureParameter[] | Any parameter definitions for this stored procedure | |
resultClasses | Class[] | Any result class(es) for this stored procedure (one per result set) | |
resultSetMappings | Class[] | Any result set mapping(s) for this stored procedure (one per result set) | |
hints | QueryHint[] | Any query hints for this stored procedure |
@Entity @NamedStoredProcedureQuery(name="MyProc", procedureName="MY_PROC_SP1", parameters={@StoredProcedureParameter(name="PARAM1", mode=ParameterMode.IN, type=String.class)}) public class Person { ... }
See the documentation for Named StoredProcedures
This annotation is used to define a series of result mappings for SQL queries that can be used in this persistence unit. Specified on the class.
Attribute | Type | Description | Default |
---|---|---|---|
value | SqlResultSetMapping[] | The SQL result mappings |
@Entity @SqlResultSetMappings({ @SqlResultSetMapping(name="PEOPLE_PLUS_AGE", entities={@EntityResult(entityClass=Person.class)}, columns={@ColumnResult(name="AGE")}), @SqlResultSetMapping(name="FIRST_LAST_NAMES", columns={@ColumnResult(name="FIRSTNAME"), @ColumnResult(name="LASTNAME")}) }) public class Person { ... }
This annotation is used to define a mapping for the results of an SQL query and can be used in this persistence unit. Specified on the class.
Attribute | Type | Description | Default |
---|---|---|---|
name | String | Symbolic name for the mapping. The mapping will be referenced under this name | |
entities | EntityResult[] | Set of entities extracted from the SQL query | |
columns | ColumnResult[] | Set of columns extracted directly from the SQL query |
@Entity @SqlResultSetMapping(name="PEOPLE_PLUS_AGE", entities={@EntityResult(entityClass=Person.class)}, columns={@ColumnResult(name="AGE")}) public class Person { ... }
This annotation is used to define a series of named EntityGraphs that can be used in this persistence unit. Specified on the class.
Attribute | Type | Description | Default |
---|---|---|---|
value | NamedEntityGraph[] | The named EntityGraphs |
@Entity @NamedEntityGraph({ @NamedEntityGraph(name="PERSON_FULL", attributeNodes={@NamedAttributeNode(name="friends"), @NamedAttributeNode(name="parents")}), @NamedEntityGraph(name="PERSON_BASIC", attributeNodes={@NamedAttributeNode(name="parents")}) }) public class Person { ... }
This annotation is used to define a named EntityGraph and can be used in this persistence unit. Specified on the class.
Attribute | Type | Description | Default |
---|---|---|---|
name | String | name for the Entity Graph. | |
attributeNodes | AttributeNode[] | Set of nodes in this EntityGraph |
@Entity @NamedEntityGraph(name="PERSON_FULL", attributeNodes={@NamedAttributeNode(name="friends"), @NamedAttributeNode(name="parents")}) public class Person { ... }
This annotation is used to define a method that is a callback for pre-persist events. Specified on the method. It has no attributes.
@Entity public class MyClass { ... @PrePersist void registerObject() { ... } }
See the documentation for Lifecycle Callbacks
This annotation is used to define a method that is a callback for post-persist events. Specified on the method. It has no attributes.
@Entity public class MyClass { ... @PostPersist void doSomething() { ... } }
See the documentation for Lifecycle Callbacks
This annotation is used to define a method that is a callback for pre-remove events. Specified on the method. It has no attributes.
@Entity public class MyClass { ... @PreRemove void registerObject() { ... } }
See the documentation for Lifecycle Callbacks
This annotation is used to define a method that is a callback for post-remove events. Specified on the method. It has no attributes.
@Entity public class MyClass { ... @PostRemove void doSomething() { ... } }
See the documentation for Lifecycle Callbacks
This annotation is used to define a method that is a callback for pre-update events. Specified on the method. It has no attributes.
@Entity public class MyClass { ... @PreUpdate void registerObject() { ... } }
See the documentation for Lifecycle Callbacks
This annotation is used to define a method that is a callback for post-update events. Specified on the method. It has no attributes.
@Entity public class MyClass { ... @PostUpdate void doSomething() { ... } }
See the documentation for Lifecycle Callbacks
This annotation is used to define a method that is a callback for post-load events. Specified on the method. It has no attributes.
@Entity public class MyClass { ... @PostLoad void registerObject() { ... } }
See the documentation for Lifecycle Callbacks
This annotation is used to define a generator using sequences in the datastore. It is scoped to the persistence unit. Specified on the class/field/method.
Attribute | Type | Description | Default |
---|---|---|---|
name | String | Name for the generator (required) | |
sequenceName | String | Name of the underlying sequence that will be used | |
initialValue | int | Initial value for the sequence (optional) | 1 |
allocationSize | int | Number of values to be allocated each time (optional) | 50 |
@Entity @SequenceGenerator(name="MySeq", sequenceName="SEQ_2") public class MyClass { ... }
This annotation is used to define a generator using a table in the datastore for storing the values. It is scoped to the persistence unit. Specified on the class/field/method.
Attribute | Type | Description | Default |
---|---|---|---|
name | String | Name for the generator (required) | |
table | String | Name of the table to use | SEQUENCE_TABLE |
catalog | String | Catalog of the table to use | |
schema | String | Schema of the table to use | |
pkColumnName | String | Name of the primary key column for the table | SEQUENCE_NAME |
valueColumnName | String | Name of the value column for the table | NEXT_VAL |
pkColumnValue | String | Value to store in the PK column for the row used by this generator | {name of the class} |
initialValue | int | Initial value for the table row (optional) | 0 |
allocationSize | int | Number of values to be allocated each time (optional) | 50 |
indexes | Index[] | Index(es) if wanting to override the provider default |
@Entity @TableGenerator(name="MySeq", table="MYAPP_IDENTITIES", pkColumnValue="MyClass") public class MyClass { ... }
This annotation is used to define the discriminator column for a class. Specified on the class.
Attribute | Type | Description | Default |
---|---|---|---|
name | String | Name of the discriminator column | DTYPE |
discriminatorType | DiscriminatorType | Type of the discriminator column | STRING | CHAR | INTEGER |
length | String | Length of the discriminator column | 31 |
@Entity @Inheritance(strategy=InheritanceType.SINGLE_TABLE) @DiscriminatorColumn(name="OBJECT_TYPE", discriminatorType=DiscriminatorType.STRING) public class MyClass { ... }
See the documentation for Inheritance
This annotation is used to define the value to be stored in the discriminator column for a class (when used). Specified on the class.
Attribute | Type | Description | Default |
---|---|---|---|
value | String | Value for the discriminator column |
@Entity @Inheritance(strategy=InheritanceType.SINGLE_TABLE) @DiscriminatorColumn(name="OBJECT_TYPE", discriminatorType=DiscriminatorType.STRING) @DiscriminatorValue("MyClass") public class MyClass { ... }
See the documentation for Inheritance
This annotation is used to define the names of the primary key columns when this class has a superclass. Specified on the class.
Attribute | Type | Description | Default |
---|---|---|---|
value | PrimaryKeyJoinColumn[] | Array of column definitions for the primary key | |
foreignKey | ForeignKey | Foreign key details if wanting to override provider default |
@Entity @Inheritance(strategy=InheritanceType.TABLE_PER_CLASS) @PrimaryKeyJoinColumns({@PrimaryKeyJoinColumn(name="PK_FIELD_1", referredColumnName="BASE_1_ID"), @PrimaryKeyJoinColumn(name="PK_FIELD_2", referredColumnName="BASE_2_ID")}) public class MyClass { ... }
This annotation is used to define the name of the primary key column when this class has a superclass. Specified on the class.
Attribute | Type | Description | Default |
---|---|---|---|
name | String | Name of the column | |
referencedColumnName | String | Name of the associated PK column in the superclass | |
columnDefinition | String | DDL to use for the column (everything except the column name). This must include the SQL type of the column | |
foreignKey | ForeignKey | Foreign key details if wanting to override provider default |
@Entity @Inheritance(strategy=InheritanceType.TABLE_PER_CLASS) @PrimaryKeyJoinColumn(name="PK_FIELD_1") public class MyClass { ... }
This annotation is used to define a field of a superclass that has its column overridden. Specified on the class.
Attribute | Type | Description | Default |
---|---|---|---|
name | String | Name of the field | |
column | Column | Column information |
@Entity @AttributeOverride(name="attr", column=@Column(name="NEW_NAME")) public class MyClass extends MySuperClass { ... }
This annotation is used to define fields of a superclass that have their columns overridden. Specified on the class.
Attribute | Type | Description | Default |
---|---|---|---|
value | AttributeOverride[] | The overrides |
@Entity @AttributeOverrides({@AttributeOverride(name="attr1", column=@Column(name="NEW_NAME_1")), @AttributeOverride(name="attr2", column=@Column(name="NEW_NAME_2"))}) public class MyClass extends MySuperClass { ... }
This annotation is used to define a 1-1/N-1 field of a superclass that has its column overridden. Specified on the class.
Attribute | Type | Description | Default |
---|---|---|---|
name | String | Name of the field | |
joinColumn | JoinColumn | Column information for the FK column |
@Entity @AssociationOverride(name="friend", joinColumn=@JoinColumn(name="FRIEND_ID")) public class Employee extends Person { ... }
This annotation is used to define 1-1/N-1 fields of a superclass that have their columns overridden. Specified on the class.
Attribute | Type | Description | Default |
---|---|---|---|
value | AssociationOverride[] | The overrides |
@Entity @AssociationOverrides({@AssociationOverride(name="friend", joinColumn=@JoinColumn(name="FRIEND_ID")), @AssociationOverride(name="teacher", joinColumn=@JoinColumn(name="TEACHER_ID"))}) public class Employee extends Person { ... }
This annotation is used to define a field to use for the identity of the class. Specified on the field/method.
@Entity public class MyClass { @Id long id; ... }
This annotation is used to define a field as being embedded. Specified on the field/method.
@Entity public class MyClass { @Embedded Object myField; ... }
This annotation is used to define a field to use for the identity of the class when embedded. Specified on the field/method.
@Entity public class MyClass { @EmbeddedId MyPrimaryKey pk; ... }
This annotation is used to define a field as holding the version for the class. Specified on the field/method.
@Entity public class MyClass { @Id long id; @Version int ver; ... }
This annotation is used to define a field of the class as persistent. Specified on the field/method.
Attribute | Type | Description | Default |
---|---|---|---|
fetch | FetchType | Type of fetching for this field | LAZY | EAGER |
optional | boolean | Whether this field having a value is optional (can it have nulls) | true | false |
@Entity public class Person { @Id long id; @Basic(optional=false) String forename; ... }
See the documentation for Fields/Properties
This annotation is used to define a field of the class as not persistent. Specified on the field/method.
@Entity public class Person { @Id long id; @Transient String personalInformation; ... }
See the documentation for Fields/Properties
This annotation is used to define that a collection/map is stored using a join table. Specified on the field/method.
Attribute | Type | Description | Default |
---|---|---|---|
name | String | Name of the table | |
catalog | String | Name of the catalog | |
schema | String | Name of the schema | |
joinColumns | JoinColumn[] | Columns back to the owning object (with the collection/map) | |
inverseJoinColumns | JoinColumn[] | Columns to the element object (stored in the collection/map) | |
uniqueConstraints | UniqueConstraint[] | Any unique constraints to apply to the table | |
indexes | Index[] | Details of indexes if wanting to override provider default | |
foreignKey | ForeignKey | Foreign key details if wanting to override provider default for the join columns | |
inverseForeignKey | ForeignKey | Foreign key details if wanting to override provider default for the inverse join columns |
@Entity public class Person { @OneToMany @JoinTable(name="PEOPLES_FRIENDS") Collection friends; ... }
This annotation is used to define that a collection/map of non-entities is stored using a join table. Specified on the field/method.
Attribute | Type | Description | Default |
---|---|---|---|
name | String | Name of the table | |
catalog | String | Name of the catalog | |
schema | String | Name of the schema | |
joinColumns | JoinColumn[] | Columns back to the owning object (with the collection/map) | |
uniqueConstraints | UniqueConstraint[] | Any unique constraints to apply to the table | |
indexes | Index[] | Details of indexes if wanting to override provider default | |
foreignKey | ForeignKey | Details of foreign key if wanting to override provider default |
@Entity public class Person { @ElementCollection @CollectionTable(name="PEOPLES_FRIENDS") Collection<String> values; ... }
This annotation is used to define that a field will be stored using a large object in the datastore. Specified on the field/method.
@Entity public class Person { @Lob byte[] photo; ... }
This annotation is used to define that a field is stored as a temporal type. It specifies the JDBC type to use for storage of this type, so whether it stores the date, the time, or both. Specified on the field/method.
Attribute | Type | Description | Default |
---|---|---|---|
value | TemporalType | Type for storage | DATE | TIME | TIMESTAMP |
@Entity public class Person { @Temporal(TemporalType.TIMESTAMP) java.util.Date dateOfBirth; ... }
This annotation is used to define that a field is stored enumerated (not that it wasnt obvious from the type!). Specified on the field/method.
Attribute | Type | Description | Default |
---|---|---|---|
value | EnumType | Type for storage | ORDINAL | STRING |
enum Gender {MALE, FEMALE}; @Entity public class Person { @Enumerated Gender gender; ... }
This annotation is used to define that a field represents a 1-1 relation. Specified on the field/method.
Attribute | Type | Description | Default |
---|---|---|---|
targetEntity | Class | Class at the other side of the relation | |
fetch | FetchType | Whether the field should be fetched immediately | EAGER | LAZY |
optional | boolean | Whether the field can store nulls. | true | false |
mappedBy | String | Name of the field that owns the relation (specified on the inverse side) | |
cascade | CascadeType[] | Whether persist, update, delete, refresh operations are cascaded | |
orphanRemoval | boolean | Whether to remove orphans when either removing this side of the relation or when nulling the relation | true | false |
@Entity public class Person { @OneToOne Person bestFriend; ... }
See the documentation for 1-1 Relations
This annotation is used to define that a field represents a 1-N relation. Specified on the field/method.
Attribute | Type | Description | Default |
---|---|---|---|
targetEntity | Class | Class at the other side of the relation | |
fetch | FetchType | Whether the field should be fetched immediately | EAGER | LAZY |
mappedBy | String | Name of the field that owns the relation (specified on the inverse side) | |
cascade | CascadeType[] | Whether persist, update, delete, refresh operations are cascaded | |
orphanRemoval | boolean | Whether to remove orphans when either removing this side of the relation or when nulling the relationremoving an element | true | false |
@Entity public class Person { @OneToMany Collection<Person> friends; ... }
See the documentation for 1-N Relations
This annotation is used to define that a field represents a M-N relation. Specified on the field/method.
Attribute | Type | Description | Default |
---|---|---|---|
targetEntity | Class | Class at the other side of the relation | |
fetch | FetchType | Whether the field should be fetched immediately | EAGER | LAZY |
mappedBy | String | Name of the field on the non-owning side that completes the relation. Specified on the owner side. | |
cascade | CascadeType[] | Whether persist, update, delete, refresh operations are cascaded |
@Entity public class Customer { @ManyToMany(mappedBy="customers") Collection<Supplier> suppliers; ... } @Entity public class Supplier { @ManyToMany Collection<Customer> customers; ... }
See the documentation for M-N Relations
This annotation is used to define that a field represents a N-1 relation. Specified on the field/method.
Attribute | Type | Description | Default |
---|---|---|---|
targetEntity | Class | Class at the other side of the relation | |
fetch | FetchType | Whether the field should be fetched immediately | EAGER | LAZY |
optional | boolean | Whether the field can store nulls. | true | false |
cascade | CascadeType[] | Whether persist, update, delete, refresh operations are cascaded |
@Entity public class House { @OneToMany(mappedBy="house") Collection<Window> windows; ... } @Entity public class Window { @ManyToOne House house; ... }
See the documentation for N-1 Relations
This annotation is used to define that a field represents a 1-N relation to non-entity objects. Specified on the field/method.
Attribute | Type | Description | Default |
---|---|---|---|
targetClass | Class | Class at the other side of the relation | |
fetch | FetchType | Whether the field should be fetched immediately | EAGER | LAZY |
@Entity public class Person { @ElementCollection Collection<String> values; ... }
This DataNucleus-extension annotation is used to define an index for this field/property. Specified on the field/property.
Attribute | Type | Description | Default |
---|---|---|---|
name | String | Name of the index | |
unique | boolean | Whether the index is unique | false |
@Entity public class MyClass { @Index(name="ENABLED_IDX") boolean enabled; ... }
This DataNucleus-extension annotation is used to define the jdbc-type to use for this field/property. Specified on the field/property.
Attribute | Type | Description | Default |
---|---|---|---|
value | String | JDBC Type (VARCHAR, INTEGER, BLOB, etc) |
@Entity public class MyClass { @JdbcType("CHAR") boolean enabled; ... }
This DataNucleus-extension annotation is used to define the column position to use for this field/property. Specified on the field/property.
Attribute | Type | Description | Default |
---|---|---|---|
value | Integer | position of the column (first is "0", increasing) |
@Entity public class MyClass { @ColumnPosition(0) boolean enabled; ... }
This DataNucleus-extension annotation is used to allow use of non-JPA-standard value generators on a field/property. Specified on the field/property.
Attribute | Type | Description | Default |
---|---|---|---|
strategy | String | Name of the strategy e.g "uuid" |
@Entity public class MyClass { @ValueGenerator(strategy="uuid") String id; ... }
This annotation is used to define the generation of a value for a (PK) field. Specified on the field/method.
Attribute | Type | Description | Default |
---|---|---|---|
strategy | GenerationType | Strategy to use when generating the values for this field. Has possible values of GenerationType TABLE, SEQUENCE, IDENTITY, AUTO. | GenerationType.AUTO |
generator | String | Name of the generator to use. See @TableGenerator and @SequenceGenerator |
@Entity public class Person { @Id @GeneratedValue(strategy=GenerationType.TABLE) long id; ... }
This annotation is used to define the field in the value class that represents the key in a Map. Specified on the field/method.
Attribute | Type | Description | Default |
---|---|---|---|
name | String | Name of the field in the value class to use for the key. If no value is supplied and the field is a Map then it is assumed that the key will be the primary key of the value class. DataNucleus only supports this null value treatment if the primary key of the value has a single field. |
@Entity public class Person { @OneToMany @MapKey(name="nickname") Map<String, Person> friends; ... }
This annotation is used to define the datastore type used for the key of a map when it is a temporal type. Specified on the field/method.
@Entity public class Person { @ElementCollection @MapKeyTemporal(TemporalType.DATE) Map<Date, String> dateMap; ... }
This annotation is used to define the datastore type used for the key of a map when it is an enum. Specified on the field/method.
@Entity public class Person { @ElementCollection @MapKeyEnumerated(EnumType.STRING) Map<MyEnum, String> dateMap; ... }
This annotation is used to define the column details for a key of a Map when stored in a join table. Specified on the field/method.
Attribute | Type | Description | Default |
---|---|---|---|
name | String | Name of the column for the key |
@Entity public class Person { @OneToMany @MapKeyColumn(name="FRIEND_NAME") Map<String, Person> friends; ... }
This annotation is used to define a field in the element class that is used for ordering the elements of the List when it is retrieved. Specified on the field/method.
Attribute | Type | Description | Default |
---|---|---|---|
value | String | Name of the field(s) in the element class to use for ordering the elements of the List when retrieving them from the datastore. This is used by JPA "ordered lists" as opposed to JDO "indexed lists" (which always return the elements in the same order as they were persisted. The value will be a comma separated list of fields and optionally have ASC/DESC to signify ascending or descending |
@Entity public class Person { @OneToMany @OrderBy(value="nickname") List<Person> friends; ... }
This annotation is used to definethat the JPA implementation will handle the ordering of the List elements using a surrogate column. Specified on the field/method.
Attribute | Type | Description | Default |
---|---|---|---|
name | String | Name of the column to use. | {fieldName}_ORDER |
nullable | boolean | Whether the column is nullable | true | false |
insertable | boolean | Whether the column is insertable | true | false |
updatable | boolean | Whether the column is updatable | true | false |
base | int | Base for ordering (not currently supported) | 0 |
@Entity public class Person { @OneToMany @OrderColumn List<Person> friends; ... }
This annotation is used to define a converter for the field/property. Specified on the field/method.
Attribute | Type | Description | Default |
---|---|---|---|
converter | Class | Converter class | |
attributeName | String | Name of the embedded field to be converted (NOT YET SUPPORTED) | |
disableConversion | boolean | Whether we should disable any use of @Converter set to auto-apply |
@Entity public class Person { @Basic @Convert(converter=MyURLConverter.class) URL website; ... }
This annotation is used to mark a class as being an attribute converter. Note that DataNucleus doesn't require this specifying against a converter class except if you want to set the "autoApply". Specified on the field/method.
Attribute | Type | Description | Default |
---|---|---|---|
autoApply | boolean | Whether this converter should always be used when storing this java type | false |
@Converter public class MyConverter { ... }
This annotation is used to define the column where a field is stored. Specified on the field/method.
Attribute | Type | Description | Default |
---|---|---|---|
name | String | Name for the column | |
unique | boolean | Whether the field is unique | true | false |
nullable | boolean | Whether the field is nullable | true | false |
insertable | boolean | Whether the field is insertable | true | false |
updatable | boolean | Whether the field is updatable | true | false |
table | String | Name of the table | |
length | int | Length for the column | 255 |
precision | int | Decimal precision for the column | 0 |
scale | int | Decimal scale for the column | 0 |
columnDefinition | String | DDL to use for the column (everything except the column name). This must include the SQL type of the column |
@Entity public class Person { @Basic @Column(name="SURNAME", length=100, nullable=false) String surname; ... }
This annotation is used to define the FK column for joining to another table. This is part of a 1-1, 1-N, or N-1 relation. Specified on the field/method.
Attribute | Type | Description | Default |
---|---|---|---|
name | String | Name for the column | |
referencedColumnName | String | Name of the column in the other table that this is the FK for | |
unique | boolean | Whether the field is unique | true | false |
nullable | boolean | Whether the field is nullable | true | false |
insertable | boolean | Whether the field is insertable | true | false |
updatable | boolean | Whether the field is updatable | true | false |
columnDefinition | String | DDL to use for the column (everything except the column name). This must include the SQL type of the column | |
foreignKey | ForeignKey | Foreign key details if wanting to override provider default |
@Entity public class Person { @OneToOne @JoinColumn(name="PET_ID", nullable=true) Animal pet; ... }
This annotation is used to define the FK columns for joining to another table. This is part of a 1-1, 1-N, or N-1 relation. Specified on the field/method.
Attribute | Type | Description | Default |
---|---|---|---|
value | JoinColumn[] | Details of the columns | |
foreignKey | ForeignKey | Foreign key details if wanting to override provider default |
@Entity public class Person { @OneToOne @JoinColumns({@JoinColumn(name="PET1_ID"), @JoinColumn(name="PET2_ID")}) Animal pet; // composite PK ... }
This annotation is used to define a unique constraint to apply to a table. It is specified as part of @Table, @JoinTable or @SecondaryTable.
Attribute | Type | Description | Default |
---|---|---|---|
columnNames | String[] | Names of the column(s) |
@Entity @Table(name="PERSON", uniqueConstraints={@UniqueConstraint(columnNames={"firstName","lastName"})}) public class Person { @Basic String firstName; @Basic String lastName; ... }
See the documentation for Schema Constraints
This annotation is used to define the details for an Index. It is specified as part of @Table, @JoinTable, @CollectionTable or @SecondaryTable.
Attribute | Type | Description | Default |
---|---|---|---|
name | String | Name of the index | |
columnList | String | Columns to be included in this index of the form colName1, colName2 | |
unique | boolean | Whether the index is unique | false |
See the documentation for Schema Constraints
This annotation is used to define the details for a ForeignKey. It is specified as part of @JoinColumn, @JoinTable, @CollectionTable or @SecondaryTable.
Attribute | Type | Description | Default |
---|---|---|---|
name | String | Name of the foreign key | |
value | ConstraintMode | Constraint mode | ConstraintMode.CONSTRAINT |
foreignKeyDefinition | String | DDL for the FOREIGN KEY statement of the form FOREIGN KEY ( colExpr1 {, colExpr2}... ) REFERENCES tblIdentifier [ ( otherColExpr1 {, otherColExpr2}... ) ] [ ON UPDATE updateAction ] [ ON DELETE deleteAction ] |
See the documentation for Schema Constraints
DataNucleus Extension Annotation used to define a set of extensions specific to DataNucleus. Specified on the class or field.
Attribute | Type | Description | Default |
---|---|---|---|
value | Extension[] | Array of extensions - see @Extension annotation |
@Entity @Extensions({@Extension(key="firstExtension", value="myValue"), @Extension(key="secondExtension", value="myValue")}) public class Person { ... }
DataNucleus Extension Annotation used to define an extension specific to DataNucleus. Specified on the class or field.
Attribute | Type | Description | Default |
---|---|---|---|
vendorName | String | Name of the vendor | datanucleus |
key | String | Key for the extension | |
value | String | Value of the extension |
@Entity @Extension(key="RunFast", value="true") public class Person { ... }