me.lucko.luckperms.api.context.ContextManager Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of luckperms-api Show documentation
An advanced permissions plugin for Bukkit/Spigot, BungeeCord, Sponge, Nukkit and Velocity.
The newest version!
/*
 * This file is part of LuckPerms, licensed under the MIT License.
 *
 *  Copyright (c) lucko (Luck) 
 *  Copyright (c) contributors
 *
 *  Permission is hereby granted, free of charge, to any person obtaining a copy
 *  of this software and associated documentation files (the "Software"), to deal
 *  in the Software without restriction, including without limitation the rights
 *  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 *  copies of the Software, and to permit persons to whom the Software is
 *  furnished to do so, subject to the following conditions:
 *
 *  The above copyright notice and this permission notice shall be included in all
 *  copies or substantial portions of the Software.
 *
 *  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 *  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 *  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 *  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 *  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 *  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 *  SOFTWARE.
 */

package me.lucko.luckperms.api.context;

import me.lucko.luckperms.api.Contexts;
import me.lucko.luckperms.api.User;

import org.checkerframework.checker.nullness.qual.NonNull;

import java.util.Optional;

/**
 * Manages {@link ContextCalculator}s, and calculates applicable contexts for a
 * given type.
 *
 * This interface accepts {@link Object} types as a parameter to avoid having to depend
 * on specific server implementations. In all cases, the "player" or "subject" type for
 * the platform must be used.
 *
 * Specifically:
 *
 * 
 * 
 * {@code org.bukkit.entity.Player}
 * {@code net.md_5.bungee.api.connection.ProxiedPlayer}
 * {@code org.spongepowered.api.service.permission.Subject}
 * {@code cn.nukkit.Player}
 * {@code com.velocitypowered.api.proxy.Player}
 * 
 *
 * @since 4.0
 */
public interface ContextManager {

    /**
     * Queries the ContextManager for current context values for the subject.
     *
     * @param subject the subject
     * @return the applicable context for the subject
     */
    @NonNull ImmutableContextSet getApplicableContext(@NonNull Object subject);

    /**
     * Queries the ContextManager for current context values for the subject.
     *
     * @param subject the subject
     * @return the applicable context for the subject
     */
    @NonNull Contexts getApplicableContexts(@NonNull Object subject);

    /**
     * Queries the ContextManager for current context values for the given User.
     *
     * This will only return a value if the player corresponding to the
     * {@link User} is online.
     *
     * If you need to be a {@link Contexts} instance regardless, you should
     * initially try this method, and then fallback on {@link #getStaticContext()}.
     *
     * @param user the user
     * @return the applicable context for the subject
     */
    @NonNull Optional lookupApplicableContext(@NonNull User user);

    /**
     * Queries the ContextManager for current context values for the given User.
     *
     * This will only return a value if the player corresponding to the
     * {@link User} is online.
     *
     * If you need to be a {@link Contexts} instance regardless, you should
     * initially try this method, and then fallback on {@link #getStaticContexts()}.
     *
     * @param user the user
     * @return the applicable context for the subject
     */
    @NonNull Optional lookupApplicableContexts(@NonNull User user);

    /**
     * Gets the contexts from the static calculators in this manager.
     *
     * Static calculators provide the same context for all subjects, and are
     * marked as such when registered.
     *
     * @return the current active static contexts
     */
    @NonNull ImmutableContextSet getStaticContext();

    /**
     * Gets the contexts from the static calculators in this manager.
     *
     * Static calculators provide the same context for all subjects, and are
     * marked as such when registered.
     *
     * @return the current active static contexts
     */
    @NonNull Contexts getStaticContexts();

    /**
     * Forms a {@link Contexts} instance from an {@link ImmutableContextSet}.
     *
     * This method relies on the plugins configuration to form the
     * {@link Contexts} instance.
     *
     * @param subject    the reference subject
     * @param contextSet the context set
     * @return a contexts instance
     */
    @NonNull Contexts formContexts(@NonNull Object subject, @NonNull ImmutableContextSet contextSet);

    /**
     * Forms a {@link Contexts} instance from an {@link ImmutableContextSet}.
     *
     * This method relies on the plugins configuration to form the
     * {@link Contexts} instance.
     *
     * @param contextSet the context set
     * @return a contexts instance
     */
    @NonNull Contexts formContexts(@NonNull ImmutableContextSet contextSet);

    /**
     * Registers a context calculator with the manager.
     *
     * @param calculator the calculator
     */
    void registerCalculator(@NonNull ContextCalculator calculator);

    /**
     * Unregisters a context calculator with the manager.
     *
     * @param calculator the calculator
     * @since 4.4
     */
    void unregisterCalculator(@NonNull ContextCalculator calculator);

    /**
     * Invalidates the lookup cache for a given subject
     *
     * @param subject the subject
     */
    void invalidateCache(@NonNull Object subject);

}