PrimaryKey (Oracle - Berkeley DB Java API)
Date: 2013-05-31

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Berkeley DB version 6.0.19
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: REQUIRED | OPTIONAL | DETAIL: ELEMENT

## com.sleepycat.persist.model
Annotation Type PrimaryKey

    @Documented
    @Retention(value=RUNTIME)
    @Target(value=FIELD)
    public @interface PrimaryKey

Indicates the primary key field of an entity class. The value of the primary key field is the unique identifier for the entity in a `PrimaryIndex`.

`PrimaryKey` may appear on at most one declared field per class.

Primary key values may be automatically assigned as sequential integers using a `sequence()`. In this case the type of the key field is restricted to a simple integer type.

A primary key field may not be null, unless it is being assigned from a sequence.

Key Field Types

The type of a key field must either be one of the following:

- Any of the simple types.
- An enum type.
- A composite key class containing one or more simple type or enum fields.

Array types are not allowed.

When using a composite key class, each field of the composite key class must be annotated with `KeyField` to identify the storage order and default sort order. See `KeyField` for an example and more information on composite keys.

Key Sort Order

Key field types, being simple types, have a well defined and reasonable default sort order, described below. This sort order is based on a storage encoding that allows a fast byte-by-byte comparison.

- All simple types except for `String` are encoded so that they are sorted as expected, that is, as if the `Comparable.compareTo(T)` method of their class (or, for primitives, their wrapper class) is called.
- Strings are encoded as UTF-8 byte arrays. Zero (0x0000) character values are UTF encoded as non-zero values, and therefore embedded zeros in the string are supported. The sequence {0xC0,0x80} is used to encode a zero character. This UTF encoding is the same one used by native Java UTF libraries. However, this encoding of zero does impact the lexicographical ordering, and zeros will not be sorted first (the natural order) or last. For all character values other than zero, the default UTF byte ordering is the same as the Unicode lexicographical character ordering.

When using a composite key class with more than one field, the sorting order among fields is determined by the `KeyField` annotations. To override the default sort order, you can use a composite key class that implements `Comparable`. This allows overriding the sort order and is therefore useful even when there is only one key field in the composite key class. See Custom Sort Order for more information on sorting of composite keys.

Inherited Primary Key

If it does not appear on a declared field in the entity class, `PrimaryKey` must appear on a field of an entity superclass. In the following example, the primary key on the base class is used:

     @Persistent
     class BaseClass {
         @PrimaryKey
         long id;
         ...
     }
     @Entity
     class Employee extends BaseClass {
         // inherits id primary key
         ...
     }

If more than one class with `PrimaryKey` is present in a class hierarchy, the key in the most derived class is used. In this case, primary key fields in superclasses are "shadowed" and are not persistent. In the following example, the primary key in the base class is not used and is not persistent:

     @Persistent
     class BaseClass {
         @PrimaryKey
         long id;
         ...
     }
     @Entity
     class Employee extends BaseClass {
         // overrides id primary key
         @PrimaryKey
         String uuid;
         ...
     }

Note that a `PrimaryKey` is not allowed on entity subclasses. The following is illegal and will cause an `IllegalArgumentException` when trying to store an `Employee` instance:

     @Entity
     class Person {
         @PrimaryKey
         long id;
         ...
     }
     @Persistent
     class Employee extends Person {
         @PrimaryKey
         String uuid;
         ...
     }

Optional Element Summary
`String` | `sequence` The name of a sequence from which to assign primary key values automatically.

### sequence

    public abstract String sequence

  The name of a sequence from which to assign primary key values automatically. If a non-empty string is specified, sequential integers will be assigned from the named sequence.

  A single sequence may be used for more than one entity class by specifying the same sequence name for each `PrimaryKey`. For each named sequence, a `Sequence` will be used to assign key values. For more information on configuring sequences, see `EntityStore.setSequenceConfig`.

  To use a sequence, the type of the key field must be a primitive integer type (`byte`, `short`, `int` or `long`) or the primitive wrapper class for one of these types. A composite key class may also be used to override sort order, but it may contain only a single key field, and this field must have one of the types previously mentioned.

  When an entity with a primary key sequence is stored using one of the `put` methods in the `PrimaryIndex`, a new key will be assigned if the primary key field in the entity instance is null (for a reference type) or zero (for a primitive integer type). Specifying zero for a primitive integer key field is allowed because the initial value of the sequence is one (not zero) by default. If the sequence configuration is changed such that zero is part of the sequence, then the field type must be a primitive wrapper class and the field value must be null to cause a new key to be assigned.

  When one of the `put` methods in the `PrimaryIndex` is called and a new key is assigned, the assigned value is returned to the caller via the key field of the entity object that is passed as a parameter.

  Default:
    ""

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Berkeley DB version 6.0.19
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: REQUIRED | OPTIONAL | DETAIL: ELEMENT

Copyright (c) 1996, 2013 Oracle and/or its affiliates. All rights reserved.