org.spongepowered.api.service.context

Interface ContextCalculator<T extends Contextual>

public interface ContextCalculator<T extends Contextual>

Calculates the Contexts applicable for a Contextual.

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 Contextual.getActiveContexts().

Calculators should be registered with the corresponding ContextualService using ContextualService.registerContextCalculator(ContextCalculator).

Context lookups for instances provided by the platform, (e.g. Player) are delegated to the active PermissionService. Plugins wishing to provide contexts for these instances should register calculators here.

When the provider of a ContextualService changes, calculators must be registered again. Plugins should listen to the ChangeServiceProviderEvent to ensure their calculators are registered with any replacement providers.

Method Summary

Modifier and Type	Method and Description
void	accumulateContexts(T target, Set<Context> accumulator) Adds any Contexts this calculator determines to be applicable to the target contextual.
static <T extends Contextual> ContextCalculator<T>	forSingleContext(String key, Function<T,String> valueFunction) Creates a new ContextCalculator that provides a single context.
default boolean	matches(Context context, T target) Checks if a Context is currently applicable to a Contextual.

Method Detail

forSingleContext

static <T extends Contextual> ContextCalculator<T> forSingleContext(String key,
                                                                    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

accumulateContexts

void accumulateContexts(T target,
                        Set<Context> accumulator)

Adds any Contexts this calculator determines to be applicable to the target contextual.

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

Calculators should not rely on the state of accumulator during this call, and also shouldn't make calls to remove contexts added by other calculators.

Parameters:

target - the target Contextual for this operation

accumulator - a Set of Contexts this operation will accumulate to.

matches

default boolean matches(Context context,
                        T target)

Checks if a Context is currently applicable to a Contextual.

If this calculator does not handle the given type of context, this method should return false.

For the given set of contexts which would be accumulated using accumulateContexts(Contextual, Set), this method should return true if the given context would be included in the accumulated set.

Parameters:

context - the Context being checked

target - the Contextual that is being checked against

Returns:

True if the given Context is handled by this calculator and is applicable to the given Contextual. Otherwise false.