Move stuff into commons, rename PermissionObject, add more javadocs to api

api/src/main/java/me/lucko/luckperms/LuckPerms.java

@@ -4,14 +4,22 @@ import lombok.AccessLevel;
 import lombok.NoArgsConstructor;
 import me.lucko.luckperms.api.LuckPermsApi;
 
+import java.util.Optional;
+
 /**
  * Static access to LuckPerms
  */
 @NoArgsConstructor(access = AccessLevel.PRIVATE)
-public class LuckPerms {
+public final class LuckPerms {
 
     private static LuckPermsApi api = null;
 
+
+    /**
+     * Gets an instance of {@link LuckPermsApi}
+     * @return an api instance
+     * @throws IllegalStateException if the api is not loaded
+     */
     public static LuckPermsApi getApi() {
         if (api == null) {
             throw new IllegalStateException("API is not loaded.");
@@ -19,6 +27,15 @@ public class LuckPerms {
         return api;
     }
 
+    /**
+     * Gets an instance of {@link LuckPermsApi} safely. Unlike {@link LuckPerms#getApi}, this method will not throw an
+     * {@link IllegalStateException} if the api is not loaded, rather return an empty {@link Optional}.
+     * @return an optional api instance
+     */
+    public static Optional<LuckPermsApi> getApiSafe() {
+        return Optional.ofNullable(api);
+    }
+
     static void registerProvider(LuckPermsApi luckPermsApi) {
         api = luckPermsApi;
     }

api/src/main/java/me/lucko/luckperms/api/Group.java

@@ -11,7 +11,7 @@ import java.util.List;
  * errors and ensure all API interactions to not damage the state of the group.
  */
 @SuppressWarnings("unused")
-public interface Group extends PermissionObject {
+public interface Group extends PermissionHolder {
 
     /**
      * @return the name of the group

api/src/main/java/me/lucko/luckperms/api/Logger.java

@@ -1,5 +1,10 @@
 package me.lucko.luckperms.api;
 
+/**
+ * A wrapper class for platform logger instances.
+ * Bukkit/Bungee both use java.util.logging, and Sponge uses org.slf4j. This class wraps those classes so the commons
+ * module can access a logger.
+ */
 public interface Logger {
 
     void info(String s);

api/src/main/java/me/lucko/luckperms/api/LuckPermsApi.java

@@ -2,23 +2,81 @@ package me.lucko.luckperms.api;
 
 import java.util.UUID;
 
+/**
+ * The root Api interface in LuckPerms
+ */
 @SuppressWarnings("unused")
 public interface LuckPermsApi {
 
+    /**
+     * Schedules an update task to run
+     */
     void runUpdateTask();
+
+    /**
+     * @return the version of the plugin running on the platform
+     */
     String getVersion();
 
+    /**
+     * Gets a wrapped {@link Datastore} instance, with somewhat limited access
+     * @return a datastore instance
+     */
     Datastore getDatastore();
+
+    /**
+     * Gets the {@link Logger} wrapping used by the platform
+     * @return the logger instance
+     */
     Logger getLogger();
 
+    /**
+     * Gets a wrapped user object from the user storage
+     * @param uuid the uuid of the user to get
+     * @return a {@link User} object, if one matching the uuid is loaded, or null if not
+     */
     User getUser(UUID uuid);
+
+    /**
+     * Gets a wrapped user object from the user storage
+     * @param name the username of the user to get
+     * @return a a {@link User} object, if one matching the uuid is loaded, or null if not
+     */
     User getUser(String name);
+
+    /**
+     * Check if a user is loaded in memory
+     * @param uuid the uuid to check for
+     * @return true if the user is loaded
+     */
     boolean isUserLoaded(UUID uuid);
 
+    /**
+     * Gets a wrapped group object from the group storage
+     * @param name the name of the group to get
+     * @return a {@link Group} object, if one matching the name exists, or null if not
+     */
     Group getGroup(String name);
+
+    /**
+     * Check if a group is loaded in memory
+     * @param name the name to check for
+     * @return true if the group is loaded
+     */
     boolean isGroupLoaded(String name);
 
+    /**
+     * Gets a wrapped track object from the track storage
+     * @param name the name of the track to get
+     * @return a {@link Track} object, if one matching the name exists, or null if not
+     */
     Track getTrack(String name);
+
+    /**
+     * Check if a track is loaded in memory
+     * @param name the name to check for
+     * @return true if the track is loaded
+     */
     boolean isTrackLoaded(String name);
 
 }

api/src/main/java/me/lucko/luckperms/api/PermissionHolder.java

@@ -7,12 +7,12 @@ import java.util.List;
 import java.util.Map;
 
 /**
- * Wrapper interface for internal PermissionObject (user/group) instances
+ * Wrapper interface for internal PermissionHolder (user/group) instances
  * The implementations of this interface limit access to the object and add parameter checks to further prevent
  * errors and ensure all API interactions to not damage the state of the object.
  */
 @SuppressWarnings("unused")
-public interface PermissionObject {
+public interface PermissionHolder {
 
     String getObjectName();
 

api/src/main/java/me/lucko/luckperms/api/User.java

@@ -12,7 +12,7 @@ import java.util.UUID;
  * errors and ensure all API interactions to not damage the state of the user.
  */
 @SuppressWarnings("unused")
-public interface User extends PermissionObject {
+public interface User extends PermissionHolder {
 
     /**
      * @return the users Mojang assigned unique id

api/src/main/java/me/lucko/luckperms/exceptions/ObjectAlreadyHasException.java

@@ -1,4 +1,8 @@
 package me.lucko.luckperms.exceptions;
 
+/**
+ * Thrown when a permission holding object already has a permission, is already a member of a group, or when a track
+ * already contains a group.
+ */
 public class ObjectAlreadyHasException extends Exception {
 }

api/src/main/java/me/lucko/luckperms/exceptions/ObjectLacksException.java

@@ -1,4 +1,8 @@
 package me.lucko.luckperms.exceptions;
 
+/**
+ * Thrown when a permission holding object does not already have a permission, is not already a member of a group,
+ * or when a track doesn't contain a group.
+ */
 public class ObjectLacksException extends Exception {
 }