Package net.luckperms.api.context

Interface ContextSet

All Superinterfaces:
Iterable<Context>
All Known Subinterfaces:
ImmutableContextSet, MutableContextSet
public interface ContextSet extends Iterable<Context>
A set of contexts.

Context in the most basic sense simply means the circumstances where something will apply.

A single "context" consists of a key and a value, both strings. The key describes the type of the context, and the value represents what the key is set to.

For example, a context with key=world and value=world_nether describes that a subject is in the "world_nether" world.

Contexts are exposed to end users and manipulated when managing permissions. For this reason, context keys should strike a balance between being descriptive and succinct.

Context keys and values are case-insensitive, and will be automatically converted to lowercase when added to a context set. Keys and values cannot be null or empty (len=0 or consisting of only whitespace).

If a context key is formed of more than one word, the parts should be separated by the '-' character. (e.g. "server-type")

If a context key is likely to conflict with another plugin, it should be appropriately namespaced using the name of the plugin providing the context. The namespace should be at the start of the context key, and separated using the ':' character. (e.g. "worldguard:region" for WorldGuard regions)

Contexts can be combined with each other to form so called "context sets" - simply a collection of context pairs.

Two default ContextSet implementations are provided. MutableContextSet allows the addition and removal of context keys after construction, and ImmutableContextSet does not.

  • Method Details

    • isImmutable

      boolean isImmutable()
      Gets if this ContextSet is immutable.

      The state of immutable instances will never change.

      Returns:
      true if the set is immutable

    • immutableCopy

      @NonNull ImmutableContextSet immutableCopy()
      Returns an immutable representation of this ContextSet.

      If the set is already immutable, the same object will be returned. If the set is mutable, an immutable copy will be made.

      Returns:
      an immutable representation of this set

    • mutableCopy

      @NonNull MutableContextSet mutableCopy()
      Creates a mutable copy of this ContextSet.

      A new copy is returned regardless of the mutability of this set.

      Returns:
      a mutable ContextSet

    • toSet

      @NonNull @Unmodifiable Set<Context> toSet()
      Returns a Set of Contexts representing the current state of this ContextSet.

      The returned set is immutable, and is a copy of the current set. (will not update live)

      Returns:
      an immutable set

    • toMap

      @NonNull @Unmodifiable Map<String,Set<String>> toMap()
      Returns a Map representing the current state of this ContextSet.

      The returned set is immutable, and is a copy of the current set. (will not update live)

      Returns:
      a map

    • toFlattenedMap

      @Deprecated @NonNull @Unmodifiable Map<String,String> toFlattenedMap()
      Deprecated.
      Deprecated because the returned map may not contain all data in the ContextSet
      Returns a Map loosely representing the current state of this ContextSet.

      The returned map is immutable, and is a copy of the current set. (will not update live)

      As a single context key can be mapped to multiple values, this method may not be a true representation of the set.

      Returns:
      an immutable map

    • iterator

      @NonNull @Unmodifiable Iterator<Context> iterator()
      Returns an Iterator over each of the context pairs in this set.

      The returned iterator represents the state of the set at the time of creation. It is not updated as the set changes.

      The iterator does not support Iterator.remove() calls.

      Specified by:
      iterator in interface Iterable<Context>
      Returns:
      an iterator

    • containsKey

      boolean containsKey(@NonNull String key)
      Returns if the ContextSet contains at least one value for the given key.
      Parameters:
      key - the key to check for
      Returns:
      true if the set contains a value for the key
      Throws:
      NullPointerException - if the key is null

    • getValues

      @NonNull @Unmodifiable Set<String> getValues(@NonNull String key)
      Returns a Set of the values mapped to the given key.

      The returned set is immutable, and only represents the current state of the ContextSet. (will not update live)

      Parameters:
      key - the key to get values for
      Returns:
      a set of values
      Throws:
      NullPointerException - if the key is null

    • getAnyValue

      default @NonNull Optional<String> getAnyValue(@NonNull String key)
      Returns any value from this ContextSet matching the key, if present.

      Note that context keys can be mapped to multiple values. Use getValues(String) to retrieve all associated values.

      Parameters:
      key - the key to find values for
      Returns:
      an optional containing any match

    • contains

      boolean contains(@NonNull String key, @NonNull String value)
      Returns if the ContextSet contains a given context pairing.
      Parameters:
      key - the key to look for
      value - the value to look for
      Returns:
      true if the set contains the context pair
      Throws:
      NullPointerException - if the key or value is null

    • contains

      default boolean contains(@NonNull Context entry)
      Returns if the ContextSet contains a given context pairing.
      Parameters:
      entry - the entry to look for
      Returns:
      true if the set contains the context pair
      Throws:
      NullPointerException - if the key or value is null

    • containsAny

      default boolean containsAny(@NonNull String key, @NonNull Iterable<String> values)
      Returns if the ContextSet contains any of the given context pairings.
      Parameters:
      key - the key to look for
      values - the values to look for
      Returns:
      true if the set contains any of the pairs
      Since:
      5.2

    • isSatisfiedBy

      default boolean isSatisfiedBy(@NonNull ContextSet other)
      Returns if this ContextSet is "satisfied" by another set.

      ContextSatisfyMode.AT_LEAST_ONE_VALUE_PER_KEY is the mode used by this method.

      Parameters:
      other - the other set
      Returns:
      true if this context set is satisfied by the other

    • isSatisfiedBy

      boolean isSatisfiedBy(@NonNull ContextSet other, @NonNull ContextSatisfyMode mode)
      Returns if this ContextSet is "satisfied" by another set, according to the given mode.
      Parameters:
      other - the other set
      mode - the mode to use
      Returns:
      true if this context set is satisfied by the other
      Since:
      5.2

    • isEmpty

      boolean isEmpty()
      Returns if the ContextSet is empty.
      Returns:
      true if the set is empty

    • size

      int size()
      Gets the number of context pairs in the ContextSet.
      Returns:
      the size of the set