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 Detail

      • 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

      • 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

      • 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

      • 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

        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