001/*
002 * PermissionsEx
003 * Copyright (C) zml and PermissionsEx contributors
004 *
005 * Licensed under the Apache License, Version 2.0 (the "License");
006 * you may not use this file except in compliance with the License.
007 * You may obtain a copy of the License at
008 *
009 *    http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package ca.stellardrift.permissionsex.context;
018
019import org.checkerframework.checker.nullness.qual.Nullable;
020
021import java.util.Collections;
022import java.util.List;
023import java.util.Set;
024import java.util.concurrent.CompletableFuture;
025
026/**
027 * A repository of context types.
028 *
029 * @since 2.0.0
030 */
031public interface ContextDefinitionProvider {
032    Set<ContextValue<?>> GLOBAL_CONTEXT = Collections.emptySet();
033
034    CompletableFuture<Set<ContextDefinition<?>>> usedContextTypes(); // TODO: part of PermissionsEngine instead?
035
036    /**
037     * Register a new context type that can be queried. If there is another context type registered with the same key
038     * as the one trying to be registered, the registration will fail.
039     *
040     * @param contextDefinition The new context type
041     * @param <T>               The context value type
042     * @return whether the context was successfully registered
043     */
044    <T> boolean registerContextDefinition(ContextDefinition<T> contextDefinition);
045
046    /**
047     * Register multiple context definitions.
048     *
049     * @param definitions The definitions to register
050     * @return The number of definitions that were successfully registered
051     * @see #registerContextDefinition for details on how individual registrations occur
052     */
053    int registerContextDefinitions(ContextDefinition<?>... definitions);
054
055    /**
056     * Get an immutable copy as a list of the registered context types
057     *
058     * @return The registered context types
059     */
060    List<ContextDefinition<?>> registeredContextTypes();
061
062    default @Nullable ContextDefinition<?> contextDefinition(final String definitionKey) {
063        return contextDefinition(definitionKey, false);
064    }
065
066    @Nullable ContextDefinition<?> contextDefinition(String definitionKey, boolean allowFallbacks);
067}