To implement a persistence layer with JPA you firstly need to map the classes and fields/properties that are involved in the persistence process to how they are represented in the datastore. This can be as simple as marking the classes as @Entity and defaulting the datastore definition, or you can configure down to the fine detail of precisely what schema it maps on to. The following sections deal with the many options available for using metadata to map your entities.

When mapping a class for JPA you make use of metadata, and this metadata can be Java annotations, or can be XML metadata, or a mixture of both. This is very much down to your own personal preference but we try to present both ways here.

We advise trying to keep schema information out of annotations, so that you avoid tying compiled code to a specific datastore. That way you retain datastore-independence. This may not be a concern for your project however.

Whilst the JPA spec only allows you to specify your mapping information using JPA metadata (annotations, or orm.xml), DataNucleus JPA also allows you the option of using JDO annotations. This is provided as a way of easily migrating across to JPA from JDO, for example. Consult the DataNucleus JDO mappings docs for details.

Classes

We have the following types of classes in DataNucleus JPA.

Entity - persistable class with full control over its persistence.
MappedSuperclass - persistable class that will not be persisted into its own table simply providing some fields to be persisted. Consequently an inheritance tree cannot just have a mapped superclass on its own.
Embeddable - persistable class that is only persistable embedded into an entity class.
PersistenceAware - a class that is not itself persisted, but that needs to access internals of persistable classes. This is a DataNucleus extension, not part of the JPA standard.

DataNucleus JPA imposes very little on classes used within the persistence process so, to a very large degree, you should design your classes as you would normally do and not design them to fit DataNucleus JPA.

In strict JPA all persistable classes need to have a default constructor. With DataNucleus JPA this is not necessary, since all classes are enhanced before persistence and the enhancer adds on a default constructor if one is not defined.

If defining a method toString in a JPA entity class, be aware that use of a persistable field will cause the load of that field if the object is managed and is not yet loaded.

If a JPA entity class is an element of a Java collection in another entity, you are advised to define hashCode and equals methods for reliable handling by Java collections.

Entity Class

Let’s take a sample class (Hotel) as an example. We can define a class as persistable using either annotations in the class, or XML metadata. Using annotations

@Entity
public class Hotel
{
    ...
}

or using XML metadata

<entity class="mydomain.test.Hotel">
    ...
</entity>

MappedSuperclass

Say we have an abstract base class Building with concrete subclass Hotel (as above). We want to persist some fields of Building, but it is abstract so will not have any objects of that type. So we make the class a MappedSuperclass, like this

@MappedSuperclass
public abstract class Building
{
    ...
}

or using XML metadata

<mapped-superclass class="mydomain.test.Building">
    ...
</mapped-superclass>

This is of particular relevance when considering inheritance.

Embeddable Class

Here we have a class ConstructionDetails that we never need to persist individually, and it will only ever be persisted as part of an owner object (in this case Building). Since information from objects of this class will be persisted, we need to mark the class as Embeddable, like this

@Embeddable
public class ConstructionDetails
{
    ...
}

or using XML metadata

<embeddable class="mydomain.test.ConstructionDetails">
    ...
</embeddable>

and hereafter we can persist fields of type ConstructionDetails, as per the Embedded Object guide.

Persistence Aware Class

nucleus extension

With JPA you cannot access public fields of classes. DataNucleus allows an extension to permit this, but such classes need special enhancement. To allow this you need to annotate the class that will access these public fields (assuming it isn’t an Entity) with the DataNucleus extension annotation @PersistenceAware, as follows

import org.datanucleus.api.jpa.annotations.PersistenceAware;

@PersistenceAware
public class MyClassThatAccessesPublicFields
{
    ...
}

See also :-

Annotations reference for @PersistenceAware

Read-Only Class

nucleus extension

You can, if you wish, make a class read-only. This is a DataNucleus extension and you set it as follows

import org.datanucleus.api.jpa.annotations.ReadOnly;

@Entity
@ReadOnly
public class MyClass
{
    ...
}

In practical terms this means that at runtime, if you try to persist an object of this type then an exception will be thrown. You can read objects of this type from the datastore just as you would for any persistable class

See also :-

Annotations reference for @ReadOnly

SoftDelete

nucleus extension

Applicable to RDBMS, MongoDB, HBase, Cassandra, Neo4j

With standard JPA when you delete an object from persistence it is deleted from the datastore. DataNucleus provides a useful ability to soft delete objects from persistence. In simple terms, any persistable types marked for soft deletion handling will have an extra column added to their datastore table to represent whether the record is soft-deleted. If it is soft deleted then it will not be visible at runtime thereafter, but will be present in the datastore.

You mark a persistable type for soft deletion handling like this

import org.datanucleus.api.jpa.annotations.SoftDelete;

@Entity
@SoftDelete
public class Hotel
{
    ...
}

You could optionally specify the column attribute of the @SoftDelete annotation to define the column name where this flag is stored.

Whenever any objects of type Hotel are deleted, like this

em.remove(myHotel);

the myHotel object will be updated to set the soft-delete flag to true.

Any call to em.find or query will not return the object since it is effectively deleted (though still present in the datastore).

If you want to view the object, you can specify the query hint include-soft-deletes as true and the soft-deleted records will be visible.

This feature is still undergoing development, so not all aspects are feature complete.

Inheritance

In Java it is a normal situation to have inheritance between classes. With JPA you have choices to make as to how you want to persist your classes for the inheritance tree. For each inheritance tree (for the root class) you select how you want to persist those classes information. You have the following choices.

The default strategy is to select a class to have its fields persisted in the table of the base class. There is only one table per inheritance hierarchy. In JPA this is known as SINGLE_TABLE
The next way is to have a table for each class in the inheritance hierarchy, and for each table to only hold columns for the fields of that class. Fields of superclasses are persisted into the table of the superclass. Consequently to get all field values for a subclass object a join is made of all tables of superclasses. In JPA this is referred to as JOINED
The third way is like JOINED except that each table will also contain columns for all inherited fields. In JPA this is referred to as TABLE_PER_CLASS

In order to demonstrate the various inheritance strategies we need an example. Here are a few simple classes representing products in a (online) store. We have an abstract base class, extending this to provide something that we can represent any product by. We then provide a few specialisations for typical products. We will use these classes later when defining how to persistent these objects in the different inheritance strategies

inheritance classes

As mentioned, the default JPA strategy is "SINGLE_TABLE", namely that the base class will have a table and all subclasses will be persisted into that same table. So if you don’t specify an "inheritance strategy" in your root class this is what you will get.

You must specify the identity of objects in the root persistable class of the inheritance hierarchy. You cannot redefine it down the inheritance tree

See also:-

Discriminator

Applicable to RDBMS, HBase, MongoDB

A discriminator is an extra "column" stored alongside data to identify the class of which that information is part. It is useful when storing objects which have inheritance to provide a quick way of determining the object type on retrieval. A discriminator in JPA will store the specified value (or the class name if you provide no value). You specify a discriminator as follows

<entity name="mydomain.Product">
    <discriminator-column name="OBJECT" discriminator-type="STRING"/>
    <discriminator-value>MyClass</discriminator-value>
    ...

or with annotations

@Entity
@DiscriminatorColumn(name="OBJECT_TYPE", discriminatorType=DiscriminatorType.STRING)
@DiscriminatorValue("MyClass")
public class Product {...}

Strategy : SINGLE_TABLE

Applicable to RDBMS

"SINGLE_TABLE" strategy is where the root class has a table and all subclasses are also persisted into that table. This corresponds to JDOs "new-table" for the root class and "superclass-table" for all subclasses. This has the advantage that retrieval of an object is a single DB call to a single table. It also has the disadvantage that the single table can have a very large number of columns, and database readability and performance can suffer, and additionally that a discriminator column is required.

When using SINGLE-TABLE DataNucleus will always use a discriminator (default column name is DTYPE) whether or not you define metadata for it.

In our example, lets ignore the AbstractProduct class for a moment and assume that Product is the base class (with the "id"). We have no real interest in having separate tables for the Book and CompactDisc classes and want everything stored in a single table PRODUCT. We change our MetaData as follows

<entity name="Product">
    <inheritance strategy="SINGLE_TABLE"/>
    <discriminator-value>PRODUCT</discriminator-value>
    <discriminator-column name="PRODUCT_TYPE" discriminator-type="STRING"/>
    <attributes>
        <id name="id">
            <column name="PRODUCT_ID"/>
        </id>
        ...
    </attributes>
</entity>
<entity name="Book">
    <discriminator-value>BOOK</discriminator-value>
     ...
</entity>
<entity name="TravelGuide">
    <discriminator-value>TRAVELGUIDE</discriminator-value>
    ...
</entity>
<entity name="CompactDisc">
    <discriminator-value>COMPACTDISC</discriminator-value>
    ...
</entity>

or using annotations

@Entity
@Inheritance(strategy=InheritanceType.SINGLE_TABLE)
@DiscriminatorValue("PRODUCT")
@DiscriminatorColumn(name="PRODUCT_TYPE", discriminatorType=DiscriminatorType.STRING)
public class Product {...}

@Entity
@DiscriminatorValue("BOOK")
public class Book {...}

@Entity
@DiscriminatorValue("TRAVELGUIDE")
public class TravelGuide {...}

@Entity
@DiscriminatorValue("COMPACTDISC")
public class CompactDisc {...}

This change of use of the inheritance element has the effect of using the PRODUCT table for all classes, containing the fields of Product, Book, CompactDisc, and TravelGuide. You will also note that we used a /discriminator-column_ element for the Product class. The specification above will result in an extra column (called PRODUCT_TYPE) being added to the PRODUCT table, and containing the "discriminator-value" of the object stored. So for a Book it will have "BOOK" in that column for example. This column is used in discriminating which row in the database is of which type. The final thing to note is that in our classes Book and CompactDisc we have a field that is identically named. With CompactDisc we have defined that its column will be called DISCTITLE since both of these fields will be persisted into the same table and would have had identical names otherwise - this gets around the problem.

inheritance db superclasstable

In the above example, when we insert a TravelGuide object into the datastore, a row will be inserted into the PRODUCT table only.

Strategy : JOINED

Applicable to RDBMS

"JOINED" strategy means that each entity in the inheritance hierarchy has its own table and that the table of each class only contains columns for that class. Inherited fields are persisted into the tables of the superclass(es). This corresponds to JDOs "new-table" (for all classes in the inheritance hierarchy). This has the advantage of being the most normalised data definition. It also has the disadvantage of being slower in performance since multiple tables will need to be accessed to retrieve an object of a sub-type. Let’s try an example using the simplest to understand strategy JOINED. We have the classes defined above, and we want to persist our classes each in their own table. We define the Meta-Data for our classes like this</p>

<entity class="AbstractProduct">
    <inheritance strategy="JOINED"/>
    <attributes>
        <id name="id">
            <column name="PRODUCT_ID"/>
        </id>
        ...
    </attributes>
</entity>
<entity class="Product">
    ...
</entity>
<entity class="Book">
    ...
</entity>
<entity class="TravelGuide">
    ...
</entity>
<entity class="CompactDisc">
    ...
</entity>

or using annotations

@Entity
@Inheritance(strategy=InheritanceType.JOINED)
public class Product {...}

So we will have 5 tables - ABSTRACTPRODUCT, PRODUCT, BOOK, COMPACTDISC, and TRAVELGUIDE. They each contain just the fields for that class (and not any inherited fields, except the identity to join with).

inheritance db newtable

In the above example, when we insert a TravelGuide object into the datastore, a row will be inserted into ABSTRACTPRODUCT, PRODUCT, BOOK, and TRAVELGUIDE.

Strategy : TABLE_PER_CLASS

Applicable to all datastores

This strategy is like "JOINED" except that in addition to each class having its own table, the table also holds columns for all inherited fields. So taking the same classes as used above

<entity class="AbstractProduct">
    <inheritance strategy="TABLE_PER_CLASS"/>
    <attributes>
        <id name="id">
            <column name="PRODUCT_ID"/>
        </id>
        ...
    </attributes>
</entity>
<entity class="Product">
    ...
</entity>
<entity class="Book">
    ...
</entity>
<entity class="TravelGuide">
    ...
</entity>
<entity class="CompactDisc">
    ...
</entity>

or using annotations

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

This then implies a datastore schema as follows inheritance db completetable

So any object of explicit type Book is persisted into the table BOOK. Similarly any TravelGuide is persisted into the table TRAVELGUIDE, etc. In addition if any class in the inheritance tree is abstract then it won’t have a table since there cannot be any instances of that type. DataNucleus currently has limitations when using a class using this inheritance as the element of a collection.

Mapped Superclasses

JPA defines entities called "mapped superclasses" for the situation where you dont persist an actual object of a superclass type but that all subclasses of that type that are entities will also persist the values for the fields of the "mapped superclass". That is a "mapped superclass" has no table to store its objects in a datastore. Instead its fields are stored in the tables of its subclasses. Let’s take an example

<mapped-superclass class="AbstractProduct">
    <attributes>
        <id name="id">
            <column name="PRODUCT_ID"/>
        </id>
        ...
    </attributes>
</mapped-superclass>

<entity class="Product">
    ...
</entity>

In this case we will have a table for Product and the fields of AbstractProduct will be stored in this table. If the mapping information (column names etc) for these fields need setting then you should use <attribute-override> in the MetaData for Product.

Identity

All JPA-enabled persistable classes need to have an "identity" to be able to identify an object for retrieval and relationships. In strict JPA there is only 1 type of identity - application identity, where you have a field or field(s) of the entity that are used to define the identity. With DataNucleus JPA we allow 2 additional types of identity. So your options are

Application Identity : a field, or several fields of the persistable type are assigned as being (part of) the primary key.
Datastore Identity : a surrogate column is added to the persistence of the persistable type, and objects of this type are identified by the class plus the value in this surrogate column. DataNucleus Extension
Nondurable Identity : the persistable type has no identity as such, so the only way to lookup objects of this type would be via query for values of specific fields. This is useful for storing things like log messages etc. DataNucleus Extension

A further complication is where you use application identity but one of the fields forming the primary key is a relation field. This is known as Derived Identity.

When you have an inheritance hierarchy, you should specify the identity type in the base instantiable class for the inheritance tree. This is then used for all persistent classes in the tree. This means that you can have @MappedSuperclass without any identity fields/properties as superclass, and then the base instantiable class is the first persistable class which has the identity field(s).

Application Identity

Applicable to all datastores.

With application identity you are taking control of the specification of id’s to DataNucleus. Application identity can require a primary key class (when you have multiple identity fields), and each persistable class may define a different class for its primary key, and different persistent capable classes can use the same primary key class, as appropriate. With application identity the field(s) of the primary key will be present as field(s) of the class itself. To specify that a class is to use application identity, you add the following to the MetaData for the class.

<entity class="org.mydomain.MyClass">
    <attributes>
        <id name="myPrimaryKeyField"/>
    </attributes>
</entity>

or, if we are using annotations

@Entity
public class MyClass
{
    @Id
    private long myPrimaryKeyField;
}

When we have multiple identity fields we also require an id-class, using XML

<entity class="org.mydomain.MyClass">
    <id-class class="org.mydomain.MyIdClass"/>
    <attributes>
        <id name="myPrimaryKeyField1"/>
        <id name="myPrimaryKeyField2"/>
    </attributes>
</entity>

or, if we are using annotations

@Entity
@IdClass(class=MyIdClass.class)
public class MyClass
{
    @Id
    private long myPrimaryKeyField1;

    @Id
    private long myPrimaryKeyField2;

}

The definition of the @IdClass is described further below.

See also:-

Application Identity : Generating identities

By choosing application identity you are controlling the process of identity generation for this class. This does not mean that you have a lot of work to do for this. JPA defines many ways of generating these identities and DataNucleus supports all of these and provides some more of its own besides.

Application Identity : Changing Identities

JPA doesn’t define what happens if you change the identity (an identity field) of an object once persistent. DataNucleus doesn’t support changes to identities.

Application Identity : Accessing objects by Identity

You access an object from its object class name and identity "value" as follows

MyClass myObj = em.find(MyClass.class, mykey);

If you have defined your own "IdClass" then the mykey is the toString() form of the identity of your PK class.

Primary Key

When you choose application identity you are defining which fields of the class are part of the primary key, and you are taking control of the specification of id’s to DataNucleus. Application identity requires a primary key (PK) class, and each persistent capable class may define a different class for its primary key, and different persistent capable classes can use the same primary key class, as appropriate. If you have only a single primary-key field then there are built-in PK classes so you can forget this section.

If you are thinking of using multiple primary key fields in a class we would urge you to consider using a single (maybe surrogate) primary key field instead for reasons of simplicity and performance. This also means that you can avoid the need to define your own primary key class.

Where you have more than 1 primary key field, you would define the PK class like this

<entity class="MyClass">
    <id-class class="MyIdClass"/>
    ...
</entity>

or using annotations

@Entity
@IdClass(class=MyIdClass.class)
public class MyClass
{
    ...
}

You now need to define the PK class to use. This is simplified for you because if you have only one PK field then you dont need to define a PK class and you only define it when you have a composite PK.

An important thing to note is that the PK can only be made up of fields of the following Java types

Primitives : boolean, byte, char, int, long, short
java.lang : Boolean, Byte, Character, Integer, Long, Short, String, Enum, StringBuffer
java.math : BigInteger
java.sql : Date, Time, Timestamp
java.util : Date, Currency, Locale, TimeZone, UUID
java.net : URI, URL
persistable

Note that the types in bold are JPA standard types. Any others are DataNucleus extensions and, as always, check the specific datastore docs to see what is supported for your datastore.

Single PrimaryKey field

The simplest way of using application identity is where you have a single PK field, and in this case you use an inbuilt primary key class that DataNucleus provides, so you don’t need to specify the id-class. Let’s take an example

public class MyClass
{
    long id;
    ...
}

<entity class="MyClass">
    <attributes>
        <id name="id"/>
        ...
    </attributes>
</entity>

or using annotations

@Entity
public class MyClass
{
    @Id
    long id;
    ...
}

Note that we didn’t specify the JPA "id-class". You will, of course, have to give the field a value before persisting the object, either by setting it yourself, or by using a value-strategy on that field.

PrimaryKey : Rules for User-Defined classes

If you wish to use application identity and don’t want to use the "SingleFieldIdentity" built-in PK classes then you must define a Primary Key class of your own. You can’t use classes like java.lang.String, or java.lang.Long directly. You must follow these rules when defining your primary key class.

The Primary Key class must be public
The Primary Key class must implement Serializable
The Primary Key class must have a public no-arg constructor, which might be the default constructor
The PrimaryKey class can have a constructor taking the primary key fields, or can use Java bean setters/getters
The field types of all non-static fields in the Primary Key class must be serializable, and are recommended to be primitive, String, Date, or Number types
All serializable non-static fields in the Primary Key class can be public, but package/protected/private should also be fine
The names of the non-static fields in the Primary Key class must include the names of the primary key fields in the Entity, and the types of the common fields must be identical
The equals() and hashCode() methods of the Primary Key class must use the value(s) of all the fields corresponding to the primary key fields in the JPA entity
If the Primary Key class is an inner class, it must be static
The Primary Key class must override the toString() method defined in Object, and return a String that can be used as the parameter of a constructor
The Primary Key class must provide a String constructor that returns an instance that compares equal to an instance that returned that String by the toString() method.
The Primary Key class must be only used within a single inheritance tree.

Please note that if one of the fields that comprises the primary key is in itself an entity then you have Derived Identity and should consult the documentation for that feature which contains its own example.

nucleus extension

Since there are many possible combinations of primary-key fields it is impossible for DataNucleus to provide a series of builtin composite primary key classes. However the DataNucleus Enhancer provides a mechanism for auto-generating a primary-key class for a persistable class. It follows the rules listed above and should work for all cases. Obviously if you want to tailor the output of things like the PK toString() method then you ought to define your own. The enhancer generation of primary-key class is only enabled if you don’t define your own class.

Your "id" class can store the target class name of the persistable object that it represents. This is useful where you want to avoid lookups of a class in an inheritance tree. To do this, add a field to your id-class called targetClassName and make sure that it is part of the toString() and String constructor code.

PrimaryKey Example - Multiple Field

Again, if you are thinking of using multiple primary key fields in a class we would urge you to consider using a single (maybe surrogate) primary key field instead for reasons of simplicity and performance. This also means that you can avoid the need to define your own primary key class.

Here’s an example of a composite (multiple field) primary key class

@Entity
@IdClass(ComposedIdKey.class)
public class MyClass
{
    @Id
    String field1;

    @Id
    String field2;
    ...
}

public class ComposedIdKey implements Serializable
{
    public String targetClassName; // DataNucleus extension, storing the class name of the persistable object
    public String field1;
    public String field2;

    /**
     *  Default constructor.
     */
    public ComposedIdKey ()
    {
    }

    /**
     * Constructor accepting same input as generated by toString().
     */
    public ComposedIdKey(String value)
    {
        StringTokenizer token = new StringTokenizer (value, "::");
        this.targetClassName = token.nextToken();
        this.field1 = token.nextToken ();
        this.field2 = token.nextToken ();
    }

    public boolean equals(Object obj)
    {
        if (obj == this)
        {
            return true;
        }
        if (!(obj instanceof ComposedIdKey))
        {
            return false;
        }
        ComposedIdKey c = (ComposedIdKey)obj;

        return field1.equals(c.field1) && field2.equals(c.field2);
    }

    public int hashCode ()
    {
        return this.field1.hashCode() ^ this.field2.hashCode();
    }

    public String toString ()
    {
        // Give output expected by String constructor
        return this.targetClassName + this.field1 + "::" + this.field2;
    }
}

Datastore Identity

nucleus extension

Applicable to RDBMS, ODF, Excel, OOXML, XML, HBase, Cassandra, Neo4j, MongoDB, JSON

While JPA defines support for application identity only, DataNucleus also provides support for datastore identity. With datastore identity you are leaving the assignment of id’s to DataNucleus and your class will not have a field for this identity - it will be added to the datastore representation by DataNucleus. It is, to all extents and purposes, a surrogate key that will have its own column in the datastore. To specify that a class is to use datastore identity with JPA, you define the metadata as follows

<entity class="org.mydomain.MyClass">
    <datastore-id/>
    ...
</entity>

or using annotations, for example

@Entity
@org.datanucleus.api.jpa.annotations.DatastoreIdentity
public class MyClass
{
    ...
}

Please note that since the JPA XML metadata is poorly designed it is not possible to specify datastore identity using XML, you have to use the annotations.

Datastore Identity : Generating identities

By choosing datastore identity you are handing the process of identity generation to the DataNucleus. This does not mean that you haven’t got any control over how it does this. JPA defines many ways of generating these identities and DataNucleus supports all of these and provides some more of its own besides.

Defining which one to use is a simple matter of adding a MetaData element to your classes definition, like this

@Entity
@org.datanucleus.api.jpa.annotations.DatastoreIdentity(generationType=GenerationType.TABLE)
public class MyClass
{
    ...
}

See also:-

Identity Generation Guide - strategies for generating ids
Annotations reference for @DatastoreIdentity

Datastore Identity : Accessing the Identity

When using datastore identity, the class has no associated field so you can’t just access a field of the class to see its identity - if you need a field to be able to access the identity then you should be using application identity. There are, however, ways to get the identity for the datastore identity case, if you have the object.

import org.datanucleus.api.jpa.NucleusJPAHelper;

Object idKey = NucleusJPAHelper.getDatastoreIdForEntity(obj);

From this you can use the "find" method to retrieve the object

MyClass myObj = em.find(MyClass.class, idKey);

Nondurable Identity

nucleus extension

Applicable to RDBMS, ODF, Excel, OOXML, HBase, Neo4j, MongoDB

JPA requires that all objects have an identity. DataNucleus provides a vendor extension that allows objects of a class to not have a unique identity in the datastore. This type of identity is typically for log files, history files etc where you aren’t going to access the object by key, but instead by a different parameter. In the datastore the table will typically not have a primary key. To specify that a class is to use nondurable identity with DataNucleus you would add the following to the MetaData for the class.

<entity class="org.mydomain.MyClass">
    <nondurable-id/>
    ...
</entity>

or using annotations, for example

@Entity
@org.datanucleus.api.jpa.annotations.NonDurableId
public class MyClass
{
    ...
}

What this means for something like RDBMS is that the table of the class will not have a primary-key.

Derived Identity Relationships

An derived identity relationship is a relationship between two objects of two classes in which the child object must coexist with the parent object and where the primary key of the child includes the Entity object of the parent. So effectively the key aspect of this type of relationship is that the primary key of one of the classes includes a Entity field (hence why is is referred to as Derived Identity). This type of relation is available in the following forms

1-1 unidirectional
1-N collection bidirectional using ForeignKey
1-N map bidirectional using ForeignKey (key stored in value)

A more efficient relationship is to handle this as a standard 1-1/1-N relation, with individual id field in the related class, and then define a unique constraint on the related class. This then foregoes the "derived identity" relationship idea and you can stick to standard relationships.

In standard JPA, if the entity that is part of the id of the derived entity has a single long field then you can put a long field in the identity class of the derived entity. In DataNucleus you cannot do this currently, and should define the @IdClass of the entity being contained and use that type in the identity class of the derived entity.

The persistable class that is contained cannot be using datastore identity, and must be using application identity with an objectid-class

When using derived identity, it is best practice to define an @IdClass for any entity that is part of the primary key, and not rely on the built-in identity types.

Derived 1-1 Relationship

Lets take the same classes as we have in the 1-1 Relationships. In the 1-1 relationships guide we note that in the datastore representation of the User and Account the ACCOUNT table has a primary key as well as a foreign-key to USER. In our example here we want to just have a primary key that is also a foreign-key to USER. To do this we need to modify the classes slightly and add primary-key fields and use "application-identity".

public class User
{
    long id;

    ...
}

public class Account
{
    User user;

    ...
}

In addition we need to define primary key classes for our User and Account classes

@Entity
public class User
{
    @Id
    long id;

    ... (remainder of User class)

    /**
     * Inner class representing Primary Key
     */
    public static class PK implements Serializable
    {
        public long id;

        public PK()
        {
        }

        public PK(String s)
        {
            this.id = Long.valueOf(s).longValue();
        }

        public String toString()
        {
            return "" + id;
        }

        public int hashCode()
        {
            return (int)id;
        }

        public boolean equals(Object other)
        {
            if (other != null && (other instanceof PK))
            {
                PK otherPK = (PK)other;
                return otherPK.id == this.id;
            }
            return false;
        }
    }
}

@Entity
public class Account
{
    @Id
    @OneToOne
    User user;

    ... (remainder of Account class)

    /**
     * Inner class representing Primary Key
     */
    public static class PK implements Serializable
    {
        public User.PK user; // Use same name as the real field above

        public PK()
        {
        }

        public PK(String s)
        {
            StringTokenizer token = new StringTokenizer(s,"::");

            this.user = new User.PK(token.nextToken());
        }

        public String toString()
        {
            return "" + this.user.toString();
        }

        public int hashCode()
        {
            return user.hashCode();
        }

        public boolean equals(Object other)
        {
            if (other != null && (other instanceof PK))
            {
                PK otherPK = (PK)other;
                return this.user.equals(otherPK.user);
            }
            return false;
        }
    }
}

To achieve what we want with the datastore schema we define the MetaData like this

<entity-mappings>
    <entity class="mydomain.User">
        <table name="USER"/>
        <id-class class="mydomain.User.PK"/>
        <attributes>
            <id name="id">
                <column name="USER_ID"/>
            </id>
            <basic name="login">
                <column name="LOGIN" length="20"/>
            </basic>
        </attributes>
    </entity>

    <entity class="mydomain.Account">
        <table name="ACCOUNT"/>
        <id-class class="mydomain.Account.PK"/>
        <attributes>
            <id name="user">
                <column name="USER_ID"/>
            </id>
            <basic name="firstName">
                <column name="FIRSTNAME" length="50"/>
            </basic>
            <basic name="secondName">
                <column name="LASTNAME" length="50"/>
            </basic>
            <one-to-one name="user"/>
        </attributes>
    </entity>
</entity-mappings>

So now we have the following datastore schema

relationship 1 1 compound db

Things to note:-

In the child Primary Key class, you must have a field with the same name as the relationship in the child class, and the field in the child Primary Key class must be the same type as the Primary Key class of the parent
See also the general instructions for Primary Key classes
You can only have one "Account" object linked to a particular "User" object since the FK to the "User" is now the primary key of "Account". To remove this restriction you could also add a "long id" to "Account" and make the "Account.PK" a composite primary-key

Derived 1-N Collection Relationship

Lets take the same classes as we have in the 1-N Relationships (FK). In the 1-N relationships guide we note that in the datastore representation of the Account and Address classes the ADDRESS table has a primary key as well as a foreign-key to ACCOUNT. In our example here we want to have the primary-key to ACCOUNT to include the foreign-key. To do this we need to modify the classes slightly, adding primary-key fields to both classes, and use "application-identity" for both.

public class Account
{
    long id;

    Set<Address> addresses;

    ...
}

public class Address
{
    long id;

    Account account;

    ...
}

In addition we need to define primary key classes for our Account and Address classes

@Entity
public class Account
{
    @Id
    long id;

    @OneToMany
    Set<Address> addresses = new HashSet<>();

    ... (remainder of Account class)

    /**
     * Inner class representing Primary Key
     */
    public static class PK implements Serializable
    {
        public long id;

        public PK()
        {
        }

        public PK(String s)
        {
            this.id = Long.valueOf(s).longValue();
        }

        public String toString()
        {
            return "" + id;
        }

        public int hashCode()
        {
            return (int)id;
        }

        public boolean equals(Object other)
        {
            if (other != null && (other instanceof PK))
            {
                PK otherPK = (PK)other;
                return otherPK.id == this.id;
            }
            return false;
        }
    }
}

@Entity
public class Address
{
    @Id
    long id;

    @Id
    @ManyToOne
    Account account;

    .. (remainder of Address class)

    /**
     * Inner class representing Primary Key
     */
    public static class PK implements Serializable
    {
        public long id; // Same name as real field above
        public Account.PK account; // Same name as the real field above

        public PK()
        {
        }

        public PK(String s)
        {
            StringTokenizer token = new StringTokenizer(s,"::");
            this.id = Long.valueOf(token.nextToken()).longValue();
            this.account = new Account.PK(token.nextToken());
        }

        public String toString()
        {
            return "" + id + "::" + this.account.toString();
        }

        public int hashCode()
        {
            return (int)id ^ account.hashCode();
        }

        public boolean equals(Object other)
        {
            if (other != null && (other instanceof PK))
            {
                PK otherPK = (PK)other;
                return otherPK.id == this.id && this.account.equals(otherPK.account);
            }
            return false;
        }
    }
}

To achieve what we want with the datastore schema we define the MetaData like this

<entity-mappings>
    <entity class="mydomain.Account">
        <table name="ACCOUNT"/>
        <id-class class="mydomain.Account.PK"/>
        <attributes>
            <id name="id">
                <column name="ACCOUNT_ID"/>
            </id>
            <basic name="firstName">
                <column name="FIRSTNAME" length="50"/>
            </basic>
            <basic name="secondName">
                <column name="LASTNAME" length="50"/>
            </basic>
            <one-to-many name="addresses" mapped-by="account"/>
        </attributes>
    </entity>

    <entity class="mydomain.Address">
        <table name="ADDRESS"/>
        <id-class class="mydomain.Address.PK"/>
        <attributes>
            <id name="id">
                <column name="ID"/>
            </id>
            <id name="account">
                <column name="ACCOUNT_ID"/>
            </id>
            <basic name="city">
                <column name="CITY"/>
            </basic>
            <basic name="street">
                <column name="STREET"/>
            </basic>
            <many-to-one name="account"/>
        </attributes>
    </entity>
</entity-mappings>

So now we have the following datastore schema

relationship 1 N compound db

Things to note :-

In the child Primary Key class, you must have a field with the same name as the relationship in the child class, and the field in the child Primary Key class must be the same type as the Primary Key class of the parent
See also the general instructions for Primary Key classes
If we had omitted the "id" field from "Address" it would have only been possible to have one "Address" in the "Account" "addresses" collection due to PK constraints. For that reason we have the "id" field too.

Derived 1-N Map Relationship

Lets take the same classes as we have in the 1-N Relationships FK. In this guide we note that in the datastore representation of the Account and Address classes the ADDRESS table has a primary key as well as a foreign-key to ACCOUNT. In our example here we want to have the primary-key to ACCOUNT to include the foreign-key. To do this we need to modify the classes slightly, adding primary-key fields to both classes, and use "application-identity" for both.

public class Account
{
    long id;

    Map<String, Address> addresses;

    ...
}

public class Address
{
    long id;

    String alias;

    Account account;

    ...
}

In addition we need to define primary key classes for our Account and Address classes

@Entity
public class Account
{
    @Id
    long id;

    @OneToMany
    Map<String, Address> addresses;

    ... (remainder of Account class)

    /**
     * Inner class representing Primary Key
     */
    public static class PK implements Serializable
    {
        public long id;

        public PK()
        {
        }

        public PK(String s)
        {
            this.id = Long.valueOf(s).longValue();
        }

        public String toString()
        {
            return "" + id;
        }

        public int hashCode()
        {
            return (int)id;
        }

        public boolean equals(Object other)
        {
            if (other != null && (other instanceof PK))
            {
                PK otherPK = (PK)other;
                return otherPK.id == this.id;
            }
            return false;
        }
    }
}

@Entity
public class Address
{
    @Id
    String alias;

    @Id
    @ManyToOne
    Account account;

    .. (remainder of Address class)

    /**
     * Inner class representing Primary Key
     */
    public static class PK implements Serializable
    {
        public String alias; // Same name as real field above
        public Account.PK account; // Same name as the real field above

        public PK()
        {
        }

        public PK(String s)
        {
            StringTokenizer token = new StringTokenizer(s,"::");
            this.alias = Long.valueOf(token.nextToken()).longValue();
            this.account = new Account.PK(token.nextToken());
        }

        public String toString()
        {
            return alias + "::" + this.account.toString();
        }

        public int hashCode()
        {
            return alias.hashCode() ^ account.hashCode();
        }

        public boolean equals(Object other)
        {
            if (other != null && (other instanceof PK))
            {
                PK otherPK = (PK)other;
                return otherPK.alias.equals(this.alias) && this.account.equals(otherPK.account);
            }
            return false;
        }
    }
}

To achieve what we want with the datastore schema we define the MetaData like this

<entity-mappings>
    <entity class="mydomain.Account">
        <table name="ACCOUNT"/>
        <id-class class="mydomain.Account.PK"/>
        <attributes>
            <id name="id">
                <column name="ACCOUNT_ID"/>
            </id>
            <basic name="firstName">
                <column name="FIRSTNAME" length="50"/>
            </basic>
            <basic name="secondName">
                <column name="LASTNAME" length="50"/>
            </basic>
            <one-to-many name="addresses" mapped-by="account">
                <map-key name="alias"/>
            </one-to-many>
        </attributes>
    </entity>

    <entity class="mydomain.Address">
        <table name="ADDRESS"/>
        <id-class class="mydomain.Address.PK"/>
        <attributes>
            <id name="account">
                <column name="ACCOUNT_ID"/>
            </id>
            <id name="alias">
                <column name="KEY"/>
            </id>
            <basic name="city">
                <column name="CITY"/>
            </basic>
            <basic name="street">
                <column name="STREET"/>
            </basic>
            <many-to-one name="account"/>
        </attributes>
    </entity>
</entity-mappings>

So now we have the following datastore schema relationship 1 N compound map db

Things to note :-

In the child Primary Key class, you must have a field with the same name as the relationship in the child class, and the field in the child Primary Key class must be the same type as the Primary Key class of the parent
See also the general instructions for Primary Key classes
If we had omitted the "alias" field from "Address" it would have only been possible to have one "Address" in the "Account" "addresses" collection due to PK constraints. For that reason we have the "alias" field too as part of the PK.

Versioning

JPA allows objects of classes to be versioned. The version is typically used as a way of detecting if the object has been updated by another thread or EntityManager since retrieval using the current EntityManager - for use by Optimistic Locking.

Version Field/Property

The standard JPA mechanism for versioning of objects is to mark a field of the class to store the version. The field must be Integer/Long based. With JPA you can specify the details of this version field as follows

@Entity
public class User
{
    ...

    @Version
    int version;

    ...
}

or using XML metadata

<entity name="mydomain.User">
    <attributes>
        ...
        <version name="version"/>
        ...
    </attributes>
</entity>

The specification above will use the "version" field for storing the version of the object. DataNucleus will use a "version-number" strategy for populating the value.

Surrogate Version for Class

nucleus extension

While the above mechanism should always be used for portability, DataNucleus also supports a surrogate version for objects of a class. With this you don’t have a particular field that stores the version and instead DataNucleus persists the version in the datastore with the field values in its own "column". You do this as follows.

import org.datanucleus.api.jpa.annotations.SurrogateVersion;

@Entity
@SurrogateVersion
public class User
{
    ...
}

or using XML metadata

<entity name="mydomain.User">
    <surrogate-version column="version"/>
    ...
</entity>

To access the "surrogate" version, you can make use of the following method

import org.datanucleus.api.jpa.NucleusJPAHelper;

Object version = NucleusJPAHelper.getSurrogateVersionForEntity(obj);

Auditing

Applicable to RDBMS

With standard JPA you have no annotations available to automatically add timestamps and user names into the datastore against each record when it is persisted or updated. Whilst you can do this manually, setting the field(s) in prePersist callbacks etc, DataNucleus provides some simple annotations to make it simpler still.

import org.datanucleus.api.jpa.annotations.CreateTimestamp;
import org.datanucleus.api.jpa.annotations.CreateUser;
import org.datanucleus.api.jpa.annotations.UpdateTimestamp;
import org.datanucleus.api.jpa.annotations.UpdateUser;

@Entity
public class Hotel
{
    @Id
    long id;

    @CreateTimestamp
    Timestamp createTimestamp;

    @CreateUser
    String createUser;

    @UpdateTimestamp
    Timestamp updateTimestamp;

    @UpdateUser
    String updateUser;

    ...
}

In the above example we have 2 fields in the class that will have columns in the datastore. The field createTimestamp and createUser will be persisted at INSERT with the Timestamp and current user for the insert. The field updateTimestamp and updateUser will be persisted whenever any update is made to the object in the datastore, with the Timestamp and current user for the update.

Defining the Current User

The timestamp can be automatically generated for population here, but clearly the current user is not available as a standard, and so we have to provide a mechanism for setting it. You have 2 ways to do this. Choose the one that is most appropriate to your situation

Specify the persistence property datanucleus.CurrentUser on the EMF to be the current user to use. Optionally you can also specify the same persistence property on each PM if you have a particular user for each EM.
Define an implementation of the DataNucleus interface CurrentUserProvider, and specify it on EMF creation using the property datanucleus.CurrentUserProvider. This is defined as follows

public interface CurrentUserProvider
{
    /** Return the current user. */
    String currentUser();
}

So you could, for example, store the current user in a thread-local and return it via your implementation of this interface.

Fields/Properties

Once we have defined a class to be persistable (as either Entity, MappedSuperclass, or Embedded), we need to define how to persist the different fields/properties that are to be persisted. There are two distinct modes of persistence definition; the most common uses fields, whereas an alternative uses properties.

Persistent Fields

The most common form of persistence is where you have a field in a class and want to persist it to the datastore. With this mode of operation DataNucleus will persist the values stored in the fields into the datastore, and will set the values of the fields when extracting it from the datastore.

Requirement : you have a field in the class. This can be public, protected, private or package access, but cannot be static or final.

An example of how to define the persistence of a field is shown below

@Entity
public class MyClass
{
    @Basic
    Date birthday;

    @Transient
    String someOtherField;
}

So, using annotations, we have marked this class as persistent, and the field birthday also as persistent, whereas field someOtherField is not persisted. Using XML MetaData we would have done

<entity name="mydomain.MyClass">
    <attributes>
        <basic name="birthday"/>
        <transient name="someOtherField"/>
    </attributes>
</entity>

Please note that the field Java type defines whether it is, by default, persistable. With DataNucleus the majority of types that you will come across in your application are persistable.

Persistent Properties

A second mode of operation is where you have Java Bean-style getter/setter for a property. In this situation you want to persist the output from getXXX to the datastore, and use the setXXX to load up the value into the object when extracting it from the datastore.

Requirement : you have a property in the class with Java Bean getter/setter methods. These methods can be public, protected, private or package access, but cannot be static. The class must have BOTH getter AND setter methods.

The JavaBean specification is to have a getter method with signature {type} getMyField() and a setter method with signature void setMyField({type} arg), where the property name is then myField, and the type is {type}.

An example of how to define the persistence of a property is shown below

@Entity
public class MyClass
{
    @Basic
    Date getBirthday()
    {
        ...
    }

    void setBirthday(Date date)
    {
        ...
    }
}

So, using annotations, we have marked this class as persistent, and the getter is marked as persistent. By default a property is non-persistent, so we have no need in specifying the someOtherField as transient. Using XML MetaData we would have done

<entity name="mydomain.MyClass">
    <attributes>
        <basic name="birthday"/>
    </attributes>
</entity>

Making a field/property non-persistent

If you have a field/property that you don’t want to persist, just mark it as transient, like this

    @Transient
    String unimportantField;

or with XML

<entity name="mydomain.MyClass">
    <attributes>
        <transient name="unimportantField"/>
    </attributes>
</entity>

Making a field/property read-only

nucleus extension

If you want to make a member read-only you can do it like this.

<entity name="mydomain.MyClass">
    <attributes>
        <basic name="myField">
            <column insertable="false" updatable="false"/>
        </basic>
    </attributes>
</entity>

or with Annotations

import org.datanucleus.api.jdo.annotations.ReadOnly;

@Entity
public class MyClass
{
    @ReadOnly
    String myField;

}

Field Types

When persisting a class, a persistence solution needs to know how to persist the types of each field in the class. Clearly a persistence solution can only support a finite number of Java types; it cannot know how to persist every possible type creatable. The JPA specification define lists of types that are required to be supported by all implementations of those specifications. This support can be conveniently split into two parts

Primary Types : An object that can be referred to (object reference, providing a relation) and that has an "identity" is termed a primary type. DataNucleus supports the following Java types as primary : any Entity that has its own identity, interface where it represents an Entity, or java.lang.Object where it represents an Entity.
Secondary Types : An object that does not have an "identity" is termed a secondary type. This is something like a String or Date field in a class, or alternatively a Collection (that contains other objects), or an embedded Entity. The sections below shows the currently supported secondary java types in DataNucleus. The tables in these sections show
- EAGER : whether the field is retrieved by default when retrieving the object itself.
- Proxy : whether the field is represented by a "proxy" that intercepts any operations to detect whether it has changed internally (such as Collection, Map).
- PK : whether the field can be used as part of the primary-key

The JPA spec places restrictions on what you can and can’t do with a @MappedSuperclass type. DataNucleus largely treats it like any entity, so can be used for querying, or relations.

The JPA spec has a required list of types that a provider should support is very basic. DataNucleus provides all of those and many many more, see below.

With DataNucleus, all types that we have a way of persisting (i.e listed below) are default persistent (meaning that you don’t need to annotate them in any way to persist them). The only field types where this is not always true is for java.lang.Object, some Serializable types, array of persistables, and java.io.File so always safer to mark those as persistent.

nucleus plugin

If you have support for any additional types and would either like to contribute them, or have them listed here, let us know. Supporting a new type is easy, typically involving a JPA AttributeConverter if you can easily convert the type into a String or Long. See also the Java Types plugin-point. You can also define more specific support for it with RDBMS datastores - the RDBMS Java Types plugin-point

Handling of second-class types uses wrappers and bytecode enhancement with DataNucleus. This contrasts to what Hibernate uses (proxies), and what Hibernate imposes on you.

When your field type is a type that is mutable it will be replaced by a "wrapper" when the owning object is managed. By default this wrapper type will be based on the instantiated type. You can change this to use the declared type by setting the persistence property datanucleus.type.wrapper.basis to declared.

Primitive and java.lang Types

All primitive types and wrappers are supported and will be persisted into a single database "column". Arrays of these are also supported, and can either be serialised into a single column, or persisted into a join table (dependent on datastore).

Java Type

EAGER?

Proxy?

PK?

Comments

boolean

Persisted as BOOLEAN, Integer (i.e 1,0), String (i.e 'Y','N').

byte

char

double

float

int

long

short

java.lang.Boolean

Persisted as BOOLEAN, Integer (i.e 1,0), String (i.e 'Y','N').

java.lang.Byte

java.lang.Character

java.lang.Double

java.lang.Float

java.lang.Integer

java.lang.Long

java.lang.Short

java.lang.Number

Persisted in a column capable of storing a BigDecimal, and will store to the precision of the object to be persisted. On reading back the object will be returned typically as a BigDecimal since there is no mechanism for determing the type of the object that was stored.

java.lang.String

java.lang.StringBuffer

Persisted as String. The dirty check mechanism for this type is limited to immutable mode, which means if you change a StringBuffer object field, you must reassign it to the owner object field to make sure changes are propagated to the database.

java.lang.StringBuilder

Persisted as String. The dirty check mechanism for this type is limited to immutable mode, which means if you change a StringBuffer object field, you must reassign it to the owner object field to make sure changes are propagated to the database.

java.lang.Class

Persisted as String.

java.math types

BigInteger and BigDecimal are supported and persisted into a single numeric column by default.

Java Type

EAGER?

Proxy?

PK?

Comments

java.math.BigDecimal

Persisted as DOUBLE or String. String can be used to retain precision.

java.math.BigInteger

Persisted as INTEGER or String. String can be used to retain precision.

Temporal Types (java.util, java.sql. java.time, Jodatime)

DataNucleus supports a very wide range of temporal types, with flexibility in how they are persisted.

Java Type

EAGER?

Proxy?

PK?

Comments

java.sql.Date

Persisted as DATE, String, DATETIME or Long.

java.sql.Time

Persisted as TIME, String, DATETIME or Long.

java.sql.Timestamp

Persisted as TIMESTAMP, String or Long.

java.util.Calendar

Persisted as TIMESTAMP (inc Timezone), DATETIME, String, or as (Long, String) storing millis + timezone respectively

java.util.GregorianCalendar

Persisted as TIMESTAMP (inc Timezone), DATETIME, String, or as (Long, String) storing millis + timezone respectively

java.util.Date

Persisted as DATETIME, String or Long.

java.util.TimeZone

Persisted as String.

java.time.LocalDateTime

Persisted as DATETIME, String, or Timestamp.

java.time.LocalTime

Persisted as TIME, String, or Long.

java.time.LocalDate

Persisted as DATE, String, or DATETIME.

java.time.OffsetDateTime

Persisted as Timestamp, String, or DATETIME.

java.time.OffsetTime

Persisted as TIME, String, or Long.

java.time.MonthDay

Persisted as String, DATE, or as (Integer,Integer) with the latter being month+day respectively.

java.time.YearMonth

Persisted as String, DATE, or as (Integer,Integer) with the latter being year+month respectively.

java.time.Year

Persisted as Integer, or String.

java.time.Period

Persisted as String.

java.time.Instant

Persisted as TIMESTAMP, String, Long, or DATETIME.

java.time.Duration

Persisted as String, Double (secs.nanos), or Long (secs).

java.time.ZoneId

Persisted as String.

java.time.ZoneOffset

Persisted as String.

java.time.ZonedDateTime

Persisted as Timestamp, or String.

org.joda.time.DateTime

Requires datanucleus-jodatime plugin. Persisted as TIMESTAMP or String.

org.joda.time.LocalTime

Requires datanucleus-jodatime plugin. Persisted as TIME or String.

org.joda.time.LocalDate

Requires datanucleus-jodatime plugin. Persisted as DATE or String.

org.joda.time.LocalDateTime

Requires datanucleus-jodatime plugin. Persisted as TIMESTAMP, or String.

org.joda.time.Duration

Requires datanucleus-jodatime plugin. Persisted as String or Long.

org.joda.time.Interval

Requires datanucleus-jodatime plugin. Persisted as String or (TIMESTAMP, TIMESTAMP).

org.joda.time.Period

Requires datanucleus-jodatime plugin. Persisted as String.

Collection/Map types

DataNucleus supports a very wide range of collection, list and map types. It also supports the declared type to be not just interfaces (Collection, Set, List, Map) but also common implementations (unlike many other JPA providers which only support the interface types).

Java Type

EAGER?

Proxy?

PK?

Comments

java.util.Collection

See the 1-N Collections Guide

java.util.List

See the 1-N Lists Guide

java.util.Map

See the 1-N Maps Guide

java.util.Queue

The comparator is specifiable via the metadata extension comparator-name (see below). See the 1-N Lists Guide

java.util.Set

See the 1-N Collections Guide

java.util.SortedMap

The comparator is specifiable via the metadata extension comparator-name (see below). See the 1-N Maps Guide

java.util.SortedSet

The comparator is specifiable via the metadata extension comparator-name (see below). See the 1-N Collections Guide

java.util.ArrayList

See the 1-N Lists Guide

java.util.BitSet

Persisted as collection by default, but will be stored as String when the datastore doesn’t provide for collection storage

java.util.HashMap

See the 1-N Maps Guide

java.util.HashSet

See the 1-N Collections Guide

java.util.Hashtable

See the 1-N Maps Guide

java.util.LinkedHashMap

Persisted as a Map currently. No List-ordering is supported. See the 1-N Maps Guide

java.util.LinkedHashSet

Persisted as a Set currently. No List-ordering is supported. See the 1-N Collections Guide

java.util.LinkedList

See the 1-N Lists Guide

java.util.Properties

See the 1-N Maps Guide

java.util.PriorityQueue

The comparator is specifiable via the metadata extension comparator-name (see below). See the 1-N Lists Guide

java.util.Stack

See the 1-N Lists Guide

java.util.TreeMap

The comparator is specifiable via the metadata extension comparator-name (see below). See the 1-N Maps Guide

java.util.TreeSet

The comparator is specifiable via the metadata extension comparator-name (see below). See the 1-N Collections Guide

java.util.Vector

See the 1-N Lists Guide

com.google.common.collect.Multiset

Requires datanucleus-guava plugin. See the 1-N Collections Guide

Collection Comparators

nucleus extension

Collections that support a Comparator to order the elements of the set can specify it in metadata like this.

@OneToMany
@Extension(key="comparator-name", value="mydomain.model.MyComparator")
SortedSet<MyElementType> elements;

When instantiating the SortedSet field, it will create it with a comparator of the specified class (which must have a default constructor).

Enums

By default an Enum is persisted as either a String form (the name), or as an integer form (the ordinal). You control which form by specifying the @Enumerated annotation (or equivalent XML).

Java Type EAGER? Proxy? PK? Comments

java.lang.Enum

Persisted as String (name) or int (ordinal). Specified via @Enumerated annotation or equivalent XML.

Enum custom values

nucleus extension

A DataNucleus extension to this is where you have an Enum that defines its own "value"s for the different enum options.

Applicable to RDBMS, MongoDB, Cassandra, Neo4j, HBase, Excel, ODF and JSON currently.

public enum MyColour
{
    RED((short)1), GREEN((short)3), BLUE((short)5), YELLOW((short)8);

    private short value;

    private MyColour(short value)
    {
        this.value = value;
    }

    public short getValue()
    {
        return value;
    }
}

With the default persistence it would persist as String-based, so persisting "RED" "GREEN" "BLUE" etc. With @Enumerated as ORDINAL it would persist 0, 1, 2, 3 being the ordinal values. If you define the metadata as

@Extension(key="enum-value-getter", value="getValue")
MyColour colour;

this will now persist 1, 3, 5, 8, being the "value" of each of the enum options. You can use this method to persist "int", "short", or "String" types.

Enum CHECK constraints

nucleus extension

Supported for RDBMS datastores.

If you want to constraint the column where the Enum is stored to only have the values for that enum you can put a CHECK constraint on the column contents in the datastore. You specify it like this

@Extension(vendorName="datanucleus", key="enum-check-constraint", value="true")
MyColour colour;

This results in a column defined like

MY_COL VARCHAR(10) CHECK (MY_COL IN ('RED', 'GREEN', 'BLUE', 'YELLOW')),

This is the recommended way of constraining enum values in the datastore since it uses ANSI SQL, and it is a better more portable solution than using such as PostgreSQL enum type.

Geospatial Types

DataNucleus has extensive support for Geospatial types. The datanucleus-geospatial plugin allows using geospatial and traditional types simultaneously in persistent objects making DataNucleus a single interface to read and manipulate any business data. This plugin supports types from all of the most used geospatial libraries, see below. The implementation of many of these spatial types follows the OGC Simple Feature specification, but adds further types where the datastores support them.

Some extra notes for implementation of JTS, JGeometry and PostGIS types support :-

MySQL doesn’t support 3-dimensional geometries. Trying to persist them anyway results in undefined behaviour, there may be an exception thrown or the z-ordinate might just get stripped.

Oracle supports additional data types like circles and curves that are not defined in the OGC SF specification. Any attempt to read or persist one of those data types, if you’re not using Oracle, will result in failure!

PostGIS added support for curves in version 1.2.0, but at the moment the JDBC driver doesn’t support them yet. Any attempt to read curves geometries will result in failure, for every mapping scenario!

Both PostGIS and Oracle have a system to add user data to specific points of a geometry. In PostGIS these types are called measure types and the z-coordinate of every 2d-point can be used to store arbitrary (numeric) data of double precision associated with that point. In Oracle this user data is called LRS. datanucleus-geospatial tries to handle these types as gracefully as possible. But the recommendation is to not use them, unless you have a mapping scenario that is known to support them.

PostGIS supports two additional types called box2d and box3d, that are not defined in OGC SF. There are only mappings available for these types for PostGIS, any attempt to read or persist one of those data types in another mapping scenario will result in failure!

We do not currently support persisting to the PostGIS "geography" type, only the (most used) "geometry" type.

java.awt Java types

The JRE contains very limited support for some geometric types, largely under the java.awt package.

Java Type

EAGER?

Proxy?

PK?

Comments

java.awt.Point

Requires datanucleus-geospatial plugin. Persisted as (int, int) on RDBMS, or as String elsewhere.

java.awt.Rectangle

Requires datanucleus-geospatial plugin. Persisted as (int, int, int, int) on RDBMS, or as String elsewhere.

java.awt.Polygon

Requires datanucleus-geospatial plugin. Persisted as (int[], int[], int) on RDBMS, or as String elsewhere.

java.awt.geom.Line2D

Requires datanucleus-geospatial plugin. Persisted as (double, double, double, double) or (float, float, float, float) on RDBMS, or as String elsewhere.

java.awt.geom.Point2D

Requires datanucleus-geospatial plugin. Persisted as (double, double) or (float, float) on RDBMS, or as String elsewhere.

java.awt.geom.Rectangle2D

Requires datanucleus-geospatial plugin. Persisted as (double, double, double, double) or (float, float, float, float) on RDBMS, or as String elsewhere.

java.awt.geom.Arc2D

Requires datanucleus-geospatial plugin. Persisted as (double, double, double, double, double, double, int) or (float, float, float, float, float, float, int) on RDBMS, or as String elsewhere.

java.awt.geom.CubicCurve2D

Requires datanucleus-geospatial plugin. Persisted as (double, double, double, double, double, double, doubel, double) or (float, float, float, float, float, float, float, float) on RDBMS, or as String elsewhere.

java.awt.geom.Ellipse2D

Requires datanucleus-geospatial plugin Persisted as (double, double, double, double) or (float, float, float, float) on RDBMS, or as String elsewhere.

java.awt.geom.QuadCurve2D

Requires datanucleus-geospatial plugin. Persisted as (double, double, double, double, double, double) or (float, float, float, float, float, float) on RDBMS, or as String elsewhere.

java.awt.geom.RoundRectangle2D

Requires datanucleus-geospatial plugin. Persisted as (double, double, double, double, double, double) or (float, float, float, float, float, float) on RDBMS, or as String elsewhere.

JTS Topology Suite Java types

The JTS Topology Suite is a Java library for creating and manipulating vector geometry.

Java Type

DFG?

Proxy?

PK?

Comments

com.vividsolutions.jts.geom.Geometry