Package io.permazen.annotation

Annotation Interface PermazenCompositeIndex

@Repeatable(PermazenCompositeIndexes.class) @Retention(RUNTIME) @Target({ANNOTATION_TYPE,TYPE}) @Documented public @interface PermazenCompositeIndex
Java annotation that defines a composite index.

A composite index is an index on two or more fields (to define a single-field index, see PermazenField.indexed()). All fields participating in a composite index must be (a) simple and (b) not a sub-field of a complex field.

The class or interface does not have to be @PermazenType-annotated; annotations are "inherited" and so apply to all @PermazenType-annotated sub-types.

@PermazenCompositeIndex is a repeatable annotation.

Uniqueness Constraints

Uniqueness constraints are supported, and their enforcement is handled in the same way as for uniqueness constraints on simply indexed fields (see @PermazenField.unique()). A uniqueness constriant on a composite index means each combination of field values must be unique to a single object. Specific field value combinations may be excluded from the uniqueness constraint by specifying the corresponding comma-separated String-encoded tuples in uniqueExcludes().
See Also:

  • Required Element Summary

    Required Elements
    Modifier and Type
    Required Element
    Description
    String[]
    fields
    The names of the indexed fields, in the desired order.
    String
    name
    The name of this index.

  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    int
    storageId
    Storage ID for this index.
    boolean
    unique
    Require each object's field combination to be unique among all types to which this annotation applies.
    ValuesList[]
    uniqueExcludes
    Specify field value combinations to be excluded from the uniqueness constraint.

  • Element Details

    • name

      String name
      The name of this index.

      The name must be unique among all other indexes and simple fields in a Java model type.

      Returns:
      the index name

    • fields

      String[] fields
      The names of the indexed fields, in the desired order. At least two fields must be specified.
      Returns:
      the names of the indexed fields

    • storageId

      int storageId
      Storage ID for this index.

      Normally this value is left as zero, in which case a value will be automatically assigned.

      Otherwise, the value should be positive and unique within the schema.

      Returns:
      this index's storage ID, or zero for automatic assignment
      Default:
      0

    • unique

      boolean unique
      Require each object's field combination to be unique among all types to which this annotation applies.

      This property creates an implicit uniqueness validation constraint.

      The constraint will be checked any time normal validation is performed on an object. More precisely, a uniqueness constraint behaves like a JSR 303 validation constraint with groups() = { Default.class, UniquenessConstraints.class }. Therefore, uniqueness constraints are included in default validation, but you can also validate only uniqueness constraints via myobj.revalidate(UniquenessConstraints.class).

      Returns:
      whether the composite index's field values should be unique
      See Also:
      Default:
      false

    • uniqueExcludes

      ValuesList[] uniqueExcludes
      Specify field value combinations to be excluded from the uniqueness constraint.

      The annotation value is a list of @ValuesList annotations, each of which describes some combination of field values that should grant the containing object exclusion from the uniqueness constraint.

      Each @ValuesList contains a list of @Values annotations, one for each field in the index. For an object to be excluded from the uniqueness constraint, the object's fields' values must all match their corresponding @Values annotation in at least one of the @ValuesList annotations.

      For example, consider this class: 

        public abstract class Person {

      public abstract String getName();
      public abstract void setName(String x);

      public abstract int getId();
      public abstract void setId(int x);
  }

      To require a Person's name and ID combination to be unique, but exclude Person's whose name is null and whose ID is equal to -1 or -2: 

       @PermazenType(compositeIndexes =
  @PermazenCompositeIndex(name = "nameAndId", fields = { "name", "id" },
      unique = true,
      uniqueExcludes = @ValuesList({ @Values(nulls = true), @Values({ "-1", "-2" }) })
  ))))
  public abstract class Person {
      ...
  }

      To require a Person's name and ID combination to be unique, but exclude Person's whose name is null or whose ID is equal to -1 or -2: 

       @PermazenType(compositeIndexes =
  @PermazenCompositeIndex(name = "nameAndId", fields = { "name", "id" },
      unique = true,
      uniqueExcludes = {
          @ValuesList({ @Values(nulls = true), @Values(nonNulls = true) }),
          @ValuesList({ @Values(nulls = true, nonNulls = true), @Values({ "-1", "-2" }) })
  }))))
  public abstract class Person {
      ...
  }

      Notes:

      • To match all possible values for a field, use @Values(nulls = true, nonNulls = true)
      • For primitive fields, @Values.nulls() is not relevant.

      It is an error if, for any @ValuesList, every possible field combination would match, as this would pointlessly exclude every object.

      This property must be left empty when unique() is false.

      Returns:
      field value combinations to exclude from the uniqueness constraint
      See Also:
      Default:
      {}