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.datastore;
018
019import ca.stellardrift.permissionsex.PermissionsEngine;
020import ca.stellardrift.permissionsex.logging.FormattedLogger;
021import ca.stellardrift.permissionsex.subject.SubjectRef;
022import ca.stellardrift.permissionsex.subject.SubjectType;
023import org.checkerframework.checker.nullness.qual.Nullable;
024
025import javax.sql.DataSource;
026import java.nio.file.Path;
027import java.sql.SQLException;
028import java.util.Map;
029import java.util.concurrent.Executor;
030
031/**
032 * Access to internals exposed for data store use only.
033 *
034 * @since 2.0.0
035 */
036public interface DataStoreContext {
037
038    /**
039     * Get the permissions engine this context is attached to.
040     *
041     * @return the engine
042     */
043    PermissionsEngine engine();
044
045    /**
046     * A logger for logging any necessary messages.
047     *
048     * @return the logger
049     */
050    FormattedLogger logger();
051
052    /**
053     * Get the base data directory where the engine will store data and configuration.
054     *
055     * @return the base data directory
056     * @since 2.0.0
057     */
058    Path baseDirectory();
059
060    /**
061     * Access the engine's async executor that can be used to schedule tasks
062     *
063     * @return the executor
064     * @since 2.0.0
065     */
066    Executor asyncExecutor();
067
068    SubjectType<SubjectType<?>> defaultsType();
069
070    SubjectType<SubjectType<?>> fallbacksType();
071
072    /**
073     * Deserialize a subject reference given a type and identifier.
074     *
075     * @param pair the subject type to identifier pair
076     * @return a resolved subject ref
077     */
078    default SubjectRef<?> deserializeSubjectRef(final Map.Entry<String, String> pair) {
079        return this.deserializeSubjectRef(pair.getKey(), pair.getValue());
080    }
081
082    /**
083     * Deserialize a subject reference given a type and identifier.
084     *
085     * @param type the subject type
086     * @param identifier the subject identifier
087     * @return a resolved subject ref
088     */
089    SubjectRef<?> deserializeSubjectRef(final String type, final String identifier);
090
091    /**
092     * Create a subject ref that will only be resolved once data is queried.
093     *
094     * @param type the subject type
095     * @param identifier the identifier
096     * @return a lazy subject reference
097     */
098    SubjectRef<?> lazySubjectRef(final String type, final String identifier);
099
100    /**
101     * Temporary -- create a pooled SQL datasource for a certain URL.
102     *
103     * @param url the URL to query
104     * @return a valid data source
105     * @throws SQLException if the connection is invalid
106     * @since 2.0.0
107     * @deprecated need to find a better place to put this
108     */
109    @Deprecated
110    @Nullable DataSource dataSourceForUrl(String url) throws SQLException;
111}