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