org.spongepowered.api.service.permission.SubjectData Maven / Gradle / Ivy
Show all versions of spongeapi Show documentation
/*
* This file is part of SpongeAPI, licensed under the MIT License (MIT).
*
* Copyright (c) SpongePowered
* 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 org.spongepowered.api.service.permission;
import org.checkerframework.checker.nullness.qual.Nullable;
import org.spongepowered.api.service.context.Context;
import org.spongepowered.api.util.Tristate;
import java.util.Collections;
import java.util.List;
import java.util.Map;
import java.util.Set;
import java.util.concurrent.CompletableFuture;
/**
* Container for a subject's data.
*
* This container updates live, and provides raw data for a subject not
* taking into account any sort of inheritance. This interface is meant to
* represent what's 'in the file', rather than the higher-level query methods
* available in {@link Subject}.
*
* Methods which modify the state of the data return
* {@link CompletableFuture}s. This allows for the time which is taken to apply
* and persist the change to the implementations storage backend. These futures
* should return quickly for changes made to transient subject data, but may
* take longer to return for changes made to a subjects persistent data. Methods
* which use this data in {@link Subject} may not reflect the change until the
* future has returned.
*
* {@link CompletableFuture#allOf(CompletableFuture[])} can be used to
* combine multiple futures into one, if the result of methods is not
* needed.
*/
public interface SubjectData {
/**
* A convenience constant for the global context combination (the empty
* set), if you want your code to look especially fancy.
*/
Set GLOBAL_CONTEXT = Collections.emptySet();
/**
* Gets the {@link Subject} which holds this data.
*
* @return The subject which holds this data
*/
Subject subject();
/**
* Return if this SubjectData is transient.
*
* @return If this SubjectData is transient
* @see Subject#transientSubjectData()
*/
boolean isTransient();
/**
* Return all permissions associated with this data object.
*
* @return An immutable copy of the mappings between contexts and lists of
* permissions containing every permission registered
*/
Map, Map> allPermissions();
/**
* Returns the list of permissions set for the given context.
*
* This list is immutable and is not a live view. If no permissions have
* been set, it returns an empty list.
*
* @param contexts The particular context combination to check
* @return Any permissions set
*/
Map permissions(Set contexts);
/**
* Sets a permission to a given value.
*
* Setting value as {@link Tristate#UNDEFINED} unsets the permission.
*
* An empty set of contexts applies this permission to the global
* context.
*
* @param contexts The particular combination of contexts to set this
* permission in
* @param permission The permission to set
* @param value The value to set this permission to
* @return Whether the operation was successful
*/
CompletableFuture setPermission(Set contexts, String permission, Tristate value);
/**
* Sets permissions in a given context combination.
*
* An empty set of contexts applies these permissions to the global
* context.
*
* Depending on the {@link TransferMethod} chosen, this will either
* replace all existing options or add to the existing options.
*
* @param contexts The particular combination of contexts to set these
* permissions in
* @param permissions The permissions to set
* @param method How to treat existing values in this subject
* @return Whether the operation was successful
*/
CompletableFuture setPermissions(Set contexts, Map permissions, TransferMethod method);
/**
* Get the permission value that will be returned if no more specific permission setting matches.
*
* @param contexts The context combination to set this permission in.
* @return The tristate
*/
Tristate fallbackPermissionValue(Set contexts);
/**
* Get all fallback permission values set on this subject data
*
* @return An immutable map from context combination to fallback value
*/
Map, Tristate> allFallbackPermissionValues();
/**
* Set the permission value at the root of the node tree, that will be returned as a response
* to permissions queries when no more specific permission matches.
*
* @param contexts The context combination
* @param fallback The new fallback value. {@link Tristate#UNDEFINED} unsets the fallback value.
* @return A future completing when the change has been applied
*/
CompletableFuture setFallbackPermissionValue(Set contexts, Tristate fallback);
/**
* Clear all fallback permission values from this subject
* @return A future completing when the change has been applied
*/
CompletableFuture clearFallbackPermissionValues();
/**
* Clear all permissions set in any context.
*
* @return Whether any change occurred
*/
CompletableFuture clearPermissions();
/**
* Clear all permissions set in a given context combination.
*
* Passing an empty context set clears permissions in the global
* context.
*
* @param contexts The context combination to clear permissions in
* @return Whether any change occurred
*/
CompletableFuture clearPermissions(Set contexts);
/**
* Return all registered parent subjects for all contexts.
*
* The returned map is immutable and not a live view. The results of this
* method do not traverse any sort of inheritance structure a permissions
* plugin may implement.
*
* @return All registered parents and the context they are registered in
*/
Map, ? extends List> allParents();
/**
* Return all registered parent subjects for a given context.
*
* The returned list is immutable and not a live view. The results of this
* method do not traverse any sort of inheritance structure a permissions
* plugin may implement.
*
* @param contexts The context to check
* @return names of parents valid in the given context
*/
List parents(Set contexts);
/**
* Sets the parents in a particular context combination.
*
* Passing an empty context combination means the parents are set in the
* global context.
*
* Depending on the {@link TransferMethod} chosen, this will either
* replace all existing options or add to the existing options.
*
* @param contexts The context combination this operation is applicable to
* @param parents A list of the parents this subject should have
* @return Whether the operation was successful
*/
CompletableFuture setParents(Set contexts, List parents, TransferMethod method);
/**
* Adds a parent in a particular context combination.
*
* Passing an empty context combination means the parent is added in the
* global context.
*
* @param contexts The context combination this operation is applicable to
* @param parent The name of the parent to add
* @return Whether the operation was successful
*/
CompletableFuture addParent(Set contexts, SubjectReference parent);
/**
* Removes a parent in a particular context combination.
*
* Passing an empty context combination means the parent is removed in
* the global context.
*
* @param contexts The context combination this operation is applicable to
* @param parent The name of the parent to remove
* @return Whether the operation was successful
*/
CompletableFuture removeParent(Set contexts, SubjectReference parent);
/**
* Remove all parents in any context combination.
*
* @return Whether any change occurred
*/
CompletableFuture clearParents();
/**
* Remove all parents in a given context combination.
*
* Passing an empty context set clears parents in the global
* context.
*
* @param contexts The context combination to clear the parents of
* @return Whether any change occurred
*/
CompletableFuture clearParents(Set contexts);
/**
* Return all options for all context combinations currently registered.
*
* @return An immutable snapshot of all options data
*/
Map, Map> allOptions();
/**
* Gets options for a specific context combination.
*
* @param contexts The context combination to get options for
* @return All available options, returning an empty map if none are present
*/
Map options(Set contexts);
/**
* Sets a specific option to a value.
*
* Passing a null value will unset the option.
*
* @param contexts The context combination to set the given option in
* @param key The key to set. Case-insensitive.
* @param value The value to set.
* @return Whether the operation was successful
*/
CompletableFuture setOption(Set contexts, String key, @Nullable String value);
/**
* Sets all options in a particular context.
*
* Depending on the {@link TransferMethod} chosen, this will either
* replace all existing options or add to the existing options.
*
* @param contexts The context combination to set the options in
* @param options The map of options to set
* @return Whether the operation was successful
*/
CompletableFuture setOptions(Set contexts, Map options, TransferMethod method);
/**
* Clear all options.
*
* @return Whether the operation was successful
*/
CompletableFuture clearOptions();
/**
* Clear all options in the given context combination.
*
* Passing an empty context set clears options in the global
* context.
*
* @param contexts The context combination
* @return Whether the operation was successful (any options were removed)
*/
CompletableFuture clearOptions(Set contexts);
/**
* Copy all data from another subject data instance into this one, preserving the original subject.
* It is expected that the other subject data is provided by the same permissions service.
* This methods's behaviour is undefined otherwise.
*
* @param other The other subject to copy data from
* @param method How to treat existing values in this subject
* @return A future completing with {@code true} if the operation is successful
*/
CompletableFuture copyFrom(SubjectData other, TransferMethod method);
/**
* Move all data from another subject data instance into this one, clearing the source
* It is expected that the other subject data is provided by the same permissions service.
* This methods's behaviour is undefined otherwise.
*
* @param other The other subject to move data from
* @param method How to treat existing values in this subject
* @return A future completing with {@code true} if the operation is successful
*/
CompletableFuture moveFrom(SubjectData other, TransferMethod method);
}