Constraints

The GigaMap can validate every write operation (add, set, update, …​) against a set of constraints. If any constraint is violated, a ConstraintViolationException is thrown and the operation is rolled back, so the map is never left in an invalid state.

Constraints are accessed through gigaMap.constraints(), which returns a GigaConstraints instance with two categories:

gigaMap.constraints().unique(); // UniqueConstraints<E>
gigaMap.constraints().custom(); // CustomConstraints<E>

Unique Constraints

A unique constraint ensures that the indexed value of a property is unique across all entities in the map. It is backed by a bitmap index, so adding one always implies that a corresponding bitmap index exists.

// use the builder
final GigaMap<Person> gigaMap = GigaMap.<Person>Builder()
    .withBitmapUniqueIndex(PersonIndices.id)
    ...
    .build();

// or register it after creating
GigaMap<Person> gigaMap = GigaMap.New();
gigaMap.index().bitmap().addUniqueConstraint(PersonIndices.id);

Validation Points

A unique constraint is checked when it is registered (against the entities already in the map), on every write - and again by reindex(), which rebuilds the indices from the current entity state and therefore derives every key anew. A rebuild over data that violates the constraint - two or more entities sharing a key - is reported with a UniqueConstraintViolationExceptionBitmap naming the violated index and the first entity found under an already taken key.

The report comes after the rebuild has completed: the indices are rebuilt and marked for storing either way, so they describe the entities as they actually are. That is also what the repair works on - re-distinguish the colliding keys via update / apply, then call reindex() again:

try
{
    gigaMap.reindex();
}
catch(final UniqueConstraintViolationException e)
{
    // the completed rebuild answers for the actual entity state, so the collisions are queryable
    final Person offender = (Person)e.getViolatingEntity();
    for(final Person person : gigaMap.query(PersonIndices.id.is(offender.getId())).toList())
    {
        gigaMap.update(person, p -> p.setId(...)); // assign distinct values
    }
    gigaMap.reindex(); // passes now
}
gigaMap.store();
Class evolution of an indexed unique field is the typical source of such data: renaming or retyping it across releases without a value-preserving refactoring mapping makes the legacy mapping default that field for every old entity, so they all reload carrying the same key. See CRUD - Removing and Updating Entities for reindex() itself.

Combining With an Identity Index

A unique constraint and an identity index are independent concerns: the identity index defines how entities are looked up, the unique constraint enforces uniqueness at write time. Combine both to get an identifying field that is also guaranteed unique:

// use the builder — the same indexer can be passed to both methods
final GigaMap<Person> gigaMap = GigaMap.<Person>Builder()
    .withBitmapIdentityIndex(PersonIndices.id)
    .withBitmapUniqueIndex(PersonIndices.id) // enforce uniqueness at runtime
    ...
    .build();

// or register it after creating: addUniqueConstraint creates the backing
// bitmap index, then setIdentityIndices promotes it to identity
GigaMap<Person> gigaMap = GigaMap.New();
final BitmapIndices<Person> bitmap = gigaMap.index().bitmap();
bitmap.addUniqueConstraint(PersonIndices.id); // creates index + unique constraint
bitmap.setIdentityIndices(PersonIndices.id);  // promote it to identity

Custom Constraints

Custom constraints let you express arbitrary validation logic — anything from a simple per-entity predicate to a check that consults the rest of the map.

Custom constraints are persisted with the GigaMap: when the map is stored, the registered constraint instances are written along with it and are restored when the map is loaded again.

Because of this, every constraint must be implemented as a named, top-level (or static nested) class. EclipseStore cannot persist:

  • lambdas — their synthetic class names are generated by the JVM and not stable across compilations or runs;

  • anonymous inner classes — their $1, $2, …​ names depend on the declaration order in the enclosing class.

In practice this means: only use CustomConstraint.Wrapper / CustomConstraint.WrapperSimple for short-lived, in-memory GigaMaps that you will never store. For any persisted GigaMap, write a named subclass of CustomConstraint.AbstractSimple or CustomConstraint.Abstract.

A custom constraint implements CustomConstraint<E>. There are four ready-made base types, ordered from simplest to most flexible:

Type When to use

AbstractSimple<E>

Validation depends only on the new entity itself.

Abstract<E>

Validation also needs the entityId and/or the entity being replaced. Throws the exception directly.

WrapperSimple<E>

Same as AbstractSimple but using a Predicate<E> lambda.

Wrapper<E>

Same as Abstract but using a CustomConstraint.Logic<E> lambda. Most flexible — also receives the GigaMap itself, so it can cross-check against other entities.

Adding Constraints

// use the builder
final GigaMap<Person> gigaMap = GigaMap.<Person>Builder()
    .withCustomConstraint(new NoBlankNames())
    ...
    .build();

// or register one or more after creating
gigaMap.constraints().custom().addConstraint(new NoBlankNames());
gigaMap.constraints().custom().addConstraints(constraint1, constraint2);
When a custom constraint is added to a non-empty GigaMap, it is immediately checked against every existing entity. If any current entity already violates it, the call fails with a ConstraintViolationException and the constraint is not registered.

Example: AbstractSimple

The most common case — a per-entity rule:

public class NoBlankNames extends CustomConstraint.AbstractSimple<Person>
{
    @Override
    public boolean isViolated(final Person person)
    {
        return person.getFirstName() == null || person.getFirstName().isBlank();
    }
}

Example: WrapperSimple (lambda)

Same logic, expressed as a predicate:

gigaMap.constraints().custom().addConstraint(
    new CustomConstraint.WrapperSimple<Person>(
        person -> person.getFirstName() == null || person.getFirstName().isBlank()
    )
);
The wrapped Predicate is a lambda and cannot be persisted by EclipseStore. Use this form only for in-memory GigaMaps. For persisted maps, port the logic to a named subclass of AbstractSimple (see above).

Example: Abstract

When the check needs the entity id or the replaced entity, declare a named subclass:

public class NoLevelDowngrade extends CustomConstraint.Abstract<Person>
{
    @Override
    public void check(final long entityId, final Person replaced, final Person entity)
    {
        if(replaced != null && entity.getLevel() < replaced.getLevel())
        {
            throw new ConstraintViolationException(entityId, replaced, entity);
        }
    }
}

gigaMap.constraints().custom().addConstraint(new NoLevelDowngrade());
For persisted GigaMaps, prefer named classes over the new CustomConstraint.Abstract<>() { …​ } anonymous-class shorthand. Anonymous-inner-class names (…​$1, …​$2) depend on declaration order in the enclosing class and are fragile across refactors.

Example: Wrapper (full Logic lambda)

When the check needs to consult the rest of the map:

final CustomConstraint.Wrapper<Person> singleAdmin = new CustomConstraint.Wrapper<>(
    (map, entityId, replaced, entity, createException) ->
    {
        if(!entity.isAdmin())
        {
            return null;
        }
        final long admins = map.query(PersonIndices.admin.is(true)).count();
        if(admins == 0 || (replaced != null && replaced.isAdmin()))
        {
            return null;
        }
        return createException
            ? new ConstraintViolationException(entityId, replaced, entity)
            : org.eclipse.serializer.util.X.BREAK();
    }
);
gigaMap.constraints().custom().addConstraint(singleAdmin);
The wrapped Logic is a lambda and cannot be persisted by EclipseStore. Use this form only for in-memory GigaMaps. For persisted maps, port the logic to a named subclass of Abstract (see above) — the check method has access to the same entityId and replaced parameters; if you also need the surrounding GigaMap, implement CustomConstraint<E> directly.

Constraint Names

Each CustomConstraint has a name() used as its registry key — duplicate names are rejected with an IllegalArgumentException. The default name() in AbstractBase returns the simple class name, which is sufficient for named subclasses (the recommended form, see the persistence note above). Anonymous subclasses fall back to an empty simple name, so registering more than one without overriding name() will fail.

Constraint Violations

All violations are signalled by ConstraintViolationException (or its subclass UniqueConstraintViolationException for unique-index violations). The exception carries:

  • entityId — the id of the offending entity

  • replacedEntity — the previous entity for set / update, null for add

  • violatingEntity — the entity that triggered the violation

What happens to the map on violation depends on the operation:

Operation Effect on the map

add / addAll

The map is unchanged. For batch operations none of the entities in the batch are added.

set / replace

The map is unchanged. Constraints are checked before the entry is mutated, so the previous entity stays in place.

update / apply

The offending entity is removed from the map. The provided logic mutates the entity in place, so a constraint failure cannot be rolled back to the previous state — the only consistent option is to drop the entry. The removed entity and its id are carried by the ConstraintViolationException (violatingEntity, entityId), so the caller can recover or re-add it after fixing the violation.

Only a constraint violation removes the entity — a constraint is what decides whether an entity may exist at all. A failure of an index does not: if an indexer throws for the new value, or an index implementation rejects it (e.g. a Lucene term over its length limit, an embedding of the wrong dimension, or a stale index), the entity is kept and the exception is rethrown. The indices may then be out of sync with the retained entity; rebuild them with reindex(). A custom constraint that signals a violation by throwing something other than a ConstraintViolationException is treated like an index failure, i.e. non-destructively.