Primary Key

Using application identity requires the use of a Primary Key class. When you have a single primary-key field a built-in class is available meaning you don't need to define this class. This is referred to as SingleFieldIdentity. We strongly recommend not to specify the PK class when you have a single PK field since these built-in classes are likely more optimised. Where the class has multiple fields that form the primary key a Primary Key class must be provided.

See also :-

• Primary Key Guide - user-defined and built-in primary keys

Compound Identity

Where one of the fields that is primary-key of your class is a persistable object you have something known as compound identity since the identity of this class contains the identity of a related class. Please refer to the docs for Compound 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. JDO defines many ways of generating these identities and DataNucleus supports all of these and provides some more of its own besides.

See also :-

• Identity Generation Guide - strategies for generating ids

Accessing the Identity

When using application identity, the class has associated field(s) that equate to the identity. As a result you can simply access the values for these field(s). Alternatively you could use a JDO identity-independent way

Object id = pm.getObjectId(obj);

Object id = JDOHelper.getObjectId(obj);

Changing Identities

JDO allows implementations to support the changing of the identity of a persisted object. This is an optional feature and DataNucleus doesn't currently support it.

Accessing objects by Identity

If you have the JDO identity then you can access the object with that identity like this

Object obj = pm.getObjectById(id);

If you are using SingleField identity then you can access it from the object class name and the key value like this

Object obj = pm.getObjectById(MyClass.class, mykey);

If you are using your own PK class then the mykey value is the toString() form of the identity of your PK class.

Single PrimaryKey field

The simplest way of using application identity is where you have a single PK field, and in this case you use SingleFieldIdentity . mechanism. This provides a PrimaryKey and you don't need to specify the objectid-class. Let's take an example

public class MyClass
{
    long id;
    ...
}

<class name="MyClass" identity-type="application">
    <field name="id" primary-key="true"/>
    ...
</class>

or using annotations

@PersistenceCapable
public class MyClass
{
    @PrimaryKey
    long id;
    ...
}

So we didnt specify the JDO "objectid-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.

If you need to create an identity of this form for use in querying via pm.getObjectById() then you can create the identities in the following way

For a "long" type :
javax.jdo.identity.LongIdentity id = new javax.jdo.identity.LongIdentity(myClass, 101);

For a "String" type :
javax.jdo.identity.StringIdentity id = new javax.jdo.identity.StringIdentity(myClass, "ABCD");

We have shown an example above for type "long", but you can also use this for the following

short, Short       - javax.jdo.identity.ShortIdentity
int, Integer       - javax.jdo.identity.IntIdentity
long, Long         - javax.jdo.identity.LongIdentity
String             - javax.jdo.identity.StringIdentity
char, Character    - javax.jdo.identity.CharIdentity
byte, Byte         - javax.jdo.identity.ByteIdentity
java.util.Date     - javax.jdo.identity.ObjectIdentity
java.util.Currency - javax.jdo.identity.ObjectIdentity
java.util.Locale   - javax.jdo.identity.ObjectIdentity

Multiple PrimaryKey field

Since there are many possible combinations of primary-key fields it is impossible for JDO 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 below 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.

Rules for User-Defined PrimaryKey classes

If you wish to use application identity and don't want to use the "SingleFieldIdentity" builtin 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 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 must be public
• the names of the non-static fields in the Primary Key class must include the names of the primary key fields in the JDO class, 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 JDO class
• 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 inheritence tree.

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

PrimaryKey Example - Multiple Field

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

@PersistenceCapable(objectIdClass=ComposedIdKey.class)
public class MyClass
{
    @PrimaryKey
    String field1;

    @PrimaryKey
    String field2;
    ...
}

public class ComposedIdKey implements Serializable
{
    public String field1;
    public String field2;

    public ComposedIdKey ()
    {
    }

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

    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.getClass().getName() + "::"  + this.field1 + "::" + this.field2;
    }
}