More cleanup

2016-11-08 20:46:29 +00:00
parent 90f8dbe243
commit 1c534d7475
31 changed files with 223 additions and 169 deletions
@@ -49,46 +49,142 @@ import java.util.Set;
 import java.util.UUID;

 /**
- * Main internal interface for LuckPerms plugins, allowing the luckperms-common module to bind with the plugin instance.
+ * Main internal interface for LuckPerms plugins, providing the base for abstraction throughout the project.
+ *
 * All plugin platforms implement this interface.
 */
 public interface LuckPermsPlugin {

-    /*
-     * Access to all of the main internal manager classes
+    /**
+     * Gets the user manager instance for the platform
+     * @return the user manager
     */
    UserManager getUserManager();
+
+    /**
+     * Gets the group manager instance for the platform
+     * @return the group manager
+     */
    GroupManager getGroupManager();
+
+    /**
+     * Gets the track manager instance for the platform
+     * @return the track manager
+     */
    TrackManager getTrackManager();
+
+    /**
+     * Gets the plugin's configuration
+     * @return the plugin config
+     */
    LPConfiguration getConfiguration();
+
+    /**
+     * Gets the primary datastore instance. This is likely to be wrapped with extra layers for caching, etc.
+     * @return the datastore
+     */
    Datastore getDatastore();
+
+    /**
+     * Gets the redis messaging instance if present. Could return null if redis is not enabled.
+     * @return the redis messaging service
+     */
    RedisMessaging getRedisMessaging();
+
+    /**
+     * Gets a wrapped logger instance for the platform.
+     * @return the plugin's logger
+     */
    Logger getLog();
+
+    /**
+     * Gets the UUID caching store for the platform
+     * @return the uuid cache
+     */
    UuidCache getUuidCache();
+
+    /**
+     * Returns the class implementing the LuckPermsAPI on this platform.
+     * @return the api
+     */
    ApiProvider getApiProvider();
+
+    /**
+     * Gets the importer instance
+     * @return the importer
+     */
    Importer getImporter();
+
+    /**
+     * Gets the consecutive command executor instance
+     * @return the consecutive executor
+     */
    ConsecutiveExecutor getConsecutiveExecutor();
+
+    /**
+     * Gets the instance providing locale translations for the plugin
+     * @return the locale manager
+     */
    LocaleManager getLocaleManager();
+
+    /**
+     * Gets the context manager.
+     * This object handles context accumulation for all players on the platform.
+     * @return the context manager
+     */
    ContextManager getContextManager();
+
+    /**
+     * Gets the class responsible for constructing PermissionCalculators on this platform.
+     * @return the permission calculator factory
+     */
    CalculatorFactory getCalculatorFactory();
+
+    /**
+     * Gets the verbose debug handler instance.
+     * @return the debug handler instance
+     */
    DebugHandler getDebugHandler();

    /**
+     * Execute a runnable asynchronously
+     * @param r the task to run
+     */
+    void doAsync(Runnable r);
+
+    /**
+     * Execute a runnable synchronously
+     * @param r the task to run
+     */
+    void doSync(Runnable r);
+
+    /**
+     * Execute a runnable asynchronously on a loop
+     * @param r the task to run
+     * @param interval the time between runs in ticks
+     */
+    void doAsyncRepeating(Runnable r, long interval);
+
+    /**
+     * Gets a string of the plugin's version
     * @return the version of the plugin
     */
    String getVersion();

    /**
+     * Gets the platform type this instance of LuckPerms is running on.
     * @return the platform type
     */
    PlatformType getType();

    /**
+     * Gets the plugins main directory
     * @return the main plugin directory
     */
    File getMainDir();

    /**
+     * Gets the plugins main data storage directory
     * @return the platforms data folder
     */
    File getDataFolder();
@@ -129,11 +225,13 @@ public interface LuckPermsPlugin {
    boolean isOnline(UUID external);

    /**
+     * Gets a list of online Senders on the platform
     * @return a {@link List} of senders online on the platform
     */
-    List<Sender> getNotifyListeners();
+    List<Sender> getSenders();

    /**
+     * Gets the console.
     * @return the console sender of the instance
     */
    Sender getConsoleSender();
@@ -147,7 +245,7 @@ public interface LuckPermsPlugin {

    /**
     * Gets a set of players ignoring logging output
-     * @return a {@link Set} of uuids
+     * @return a {@link Set} of {@link UUID}s
     */
    Set<UUID> getIgnoringLogs();

@@ -166,7 +264,7 @@ public interface LuckPermsPlugin {
    Object getService(Class clazz);

    /**
-     * Used as a backup for migration
+     * Gets the UUID of a player. Used as a backup for migration
     * @param playerName the players name
     * @return a uuid if found, or null if not
     */
@@ -180,27 +278,9 @@ public interface LuckPermsPlugin {
    boolean isPluginLoaded(String name);

    /**
-     * Runs an update task
+     * Gets the update task buffer of the platform, used for scheduling and running update tasks.
+     * @return the update task buffer instance
     */
    BufferedRequest<Void> getUpdateTaskBuffer();

-    /**
-     * Execute a runnable asynchronously
-     * @param r the task to run
-     */
-    void doAsync(Runnable r);
-
-    /**
-     * Execute a runnable synchronously
-     * @param r the task to run
-     */
-    void doSync(Runnable r);
-
-    /**
-     * Execute a runnable asynchronously on a loop
-     * @param r the task to run
-     * @param interval the time between runs in ticks
-     */
-    void doAsyncRepeating(Runnable r, long interval);
-
 }
@@ -26,6 +26,7 @@ import me.lucko.luckperms.api.event.events.LogNotifyEvent;
 import me.lucko.luckperms.common.LuckPermsPlugin;
 import me.lucko.luckperms.common.commands.Sender;
 import me.lucko.luckperms.common.constants.Message;
+import me.lucko.luckperms.common.constants.Permission;
 import me.lucko.luckperms.common.core.PermissionHolder;
 import me.lucko.luckperms.common.groups.Group;
 import me.lucko.luckperms.common.tracks.Track;
@@ -56,15 +57,17 @@ public class LogEntry extends me.lucko.luckperms.api.LogEntry {

        final String msg = super.getFormatted();

-        List<Sender> senders = plugin.getNotifyListeners();
+        List<Sender> senders = plugin.getSenders();
        senders.add(plugin.getConsoleSender());

        if (sender == null) {
            senders.stream()
+                    .filter(Permission.LOG_NOTIFY::isAuthorized)
                    .filter(s -> !plugin.getIgnoringLogs().contains(s.getUuid()))
                    .forEach(s -> Message.LOG.send(s, msg));
        } else {
            senders.stream()
+                    .filter(Permission.LOG_NOTIFY::isAuthorized)
                    .filter(s -> !plugin.getIgnoringLogs().contains(s.getUuid()))
                    .filter(s -> !s.getUuid().equals(sender.getUuid()))
                    .forEach(s -> Message.LOG.send(s, msg));
@@ -61,6 +61,9 @@ public class User extends PermissionHolder implements Identifiable<UserIdentifie
    @Setter
    private String primaryGroup = null;

+    /**
+     * The users data cache instance, if present.
+     */
    @Getter
    private UserCache userData = null;

@@ -26,6 +26,10 @@ import java.util.concurrent.CountDownLatch;
 import java.util.concurrent.TimeUnit;
 import java.util.concurrent.TimeoutException;

+/**
+ * Basic Future implementation
+ * @param <R> the return type
+ */
 public class AbstractFuture<R> implements LPFuture<R> {
    private final CountDownLatch latch = new CountDownLatch(1);
    private R value;
@@ -32,6 +32,9 @@ import me.lucko.luckperms.common.users.User;

 import java.util.UUID;

+/**
+ * An abstract listener shared by Bukkit & Sponge.
+ */
@AllArgsConstructor
 public class AbstractListener {
    private final LuckPermsPlugin plugin;
@@ -25,6 +25,9 @@ package me.lucko.luckperms.common.utils;
 import lombok.experimental.UtilityClass;
 import me.lucko.luckperms.common.constants.Patterns;

+/**
+ * Utility for checking arguments for consistency
+ */
@UtilityClass
 public class ArgumentChecker {

@@ -27,19 +27,24 @@ import lombok.*;
 import java.util.LinkedList;
 import java.util.List;
 import java.util.ListIterator;
+import java.util.concurrent.locks.ReentrantLock;

 /**
- * Holds a buffer of objects to be processed after they've been in the buffer for a given time.
+ * Thread-safe buffer utility. Holds a buffer of objects to be processed after they've been waiting in the buffer
+ * for a given time. If the same object is pushed to the buffer again in that time, its wait time is reset.
+ *
 * @param <T> the type of objects in the buffer
 * @param <R> the type of result produced by the final process
 */
 public abstract class Buffer<T, R> implements Runnable {
    private static final long DEFAULT_FLUSH_TIME = 1000; // 1 second

+    private final ReentrantLock lock = new ReentrantLock();
    private final List<BufferedObject<T, R>> buffer = new LinkedList<>();

    public LPFuture<R> enqueue(@NonNull T t) {
-        synchronized (buffer) {
+        lock.lock();
+        try {
            ListIterator<BufferedObject<T, R>> it = buffer.listIterator();

            BufferedObject<T, R> o = null;
@@ -62,6 +67,8 @@ public abstract class Buffer<T, R> implements Runnable {

            buffer.add(o);
            return o.getFuture();
+        } finally {
+            lock.unlock();
        }
    }

@@ -70,7 +77,8 @@ public abstract class Buffer<T, R> implements Runnable {
    public void flush(long flushTime) {
        long time = System.currentTimeMillis();

-        synchronized (buffer) {
+        lock.lock();
+        try {
            ListIterator<BufferedObject<T, R>> it = buffer.listIterator(buffer.size());

            while (it.hasPrevious()) {
@@ -85,6 +93,8 @@ public abstract class Buffer<T, R> implements Runnable {
                    it.remove();
                }
            }
+        } finally {
+            lock.unlock();
        }
    }

@@ -30,14 +30,20 @@ import java.util.concurrent.locks.ReentrantLock;
 import java.util.function.Consumer;
 import java.util.function.Supplier;

+/**
+ * Thread-safe request buffer.
+ *
+ * Waits for the buffer time to pass before performing the operation. If the task is called again in that time, the
+ * buffer time is reset.
+ *
+ * @param <T> the return type
+ */
@RequiredArgsConstructor
 public abstract class BufferedRequest<T> {
    private final long bufferTimeMillis;
    private final Consumer<Runnable> executor;

    private WeakReference<Processor<T>> processor = null;
-
-    @Getter
    private ReentrantLock lock = new ReentrantLock();

    public LPFuture<T> request() {
@@ -66,7 +72,6 @@ public abstract class BufferedRequest<T> {

    protected abstract T perform();

-
    @RequiredArgsConstructor
    private static class Processor<R> implements Runnable {
        private final long delayMillis;
@@ -1,23 +1,7 @@
 /*
- * Copyright (c) 2016 Lucko (Luck) <luck@lucko.me>
- *
- *  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.
+ *  All credit to Essentials / EssentialsX for this class
+ *  https://github.com/drtshock/Essentials/blob/2.x/Essentials/src/com/earth2me/essentials/utils/DateUtil.java
+ *  https://github.com/essentials/Essentials/blob/2.x/Essentials/src/com/earth2me/essentials/utils/DateUtil.java
 */

 package me.lucko.luckperms.common.utils;
@@ -30,9 +14,7 @@ import java.util.regex.Matcher;
 import java.util.regex.Pattern;

 /**
- * All credit to Essentials / EssentialsX for this class
- * https://github.com/drtshock/Essentials/blob/2.x/Essentials/src/com/earth2me/essentials/utils/DateUtil.java
- * https://github.com/essentials/Essentials/blob/2.x/Essentials/src/com/earth2me/essentials/utils/DateUtil.java
+ * Translates unix timestamps / durations into a readable format
 */
@UtilityClass
 public class DateUtil {
@@ -52,13 +34,7 @@ public class DateUtil {
     */
    public static long parseDateDiff(String time, boolean future) throws IllegalDateException {
        Matcher m = TIME_PATTERN.matcher(time);
-        int years = 0;
-        int months = 0;
-        int weeks = 0;
-        int days = 0;
-        int hours = 0;
-        int minutes = 0;
-        int seconds = 0;
+        int years = 0, months = 0, weeks = 0, days = 0, hours = 0, minutes = 0, seconds = 0;
        boolean found = false;
        while (m.find()) {
            if (m.group() == null || m.group().isEmpty()) {
@@ -137,8 +113,7 @@ public class DateUtil {
        int fromYear = fromDate.get(year);
        int toYear = toDate.get(year);
        if (Math.abs(fromYear - toYear) > MAX_YEARS) {
-            toDate.set(year, fromYear +
-                    (future ? MAX_YEARS : -MAX_YEARS));
+            toDate.set(year, fromYear + (future ? MAX_YEARS : -MAX_YEARS));
        }

        int diff = 0;
@@ -36,11 +36,11 @@ import java.util.UUID;
 import java.util.concurrent.ConcurrentHashMap;

 public class DebugHandler {
-    private final Map<Reciever, List<String>> listeners = new ConcurrentHashMap<>();
+    private final Map<Receiver, List<String>> listeners = new ConcurrentHashMap<>();

    public void printOutput(String checked, String node, Tristate value) {
        all:
-        for (Map.Entry<Reciever, List<String>> e : listeners.entrySet()) {
+        for (Map.Entry<Receiver, List<String>> e : listeners.entrySet()) {
            for (String filter : e.getValue()) {
                if (node.toLowerCase().startsWith(filter.toLowerCase())) {
                    continue;
@@ -58,17 +58,17 @@ public class DebugHandler {
    }

    public void register(Sender sender, List<String> filters) {
-        listeners.put(new Reciever(sender.getUuid(), sender), ImmutableList.copyOf(filters));
+        listeners.put(new Receiver(sender.getUuid(), sender), ImmutableList.copyOf(filters));
    }

    public void unregister(UUID uuid) {
-        listeners.remove(new Reciever(uuid, null));
+        listeners.remove(new Receiver(uuid, null));
    }

    @Getter
    @EqualsAndHashCode(of = "uuid")
    @AllArgsConstructor
-    private static final class Reciever {
+    private static final class Receiver {
        private final UUID uuid;
        private final Sender sender;
    }
@@ -27,7 +27,7 @@ import lombok.experimental.Delegate;
 import me.lucko.luckperms.api.Node;

 /**
- * Holds a Node and where it was inherited from
+ * Holds a Node and where it was inherited from. All calls are passed onto the contained Node instance.
 */
@Getter
@ToString
@@ -25,6 +25,9 @@ package me.lucko.luckperms.common.utils;
 import lombok.experimental.UtilityClass;
 import me.lucko.luckperms.api.Logger;

+/**
+ * Utility to help create wrapped log instances
+ */
@UtilityClass
 public class LogFactory {
    public static Logger wrap(org.slf4j.Logger l) {
@@ -29,6 +29,9 @@ import java.util.function.Predicate;
 import java.util.stream.Collectors;
 import java.util.stream.IntStream;

+/**
+ * A collection of predicate utilities used mostly in command classes
+ */
@SuppressWarnings({"WeakerAccess", "unused"})
@UtilityClass
 public class Predicates {