Package net.luckperms.api.context

Interface ContextCalculator<T>

All Known Subinterfaces:
StaticContextCalculator
Functional Interface:
This is a functional interface and can therefore be used as the assignment target for a lambda expression or method reference.
@FunctionalInterface public interface ContextCalculator<T>
Calculates the contexts applicable for a contextual subject.

Implementations of this interface should satisfy the following requirements:

  • Context lookups should be fast: lookup methods are likely to be invoked frequently, and should therefore be fast to execute. If determining the current contexts involves a particularly time consuming lookup (database queries, network requests, etc), then such results should be cached ahead of time.
  • Context lookups should be thread-safe: lookups will sometimes be performed from "async" threads, and therefore should not access any part of the server only safe for access from a sync context. If necessary, such results should be determined ahead of time and stored in a thread-safe collection for retrieval later.
  • Context lookups should not query active contexts: doing so is likely to result in a stack overflow, or thread deadlock. Care should be taken to avoid (indirect) calls to the same calculator.

Calculators should be registered using ContextManager.registerCalculator(ContextCalculator).

  • Method Details

    • forSingleContext

      static <T> @NonNull ContextCalculator<T> forSingleContext(@NonNull String key, @NonNull Function<T,String> valueFunction)
      Creates a new ContextCalculator that provides a single context.
      Type Parameters:
      T - the contextual type
      Parameters:
      key - the key of the context provided by the calculator
      valueFunction - the function used to compute the corresponding value for each query. A context will not be "accumulated" if the value returned is null.
      Returns:
      the resultant calculator

    • calculate

      void calculate(@NonNull T target, @NonNull ContextConsumer consumer)
      Submits any contexts this calculator determines to be applicable to the target contextual subject.

      Care should be taken to ensure implementations of this method meet the general requirements for ContextCalculator, defined in the class doc.

      Parameters:
      target - the target contextual subject for this operation
      consumer - the ContextConsumer to submit contexts to

    • estimatePotentialContexts

      default @NonNull ContextSet estimatePotentialContexts()
      Gets a ContextSet, containing some/all of the contexts this calculator could potentially submit.

      The result of this call is primarily intended on providing suggestions to end users when defining permissions.

      Returns:
      a set of potential contexts