Expose TemporaryMergeBehaviour in the API (#1189)

2018-09-05 11:11:45 +01:00
parent 8d79ec6b07
commit 9e769904bf
12 changed files with 271 additions and 132 deletions
@@ -475,6 +475,31 @@ public interface PermissionHolder {
    @Nonnull
    DataMutateResult setPermission(@Nonnull Node node);

+    /**
+     * Sets a permission node for the permission holder.
+     *
+     * <p>Although this method is named setPermission, it can be used for all node types.</p>
+     *
+     * <p>The effect of this mutate operation will not persist in storage unless changes are
+     * explicitly saved. If changes are not saved, the effect will only be observed until the next
+     * time the holders permission data is (re)loaded. Changes to {@link User}s should be saved
+     * using {@link UserManager#saveUser(User)}, and changes to {@link Group}s should be saved
+     * using {@link GroupManager#saveGroup(Group)}.</p>
+     *
+     * <p>Before making changes to a user or group, it may be a good idea to load a fresh copy of
+     * the backing data from the storage if you haven't done so already, to avoid overwriting changes
+     * made already. This can be done via {@link UserManager#loadUser(UUID)} or
+     * {@link GroupManager#loadGroup(String)} respectively.</p>
+     *
+     * @param node The node to be set
+     * @param temporaryMergeBehaviour The behaviour used to merge temporary permission entries
+     * @return the result of the operation
+     * @throws NullPointerException if the node is null
+     * @since 4.3
+     */
+    @Nonnull
+    TemporaryDataMutateResult setPermission(@Nonnull Node node, @Nonnull TemporaryMergeBehaviour temporaryMergeBehaviour);
+
    /**
     * Sets a transient permission for the permission holder.
     *
@@ -499,6 +524,31 @@ public interface PermissionHolder {
    @Nonnull
    DataMutateResult setTransientPermission(@Nonnull Node node);

+    /**
+     * Sets a transient permission for the permission holder.
+     *
+     * <p>A transient node is a permission that does not persist.
+     * Whenever a user logs out of the server, or the server restarts, this permission will
+     * disappear. It is never saved to the datastore, and therefore will not apply on other
+     * servers.</p>
+     *
+     * <p>This is useful if you want to temporarily set a permission for a user while they're
+     * online, but don't want it to persist, and have to worry about removing it when they log
+     * out.</p>
+     *
+     * <p>For unsetting a transient permission, see {@link #unsetTransientPermission(Node)}.</p>
+     *
+     * <p>Although this method is named setTransientPermission, it can be used for all node types.</p>
+     *
+     * @param node The node to be se
+     * @param temporaryMergeBehaviour The behaviour used to merge temporary permission entries
+     * @return the result of the operation
+     * @throws NullPointerException if the node is null
+     * @since 4.3
+     */
+    @Nonnull
+    TemporaryDataMutateResult setTransientPermission(@Nonnull Node node, @Nonnull TemporaryMergeBehaviour temporaryMergeBehaviour);
+
    /**
     * Unsets a permission for the permission holder.
     *
@@ -0,0 +1,32 @@
+package me.lucko.luckperms.api;
+
+import javax.annotation.Nonnull;
+
+/**
+ * Extension of {@link DataMutateResult} for temporary set operations.
+ *
+ * @since 4.3
+ */
+public interface TemporaryDataMutateResult {
+
+    /**
+     * Gets the underlying result.
+     *
+     * @return the result
+     */
+    @Nonnull
+    DataMutateResult getResult();
+
+    /**
+     * Gets the node that resulted from any {@link TemporaryMergeBehaviour}
+     * processing.
+     *
+     * <p>If no processing took place, the same instance will be returned by
+     * this method.</p>
+     *
+     * @return the resultant node
+     */
+    @Nonnull
+    Node getMergedNode();
+
+}
@@ -0,0 +1,58 @@
+/*
+ * This file is part of LuckPerms, licensed under the MIT License.
+ *
+ *  Copyright (c) lucko (Luck) <luck@lucko.me>
+ *  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 me.lucko.luckperms.api;
+
+/**
+ * Controls how the implementation should behave when new temporary nodes are set
+ * that would otherwise conflict with existing entries.
+ *
+ * <p>The default behaviour of {@link PermissionHolder#setPermission(Node)} is
+ * to return a result of {@link DataMutateResult#ALREADY_HAS} when an equivalent
+ * node is found. This can be replicated using {@link #FAIL_WITH_ALREADY_HAS}.</p>
+ *
+ * <p>However, the {@link PermissionHolder#setPermission(Node, TemporaryMergeBehaviour)}
+ * method allows this behaviour to be customized for temporary permissions.</p>
+ *
+ * @since 4.3
+ */
+public enum TemporaryMergeBehaviour {
+
+    /**
+     * Expiry durations will be added to the existing expiry time of a permission.
+     */
+    ADD_NEW_DURATION_TO_EXISTING,
+
+    /**
+     * Expiry durations will be replaced if the new duration is longer than the current one.
+     */
+    REPLACE_EXISTING_IF_DURATION_LONGER,
+
+    /**
+     * The operation will fail if an existing temporary node is present.
+     */
+    FAIL_WITH_ALREADY_HAS
+
+}