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.subject;
018
019import java.util.Collection;
020import java.util.concurrent.CompletableFuture;
021import java.util.stream.Stream;
022
023/**
024 * Collection providing a view of subjects of a given type within the PEX engine.
025 *
026 * @param <I> subject identifier type
027 * @since 2.0.0
028 */
029public interface SubjectTypeCollection<I> {
030
031    /**
032     * Set information configuring resolution for this subject type.
033     *
034     * @return the active type information
035     * @since 2.0.0
036     */
037    SubjectType<I> type();
038
039    /**
040     * Request that all subjects of this type be loaded into the cache.
041     *
042     * <p>Be aware that on larger collections this may be a very expensive operation.</p>
043     *
044     * @since 2.0.0
045     */
046    void cacheAll();
047
048    /**
049     * Get an unmodifiable view of the calculated subjects currently active in this data store.
050     *
051     * <p>This view may update at any time.</p>
052     *
053     * @return An unmodifiable view of the subjects
054     * @since 2.0.0
055     */
056    Collection<CalculatedSubject> activeSubjects();
057
058    /**
059     * Request that a given identifier be removed from the cached data stores.
060     *
061     * @param identifier The subject identifier to uncache.
062     * @since 2.0.0
063     */
064    void uncache(I identifier);
065
066    /**
067     * Get the calculated subject data for a given subject.
068     *
069     * <p>The returned data allows querying subject data taking into account both persistent and
070     * transient data, inheritance, context priorities and inheritance, and any factors that may be
071     * implemented in the future.</p>
072     *
073     * @param identifier The identifier of the subject to get
074     * @return A future providing the calculated subject
075     * @throws IllegalArgumentException if the given identifier is not valid for this subject type
076     * @since 2.0.0
077     */
078    CompletableFuture<CalculatedSubject> get(I identifier);
079
080    /**
081     * Access the transient data for subjects of this type.
082     *
083     * <p>Operations on these data objects will only be stored in memory.
084     * If {@link SubjectType#transientHasPriority()} is true, data set here will override the
085     * persistent data for subjects in this collection.</p>
086     *
087     * @return The transient data cache
088     * @since 2.0.0
089     */
090    SubjectDataCache<I> transientData();
091
092    /**
093     * Access the persistent data for subjects of this type
094     *
095     * @return The persistent data cache
096     * @since 2.0.0
097     */
098    SubjectDataCache<I> persistentData();
099
100    /**
101     * Request that a subject of a given identifier is loaded into the cache. This operation completes asynchronously.
102     *
103     * @param identifier The identifier of the subject being loaded.
104     * @since 2.0.0
105     */
106    void load(I identifier);
107
108    /**
109     * Query the backing data stores to see if a given subject is registered
110     *
111     * @param identifier The identifier of the subject to query
112     * @return A future returning whether or not this subject has data registered
113     * @since 2.0.0
114     */
115    CompletableFuture<Boolean> isRegistered(I identifier);
116
117    /**
118     * Get a set of subject identifiers for every subject registered of this type.
119     *
120     * @return All subject identifiers
121     * @since 2.0.0
122     */
123    Stream<I> allIdentifiers();
124}