• Home
• com.sleepycat
• je
• 18.3.12
• source code
• KeyField.java

×

Project download

Many resources are needed to download a project. Please understand that we have to compensate our server costs. Thank you in advance.
Project price only 1 $

You can buy this project and download/modify it how often you want.

com.sleepycat.persist.model.KeyField Maven / Gradle / Ivy

/*-
 * Copyright (C) 2002, 2018, Oracle and/or its affiliates. All rights reserved.
 *
 * This file was distributed by Oracle as part of a version of Oracle Berkeley
 * DB Java Edition made available at:
 *
 * http://www.oracle.com/technetwork/database/database-technologies/berkeleydb/downloads/index.html
 *
 * Please see the LICENSE file included in the top-level directory of the
 * appropriate version of Oracle Berkeley DB Java Edition for a copy of the
 * license and additional information.
 */

package com.sleepycat.persist.model;

import static java.lang.annotation.ElementType.FIELD;
import static java.lang.annotation.RetentionPolicy.RUNTIME;

import java.lang.annotation.Documented;
import java.lang.annotation.Retention;
import java.lang.annotation.Target;

import com.sleepycat.je.Environment;

/**
 * Indicates the sorting position of a key field in a composite key class when
 * the {@code Comparable} interface is not implemented.  The {@code KeyField}
 * integer value specifies the sort order of this field within the set of
 * fields in the composite key.
 *
 * 
If the field type of a {@link PrimaryKey} or {@link SecondaryKey} is a
 * composite key class containing more than one key field, then a {@code
 * KeyField} annotation must be present on each non-transient instance field of
 * the composite key class.  The {@code KeyField} value must be a number
 * between one and the number of non-transient instance fields declared in the
 * composite key class.
 *
 * 
Note that a composite key class is a flat container for one or more
 * simple type fields.  All non-transient instance fields in the composite key
 * class are key fields, and its superclass must be {@code Object}.
 *
 * 
For example:
 * 
 *  {@literal @Entity}
 *  class Animal {
 *      {@literal @PrimaryKey}
 *      Classification classification;
 *      ...
 *  }
 *
 *  {@literal @Persistent}
 *  class Classification {
 *      {@literal @KeyField(1) String kingdom;}
 *      {@literal @KeyField(2) String phylum;}
 *      {@literal @KeyField(3) String clazz;}
 *      {@literal @KeyField(4) String order;}
 *      {@literal @KeyField(5) String family;}
 *      {@literal @KeyField(6) String genus;}
 *      {@literal @KeyField(7) String species;}
 *      {@literal @KeyField(8) String subspecies;}
 *      ...
 *  }
 *
 * 
This causes entities to be sorted first by {@code kingdom}, then by
 * {@code phylum} within {@code kingdom}, and so on.
 *
 * 
The fields in a composite key class may not be null.
 *
 * 
Custom Sort Order
 *
 * 
To override the default sort order, a composite key class may implement
 * the {@link Comparable} interface.  This allows overriding the sort order and
 * is therefore useful even when there is only one key field in the composite
 * key class.  For example, the following class sorts Strings using a Canadian
 * collator:
 *
 * 
 *  import java.text.Collator;
 *  import java.util.Locale;
 *
 *  {@literal @Entity}
 *  class Animal {
 *      ...
 *      {@literal @SecondaryKey(relate=ONE_TO_ONE)}
 *      CollatedString canadianName;
 *      ...
 *  }
 *
 *  {@literal @Persistent}
 *  {@literal class CollatedString implements Comparable} {
 *
 *      static Collator collator = Collator.getInstance(Locale.CANADA);
 *
 *      {@literal @KeyField(1)}
 *      String value;
 *
 *      CollatedString(String value) { this.value = value; }
 *
 *      private CollatedString() {}
 *
 *      public int compareTo(CollatedString o) {
 *          return collator.compare(value, o.value);
 *      }
 *  }
 *
 * 
Several important rules should be considered when implementing a custom
 * comparison method.  Failure to follow these rules may result in the primary
 * or secondary index becoming unusable; in other words, the store will not be
 * able to function.
 * 

 * 
The comparison method must always return the same result, given the same
 * inputs.  The behavior of the comparison method must not change over
 * time.
 * 
A corollary to the first rule is that the behavior of the comparison
 * method must not be dependent on state which may change over time.  For
 * example, if the above collation method used the default Java locale, and the
 * default locale is changed, then the sort order will change.
 * 
The comparison method must not assume that it is called after the store
 * has been opened.  With Berkeley DB Java Edition, the comparison method is
 * called during database recovery, which occurs in the {@link Environment}
 * constructor.
 * 
The comparison method must not assume that it will only be called with
 * keys that are currently present in the database.  The comparison method will
 * occasionally be called with deleted keys or with keys for records that were
 * not part of a committed transaction.
 * 
 *
 * @author Mark Hayes
 */
@Documented @Retention(RUNTIME) @Target(FIELD)
public @interface KeyField {

    int value();
}