diff --git a/api/src/main/java/me/lucko/luckperms/api/Datastore.java b/api/src/main/java/me/lucko/luckperms/api/Datastore.java index 84873d66..c45b3d79 100644 --- a/api/src/main/java/me/lucko/luckperms/api/Datastore.java +++ b/api/src/main/java/me/lucko/luckperms/api/Datastore.java @@ -28,9 +28,6 @@ import java.util.UUID; /** * Wrapper interface for the internal Datastore instance - * - *

The implementations of this interface limit access to the datastore and add parameter checks to further prevent - * errors and ensure all API interactions to not damage the state of the plugin. */ @SuppressWarnings("unused") public interface Datastore { @@ -38,10 +35,191 @@ public interface Datastore { String getName(); boolean isAcceptingLogins(); - Async async(); + /** + * Gets the {@link Sync} interface. + * + * All operations through this interface are called immediately and in the same thread as they are called. + * Datastore operations are thread blocking, and Sync operations should not be called on the main server thread. + * @return the sync interface + */ Sync sync(); + + /** + * Gets the {@link Async} interface. + * + * All operations through this interface are called in a new, separate asynchronous thread. + * When the operation is complete, the provided callback method is called, in applicable, in the main server thread. + * @return the async interface + */ + Async async(); + + /** + * Gets the {@link Future} interface + * + * All operations through this interface are called in a new, separate asynchronous thread, similar to {@link Async}. + * The only difference is that instead of providing a callback, a {@link java.util.concurrent.Future} is returned. + * See the Oracle JavaDocs for usage of the Future class. + * @return the future interface + */ Future future(); + /** + * All operations through this interface are called immediately and in the same thread as they are called. + * Datastore operations are thread blocking, and Sync operations should not be called on the main server thread. + */ + interface Sync { + + /** + * Saves an action to the datastore + * @param entry the log entry to be saved + * @return true if the operation completed successfully. + * @throws NullPointerException if entry is null + */ + boolean logAction(LogEntry entry); + + /** + * Loads and returns the log from the datastore + * @return a log instance, could be null + */ + Log getLog(); + + /** + * Either loads or creates a user object, and loads it into the plugins internal storage + * @param uuid the uuid of the user + * @param username the users username. (if you want to specify null here, just input "null" as a string.) + * @return true if the operation completed successfully. + * @throws NullPointerException if uuid or username is null + * @throws IllegalArgumentException if either of the parameters are invalid + */ + boolean loadOrCreateUser(UUID uuid, String username); + + /** + * Loads a user from the datastore into the plugins internal storage. + * @param uuid the uuid of the user to load + * @return true if the user exists, and was loaded correctly. + * @throws NullPointerException if uuid is null + */ + boolean loadUser(UUID uuid); + + /** + * Saves a user object into the datastore. You should call this after you make any changes to a user. + * @param user the user to save + * @return true if the operation completed successfully. + * @throws NullPointerException if user is null + * @throws IllegalStateException if the user instance was not obtained from LuckPerms. + */ + boolean saveUser(User user); + + /** + * Creates and loads a group into the plugins internal storage + * @param name the name of the group + * @return true if the operation completed successfully + * @throws NullPointerException if name is null + * @throws IllegalArgumentException if the name is invalid + */ + boolean createAndLoadGroup(String name); + + /** + * Loads a group into the plugins internal storage. + * @param name the name of the group + * @return true if the operation completed successfully + * @throws NullPointerException if name is null + * @throws IllegalArgumentException if the name is invalid + */ + boolean loadGroup(String name); + + /** + * Loads all groups from the datastore into the plugins internal storage + * @return true if the operation completed successfully. + */ + boolean loadAllGroups(); + + /** + * Saves a group back to the datastore. You should call this after you make any changes to a group. + * @param group the group to save + * @return true if the operation completed successfully. + * @throws NullPointerException if group is null + * @throws IllegalStateException if the group instance was not obtained from LuckPerms. + */ + boolean saveGroup(Group group); + + /** + * Permanently deletes a group from the datastore + * @param group the group to delete + * @return true if the operation completed successfully. + * @throws NullPointerException if group is null + * @throws IllegalStateException if the group instance was not obtained from LuckPerms. + */ + boolean deleteGroup(Group group); + + /** + * Creates and loads a track into the plugins internal storage + * @param name the name of the track + * @return true if the operation completed successfully + * @throws NullPointerException if name is null + * @throws IllegalArgumentException if the name is invalid + */ + boolean createAndLoadTrack(String name); + + /** + * Loads a track into the plugins internal storage. + * @param name the name of the track + * @return true if the operation completed successfully + * @throws NullPointerException if name is null + * @throws IllegalArgumentException if the name is invalid + */ + boolean loadTrack(String name); + + /** + * Loads all tracks from the datastore into the plugins internal storage + * @return true if the operation completed successfully. + */ + boolean loadAllTracks(); + + /** + * Saves a track back to the datastore. You should call this after you make any changes to a track. + * @param track the track to save + * @return true if the operation completed successfully. + * @throws NullPointerException if track is null + * @throws IllegalStateException if the track instance was not obtained from LuckPerms. + */ + boolean saveTrack(Track track); + + /** + * Permanently deletes a track from the datastore + * @param track the track to delete + * @return true if the operation completed successfully. + * @throws NullPointerException if track is null + * @throws IllegalStateException if the track instance was not obtained from LuckPerms. + */ + boolean deleteTrack(Track track); + + /** + * Saves UUID caching data to the datastore + * @param username the users username + * @param uuid the users mojang unique id + * @return true if the operation completed successfully. + * @throws NullPointerException if either parameters are null + * @throws IllegalArgumentException if the username is invalid + */ + boolean saveUUIDData(String username, UUID uuid); + + /** + * Gets a UUID from a username + * @param username the corresponding username + * @return a uuid object, could be null + * @throws NullPointerException if either parameters are null + * @throws IllegalArgumentException if the username is invalid + */ + UUID getUUID(String username); + } + + /** + * All operations through this interface are called in a new, separate asynchronous thread. + * When the operation is complete, the provided callback method is called, in applicable, in the main server thread. + * + * See {@link Sync} for method documentation. + */ interface Async { void logAction(LogEntry entry, Callback callback); void getLog(Callback callback); @@ -62,26 +240,13 @@ public interface Datastore { void getUUID(String username, Callback callback); } - interface Sync { - boolean logAction(LogEntry entry); - Log getLog(); - boolean loadOrCreateUser(UUID uuid, String username); - boolean loadUser(UUID uuid); - boolean saveUser(User user); - boolean createAndLoadGroup(String name); - boolean loadGroup(String name); - boolean loadAllGroups(); - boolean saveGroup(Group group); - boolean deleteGroup(Group group); - boolean createAndLoadTrack(String name); - boolean loadTrack(String name); - boolean loadAllTracks(); - boolean saveTrack(Track track); - boolean deleteTrack(Track track); - boolean saveUUIDData(String username, UUID uuid); - UUID getUUID(String username); - } - + /** + * All operations through this interface are called in a new, separate asynchronous thread, similar to {@link Async}. + * The only difference is that instead of providing a callback, a {@link java.util.concurrent.Future} is returned. + * See the Oracle JavaDocs for usage of the Future class. + * + * See {@link Sync} for method documentation. + */ interface Future { java.util.concurrent.Future logAction(LogEntry entry); java.util.concurrent.Future getLog(); diff --git a/api/src/main/java/me/lucko/luckperms/api/Group.java b/api/src/main/java/me/lucko/luckperms/api/Group.java index 3f92af7d..99edf626 100644 --- a/api/src/main/java/me/lucko/luckperms/api/Group.java +++ b/api/src/main/java/me/lucko/luckperms/api/Group.java @@ -29,9 +29,6 @@ import java.util.List; /** * Wrapper interface for internal Group instances - * - *

The implementations of this interface limit access to the Group and add parameter checks to further prevent - * errors and ensure all API interactions to not damage the state of the group. */ @SuppressWarnings("unused") public interface Group extends PermissionHolder { @@ -42,26 +39,34 @@ public interface Group extends PermissionHolder { String getName(); /** - * check to see if a group inherits a group + * Check to see if a group inherits a group * @param group The group to check membership of - * @return true if the user is a member of the group + * @return true if the group inherits the other group + * @throws NullPointerException if the group is null + * @throws IllegalStateException if the group instance was not obtained from LuckPerms. */ boolean inheritsGroup(Group group); /** - * check to see if the group inherits a group on a specific server + * Check to see if the group inherits a group on a specific server * @param group The group to check membership of * @param server The server to check on - * @return true if the group inherits the group + * @return true if the group inherits the group on the server + * @throws NullPointerException if the group or server is null + * @throws IllegalStateException if the group instance was not obtained from LuckPerms. + * @throws IllegalArgumentException if the server is invalid */ boolean inheritsGroup(Group group, String server); /** - * check to see if the group inherits a group on a specific server + * Check to see if the group inherits a group on a specific server and world * @param group The group to check membership of * @param server The server to check on * @param world The world to check on - * @return true if the group inherits the group + * @return true if the group inherits the group on the server and world + * @throws NullPointerException if the group, server or world is null + * @throws IllegalStateException if the group instance was not obtained from LuckPerms. + * @throws IllegalArgumentException if the server or world is invalid */ boolean inheritsGroup(Group group, String server, String world); @@ -69,101 +74,134 @@ public interface Group extends PermissionHolder { * Make this group inherit another group * @param group the group to be inherited * @throws ObjectAlreadyHasException if the group already inherits the group + * @throws NullPointerException if the group is null + * @throws IllegalStateException if the group instance was not obtained from LuckPerms. */ void setInheritGroup(Group group) throws ObjectAlreadyHasException; /** * Make this group inherit another group on a specific server * @param group the group to be inherited - * @param server The server to add the group on + * @param server The server to inherit the group on * @throws ObjectAlreadyHasException if the group already inherits the group on that server + * @throws NullPointerException if the group or server is null + * @throws IllegalStateException if the group instance was not obtained from LuckPerms. + * @throws IllegalArgumentException if the server is invalid */ void setInheritGroup(Group group, String server) throws ObjectAlreadyHasException; /** - * Make this group inherit another group on a specific server + * Make this group inherit another group on a specific server and world * @param group the group to be inherited - * @param server The server to add the group on - * @param world The world to add the group on - * @throws ObjectAlreadyHasException if the group already inherits the group on that server + * @param server The server to inherit the group on + * @param world The world to inherit the group on + * @throws ObjectAlreadyHasException if the group already inherits the group on that server and world + * @throws NullPointerException if the group, server or world is null + * @throws IllegalStateException if the group instance was not obtained from LuckPerms. + * @throws IllegalArgumentException if the server or world is invalid */ void setInheritGroup(Group group, String server, String world) throws ObjectAlreadyHasException; /** - * Make this group inherit another group on a specific server + * Make this group inherit another group temporarily * @param group the group to be inherited - * @param expireAt when the group should expire - * @throws ObjectAlreadyHasException if the group already inherits the group on that server + * @param expireAt the unix time when the group should expire + * @throws ObjectAlreadyHasException if the group already inherits the group temporarily + * @throws NullPointerException if the group is null + * @throws IllegalStateException if the group instance was not obtained from LuckPerms. + * @throws IllegalArgumentException if the expiry time is in the past */ void setInheritGroup(Group group, long expireAt) throws ObjectAlreadyHasException; /** - * Make this group inherit another group on a specific server + * Make this group inherit another group on a specific server temporarily * @param group the group to be inherited - * @param server The server to add the group on + * @param server The server inherit add the group on * @param expireAt when the group should expire - * @throws ObjectAlreadyHasException if the group already inherits the group on that server + * @throws ObjectAlreadyHasException if the group already inherits the group on that server temporarily + * @throws NullPointerException if the group or server is null + * @throws IllegalStateException if the group instance was not obtained from LuckPerms. + * @throws IllegalArgumentException if the expiry time is in the past or the server is invalid */ void setInheritGroup(Group group, String server, long expireAt) throws ObjectAlreadyHasException; /** - * Make this group inherit another group on a specific server + * Make this group inherit another group on a specific server and world temporarily * @param group the group to be inherited - * @param server The server to add the group on - * @param world The world to add the group on + * @param server The server to inherit the group on + * @param world The world to inherit the group on * @param expireAt when the group should expire - * @throws ObjectAlreadyHasException if the group already inherits the group on that server + * @throws ObjectAlreadyHasException if the group already inherits the group on that server and world temporarily + * @throws NullPointerException if the group, server or world is null + * @throws IllegalStateException if the group instance was not obtained from LuckPerms. + * @throws IllegalArgumentException if the expiry time is in the past or the server/world is invalid */ void setInheritGroup(Group group, String server, String world, long expireAt) throws ObjectAlreadyHasException; /** - * Remove a previously set inheritance + * Remove a previously set inheritance rule * @param group the group to uninherit * @throws ObjectLacksException if the group does not already inherit the group + * @throws NullPointerException if the group is null + * @throws IllegalStateException if the group instance was not obtained from LuckPerms. */ void unsetInheritGroup(Group group) throws ObjectLacksException; /** - * Remove a previously set inheritance + * Remove a previously set inheritance rule * @param group the group to uninherit * @param temporary if the group being removed is temporary * @throws ObjectLacksException if the group does not already inherit the group + * @throws NullPointerException if the group is null + * @throws IllegalStateException if the group instance was not obtained from LuckPerms. */ void unsetInheritGroup(Group group, boolean temporary) throws ObjectLacksException; /** - * Remove a previously set inheritance + * Remove a previously set inheritance rule on a specific server * @param group the group to uninherit * @param server The server to remove the group on - * @throws ObjectLacksException if the group does not already inherit the group + * @throws ObjectLacksException if the group does not already inherit the group on that server + * @throws NullPointerException if the group or server is null + * @throws IllegalStateException if the group instance was not obtained from LuckPerms. + * @throws IllegalArgumentException if the server is invalid */ void unsetInheritGroup(Group group, String server) throws ObjectLacksException; /** - * Remove a previously set inheritance + * Remove a previously set inheritance rule on a specific server and world * @param group the group to uninherit * @param server The server to remove the group on * @param world The world to remove the group on * @throws ObjectLacksException if the group does not already inherit the group + * @throws NullPointerException if the group, server or world is null + * @throws IllegalStateException if the group instance was not obtained from LuckPerms. + * @throws IllegalArgumentException if the server or world is invalid */ void unsetInheritGroup(Group group, String server, String world) throws ObjectLacksException; /** - * Remove a previously set inheritance + * Remove a previously set inheritance rule on a specific server * @param group the group to uninherit * @param server The server to remove the group on * @param temporary if the group being removed is temporary * @throws ObjectLacksException if the group does not already inherit the group + * @throws NullPointerException if the group or server is null + * @throws IllegalStateException if the group instance was not obtained from LuckPerms. + * @throws IllegalArgumentException if the expiry time is in the past or the server is invalid */ void unsetInheritGroup(Group group, String server, boolean temporary) throws ObjectLacksException; /** - * Remove a previously set inheritance + * Remove a previously set inheritance rule on a specific server and world * @param group the group to uninherit * @param server The server to remove the group on * @param world The world to remove the group on - * @param temporary if the group being removed is temporary + * @param temporary if the group being removed was set temporarily * @throws ObjectLacksException if the group does not already inherit the group + * @throws NullPointerException if the group, server or world is null + * @throws IllegalStateException if the group instance was not obtained from LuckPerms. + * @throws IllegalArgumentException if the expiry time is in the past or the server/world is invalid */ void unsetInheritGroup(Group group, String server, String world, boolean temporary) throws ObjectLacksException; @@ -183,6 +221,8 @@ public interface Group extends PermissionHolder { * @param server the server to check * @param world the world to check * @return a {@link List} of group names + * @throws NullPointerException if the server or world is null + * @throws IllegalArgumentException if the server or world is invalid */ List getLocalGroups(String server, String world); @@ -190,6 +230,8 @@ public interface Group extends PermissionHolder { * Get a {@link List} of the groups the group inherits on a specific server * @param server the server to check * @return a {@link List} of group names + * @throws NullPointerException if the server is null + * @throws IllegalArgumentException if the server is invalid */ List getLocalGroups(String server); } diff --git a/api/src/main/java/me/lucko/luckperms/api/LPConfiguration.java b/api/src/main/java/me/lucko/luckperms/api/LPConfiguration.java index 195f9a75..ceb4a9cc 100644 --- a/api/src/main/java/me/lucko/luckperms/api/LPConfiguration.java +++ b/api/src/main/java/me/lucko/luckperms/api/LPConfiguration.java @@ -28,6 +28,7 @@ import me.lucko.luckperms.api.data.MySQLConfiguration; /** * A wrapper interface for the internal LuckPerms configuration, providing read only access. */ +@SuppressWarnings("unused") public interface LPConfiguration { /** diff --git a/api/src/main/java/me/lucko/luckperms/api/Log.java b/api/src/main/java/me/lucko/luckperms/api/Log.java index 653b7393..346048e0 100644 --- a/api/src/main/java/me/lucko/luckperms/api/Log.java +++ b/api/src/main/java/me/lucko/luckperms/api/Log.java @@ -28,7 +28,7 @@ import java.util.UUID; /** * Represents the internal LuckPerms log. - * All content is immutable. You can add to the log using the {@link Datastore}, and then request an updated copy. + * All content internally is immutable. You can add to the log using the {@link Datastore}, and then request an updated copy. */ @SuppressWarnings("unused") public interface Log { @@ -38,27 +38,124 @@ public interface Log { */ SortedSet getContent(); + /** + * @return all content in this log + */ SortedSet getRecent(); + + /** + * Gets the recent content separated by page + * @param pageNo the page number + * @return the page content + */ SortedMap getRecent(int pageNo); + + /** + * @return the max page number allowed in the {@link #getRecent(int)} method + */ int getRecentMaxPages(); + + /** + * @param actor the uuid of the actor to filter by + * @return all content in this log where is actor = uuid + */ SortedSet getRecent(UUID actor); + + /** + * Gets the recent content for the uuid, separated into pages + * @param pageNo the page number + * @param actor the uuid of the actor to filter by + * @return the page content + */ SortedMap getRecent(int pageNo, UUID actor); + + /** + * @param actor the actor to filter by + * @return the max page number allowed in the {@link #getRecent(int, UUID)} method + */ int getRecentMaxPages(UUID actor); + + /** + * @param uuid the uuid to filter by + * @return all content in this log where the user = uuid + */ SortedSet getUserHistory(UUID uuid); + + /** + * Gets the user history content, separated by pages + * @param pageNo the page number + * @param uuid the uuid of the acted user to filter by + * @return the page content + */ SortedMap getUserHistory(int pageNo, UUID uuid); + + /** + * @param uuid the uuid to filter by + * @return the max page number allowed in the {@link #getUserHistory(int, UUID)} method + */ int getUserHistoryMaxPages(UUID uuid); + + /** + * @param name the name to filter by + * @return all content in this log where the group = name + */ SortedSet getGroupHistory(String name); + + /** + * Gets the group history content, separated by pages + * @param pageNo the page number + * @param name the name of the acted group to filter by + * @return the page content + */ SortedMap getGroupHistory(int pageNo, String name); + + /** + * @param name the name to filter by + * @return the max page number allowed in the {@link #getGroupHistory(int, String)} method + */ int getGroupHistoryMaxPages(String name); + + /** + * @param name the name to filter by + * @return all content in this log where the track = name + */ SortedSet getTrackHistory(String name); + + /** + * Gets the track history content, separated by pages + * @param pageNo the page number + * @param name the name of the acted track to filter by + * @return the page content + */ SortedMap getTrackHistory(int pageNo, String name); + + /** + * @param name the name to filter by + * @return the max page number allowed in the {@link #getTrackHistory(int, String)} method + */ int getTrackHistoryMaxPages(String name); + /** + * @param query the query to filter by + * @return all content in this log where the content matches query + */ SortedSet getSearch(String query); + + /** + * Gets the search content, separated by pages + * @param pageNo the page number + * @param query the query to filter by + * @return the page content + */ SortedMap getSearch(int pageNo, String query); + + /** + * @param query the query to filter by + * @return the max page number allowed in the {@link #getSearch(int, String)} method + */ int getSearchMaxPages(String query); } diff --git a/api/src/main/java/me/lucko/luckperms/api/LogEntry.java b/api/src/main/java/me/lucko/luckperms/api/LogEntry.java index e3718758..eee66ee3 100644 --- a/api/src/main/java/me/lucko/luckperms/api/LogEntry.java +++ b/api/src/main/java/me/lucko/luckperms/api/LogEntry.java @@ -24,6 +24,9 @@ package me.lucko.luckperms.api; import java.util.UUID; +/** + * Represents a single entry in a log + */ public class LogEntry implements Comparable { public static LogEntryBuilder builder() { return new LogEntryBuilder(); diff --git a/api/src/main/java/me/lucko/luckperms/api/LuckPermsApi.java b/api/src/main/java/me/lucko/luckperms/api/LuckPermsApi.java index af251ca1..b29199b3 100644 --- a/api/src/main/java/me/lucko/luckperms/api/LuckPermsApi.java +++ b/api/src/main/java/me/lucko/luckperms/api/LuckPermsApi.java @@ -29,7 +29,7 @@ import java.util.Set; import java.util.UUID; /** - * The root Api interface in LuckPerms + * The root API interface in LuckPerms */ @SuppressWarnings("unused") public interface LuckPermsApi { diff --git a/api/src/main/java/me/lucko/luckperms/api/PermissionHolder.java b/api/src/main/java/me/lucko/luckperms/api/PermissionHolder.java index ca3df1b2..d5617a24 100644 --- a/api/src/main/java/me/lucko/luckperms/api/PermissionHolder.java +++ b/api/src/main/java/me/lucko/luckperms/api/PermissionHolder.java @@ -30,15 +30,20 @@ import java.util.Map; /** * 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 PermissionHolder { + /** + * @return the identifier for this object. either a uuid string or name + * However, you should really use {@link User#getUuid()}, {@link User#getName()} or {@link Group#getName()} + */ String getObjectName(); + /** + * Gets an immutable Map of the objects permission nodes + * @return an immutable map of permissions + */ Map getNodes(); /** @@ -46,6 +51,8 @@ public interface PermissionHolder { * @param node The permission node * @param b If the node is true/false(negated) * @return true if the user has the permission + * @throws NullPointerException if the node is null + * @throws IllegalArgumentException if the node is invalid */ boolean hasPermission(String node, boolean b); @@ -55,25 +62,31 @@ public interface PermissionHolder { * @param b If the node is true/false(negated) * @param server The server * @return true if the user has the permission + * @throws NullPointerException if the node or server is null + * @throws IllegalArgumentException if the node or server is invalid */ boolean hasPermission(String node, boolean b, String server); /** - * Checks to see the the object has a permission on a certain server + * Checks to see the the object has a permission on a certain server and world * @param node The permission node * @param b If the node is true/false(negated) * @param server The server * @param world The world * @return true if the user has the permission + * @throws NullPointerException if the node, server or world is null + * @throws IllegalArgumentException if the node, server or world is invalid */ boolean hasPermission(String node, boolean b, String server, String world); /** - * Checks to see the the object has a permission on a certain server + * Checks to see the the object has a permission * @param node The permission node * @param b If the node is true/false(negated) * @param temporary if the permission is temporary * @return true if the user has the permission + * @throws NullPointerException if the node is null + * @throws IllegalArgumentException if the node is invalid */ boolean hasPermission(String node, boolean b, boolean temporary); @@ -84,17 +97,21 @@ public interface PermissionHolder { * @param server The server to check on * @param temporary if the permission is temporary * @return true if the user has the permission + * @throws NullPointerException if the node or server is null + * @throws IllegalArgumentException if the node or server is invalid */ boolean hasPermission(String node, boolean b, String server, boolean temporary); /** - * Checks to see the the object has a permission on a certain server + * Checks to see the the object has a permission on a certain server and world * @param node The permission node * @param b If the node is true/false(negated) * @param server The server to check on * @param world The world to check on * @param temporary if the permission is temporary * @return true if the user has the permission + * @throws NullPointerException if the node, server or world is null + * @throws IllegalArgumentException if the node, server or world is invalud */ boolean hasPermission(String node, boolean b, String server, String world, boolean temporary); @@ -103,6 +120,8 @@ public interface PermissionHolder { * @param node The permission node * @param b If the node is true/false(negated) * @return true if the user inherits the permission + * @throws NullPointerException if the node is null + * @throws IllegalArgumentException if the node is invalid */ boolean inheritsPermission(String node, boolean b); @@ -112,46 +131,56 @@ public interface PermissionHolder { * @param b If the node is true/false(negated) * @param server The server * @return true if the user inherits the permission + * @throws NullPointerException if the node or server is null + * @throws IllegalArgumentException if the node or server is invalid */ boolean inheritsPermission(String node, boolean b, String server); /** - * Checks to see the the object inherits a permission on a certain server + * Checks to see the the object inherits a permission on a certain server and world * @param node The permission node * @param b If the node is true/false(negated) * @param server The server * @param world The world * @return true if the user inherits the permission + * @throws NullPointerException if the node, server or world is null + * @throws IllegalArgumentException if the node server or world is invalid */ boolean inheritsPermission(String node, boolean b, String server, String world); /** - * Checks to see if the object inherits a certain permission + * Checks to see if the object inherits a permission * @param node The permission node * @param b If the node is true/false(negated) * @param temporary if the permission is temporary * @return true if the user inherits the permission + * @throws NullPointerException if the node is null + * @throws IllegalArgumentException if the node is invalid */ boolean inheritsPermission(String node, boolean b, boolean temporary); /** - * Checks to see if the object inherits a certain permission + * Checks to see if the object inherits a permission on a certain server * @param node The permission node * @param b If the node is true/false(negated) * @param server The server * @param temporary if the permission is temporary * @return true if the user inherits the permission + * @throws NullPointerException if the node or server is null + * @throws IllegalArgumentException if the node or server is invalid */ boolean inheritsPermission(String node, boolean b, String server, boolean temporary); /** - * Checks to see if the object inherits a certain permission + * Checks to see if the object inherits a permission on a certain server and world * @param node The permission node * @param b If the node is true/false(negated) * @param server The server * @param world The world * @param temporary if the permission is temporary * @return true if the user inherits the permission + * @throws NullPointerException if the node, server or world is null + * @throws IllegalArgumentException if the node, server or world if invalid */ boolean inheritsPermission(String node, boolean b, String server, String world, boolean temporary); @@ -160,55 +189,67 @@ public interface PermissionHolder { * @param node The node to be set * @param value What to set the node to - true/false(negated) * @throws ObjectAlreadyHasException if the object already has the permission + * @throws NullPointerException if the node is null + * @throws IllegalArgumentException if the node is invalid */ void setPermission(String node, boolean value) throws ObjectAlreadyHasException; /** - * Sets a permission for the object + * Sets a permission for the object on a specific server * @param node The node to set * @param value What to set the node to - true/false(negated) * @param server The server to set the permission on * @throws ObjectAlreadyHasException if the object already has the permission + * @throws NullPointerException if the node or server is null + * @throws IllegalArgumentException if the node or server is invalid */ void setPermission(String node, boolean value, String server) throws ObjectAlreadyHasException; /** - * Sets a permission for the object + * Sets a permission for the object on a specific server and world * @param node The node to set * @param value What to set the node to - true/false(negated) * @param server The server to set the permission on * @param world The world to set the permission on * @throws ObjectAlreadyHasException if the object already has the permission + * @throws NullPointerException if the node, server or world is null + * @throws IllegalArgumentException if the node, server or world is invalid */ void setPermission(String node, boolean value, String server, String world) throws ObjectAlreadyHasException; /** - * Sets a permission for the object + * Sets a temporary permission for the object * @param node The node to set * @param value What to set the node to - true/false(negated) * @param expireAt The time in unixtime when the permission will expire * @throws ObjectAlreadyHasException if the object already has the permission + * @throws NullPointerException if the node is null + * @throws IllegalArgumentException if the node is invalid or if the expiry time is in the past */ void setPermission(String node, boolean value, long expireAt) throws ObjectAlreadyHasException; /** - * Sets a permission for the object + * Sets a temporary permission for the object on a specific server * @param node The node to set * @param value What to set the node to - true/false(negated) * @param server The server to set the permission on * @param expireAt The time in unixtime when the permission will expire * @throws ObjectAlreadyHasException if the object already has the permission + * @throws NullPointerException if the node or server is null + * @throws IllegalArgumentException if the node/server is invalid or if the expiry time is in the past */ void setPermission(String node, boolean value, String server, long expireAt) throws ObjectAlreadyHasException; /** - * Sets a permission for the object + * Sets a temporary permission for the object on a specific server and world * @param node The node to set * @param value What to set the node to - true/false(negated) * @param server The server to set the permission on * @param world The world to set the permission on * @param expireAt The time in unixtime when the permission will expire * @throws ObjectAlreadyHasException if the object already has the permission + * @throws NullPointerException if the node, server or world is null + * @throws IllegalArgumentException if the node/server/world is invalid, or if the expiry time is in the past */ void setPermission(String node, boolean value, String server, String world, long expireAt) throws ObjectAlreadyHasException; @@ -217,6 +258,8 @@ public interface PermissionHolder { * @param node The node to be unset * @param temporary if the permission being removed is temporary * @throws ObjectLacksException if the node wasn't already set + * @throws NullPointerException if the node is null + * @throws IllegalArgumentException if the node is invalid */ void unsetPermission(String node, boolean temporary) throws ObjectLacksException; @@ -224,47 +267,57 @@ public interface PermissionHolder { * Unsets a permission for the object * @param node The node to be unset * @throws ObjectLacksException if the node wasn't already set + * @throws NullPointerException if the node is null + * @throws IllegalArgumentException if the node is invalid */ void unsetPermission(String node) throws ObjectLacksException; /** - * Unsets a permission for the object + * Unsets a permission for the object on a specific server * @param node The node to be unset * @param server The server to unset the node on * @throws ObjectLacksException if the node wasn't already set + * @throws NullPointerException if the node or server is null + * @throws IllegalArgumentException if the node or server is invalid */ void unsetPermission(String node, String server) throws ObjectLacksException; /** - * Unsets a permission for the object + * Unsets a permission for the object on a specific server and world * @param node The node to be unset * @param server The server to unset the node on * @param world The world to unset the node on * @throws ObjectLacksException if the node wasn't already set + * @throws NullPointerException if the node, server or world is null + * @throws IllegalArgumentException if the node, server or world is invalid */ void unsetPermission(String node, String server, String world) throws ObjectLacksException; /** - * Unsets a permission for the object + * Unsets a permission for the object on a specific server * @param node The node to be unset * @param server The server to unset the node on * @param temporary if the permission being unset is temporary * @throws ObjectLacksException if the node wasn't already set + * @throws NullPointerException if the node or server is null + * @throws IllegalArgumentException if the node or server is invalid */ void unsetPermission(String node, String server, boolean temporary) throws ObjectLacksException; /** - * Unsets a permission for the object + * Unsets a permission for the object on a specific server and world * @param node The node to be unset * @param server The server to unset the node on * @param world The world to unset the node on * @param temporary if the permission being unset is temporary * @throws ObjectLacksException if the node wasn't already set + * @throws NullPointerException if the node, server or world is null + * @throws IllegalArgumentException if the node, server or world is invalid */ void unsetPermission(String node, String server, String world, boolean temporary) throws ObjectLacksException; /** - * Gets the permissions and inherited permissions that apply to a specific server + * Gets the permissions and inherited permissions that apply to a specific server and world * @param server The server to get nodes for * @param world The world to get nodes for * @param excludedGroups Groups that shouldn't be inherited (to prevent circular inheritance issues) @@ -274,7 +327,7 @@ public interface PermissionHolder { Map getLocalPermissions(String server, String world, List excludedGroups, List possibleNodes); /** - * Gets the permissions and inherited permissions that apply to a specific server + * Gets the permissions and inherited permissions that apply to a specific server and world * @param server The server to get nodes for * @param world The world to get nodes for * @param excludedGroups Groups that shouldn't be inherited (to prevent circular inheritance issues) @@ -300,13 +353,13 @@ public interface PermissionHolder { Map getLocalPermissions(String server, List excludedGroups); /** - * Processes the objects and returns the temporary ones. + * Processes the nodes and returns the temporary ones. * @return a map of temporary nodes */ Map, Long> getTemporaryNodes(); /** - * Processes the objects and returns the non-temporary ones. + * Processes the nodes and returns the non-temporary ones. * @return a map of permanent nodes */ Map getPermanentNodes(); diff --git a/api/src/main/java/me/lucko/luckperms/api/Track.java b/api/src/main/java/me/lucko/luckperms/api/Track.java index 76fe2d1a..6457e059 100644 --- a/api/src/main/java/me/lucko/luckperms/api/Track.java +++ b/api/src/main/java/me/lucko/luckperms/api/Track.java @@ -29,18 +29,19 @@ import java.util.List; /** * Wrapper interface for internal Track instances - * - *

The implementations of this interface limit access to the Track and add parameter checks to further prevent - * errors and ensure all API interactions to not damage the state of the track. */ @SuppressWarnings("unused") public interface Track { + /** + * @return the name of this track + */ String getName(); /** * Gets an ordered list of the groups on this track - * @return am ordered {@link List} of the groups on this track + * Index 0 is the first/lowest group in (or start of) the track + * @return an ordered {@link List} of the groups on this track */ List getGroups(); @@ -55,14 +56,18 @@ public interface Track { * @param current the group before the group being requested * @return the group name, or null if the end of the track has been reached * @throws ObjectLacksException if the track does not contain the group given + * @throws NullPointerException if the group is null + * @throws IllegalStateException if the group instance was not obtained from LuckPerms. */ String getNext(Group current) throws ObjectLacksException; /** - * Gets the group before the group provided + * Gets the previous group on the track, before the one provided * @param current the group after the group being requested * @return the group name, or null if the start of the track has been reached * @throws ObjectLacksException if the track does not contain the group given + * @throws NullPointerException if the group is null + * @throws IllegalStateException if the group instance was not obtained from LuckPerms. */ String getPrevious(Group current) throws ObjectLacksException; @@ -70,6 +75,8 @@ public interface Track { * Appends a group to the end of this track * @param group the group to append * @throws ObjectAlreadyHasException if the group is already on this track somewhere + * @throws NullPointerException if the group is null + * @throws IllegalStateException if the group instance was not obtained from LuckPerms. */ void appendGroup(Group group) throws ObjectAlreadyHasException; @@ -79,6 +86,8 @@ public interface Track { * @param position the index position (a value of 0 inserts at the start) * @throws ObjectAlreadyHasException if the group is already on this track somewhere * @throws IndexOutOfBoundsException if the position is less than 0 or greater than the size of the track + * @throws NullPointerException if the group is null + * @throws IllegalStateException if the group instance was not obtained from LuckPerms. */ void insertGroup(Group group, int position) throws ObjectAlreadyHasException, IndexOutOfBoundsException; @@ -86,6 +95,8 @@ public interface Track { * Removes a group from this track * @param group the group to remove * @throws ObjectLacksException if the group is not on this track + * @throws NullPointerException if the group is null + * @throws IllegalStateException if the group instance was not obtained from LuckPerms. */ void removeGroup(Group group) throws ObjectLacksException; @@ -93,6 +104,7 @@ public interface Track { * Removes a group from this track * @param group the group to remove * @throws ObjectLacksException if the group is not on this track + * @throws NullPointerException if the group is null */ void removeGroup(String group) throws ObjectLacksException; @@ -100,6 +112,8 @@ public interface Track { * Checks if a group features on this track * @param group the group to check * @return true if the group is on this track + * @throws NullPointerException if the group is null + * @throws IllegalStateException if the group instance was not obtained from LuckPerms. */ boolean containsGroup(Group group); @@ -107,6 +121,7 @@ public interface Track { * Checks if a group features on this track * @param group the group to check * @return true if the group is on this track + * @throws NullPointerException if the group is null */ boolean containsGroup(String group); diff --git a/api/src/main/java/me/lucko/luckperms/api/User.java b/api/src/main/java/me/lucko/luckperms/api/User.java index e12ab60c..34974082 100644 --- a/api/src/main/java/me/lucko/luckperms/api/User.java +++ b/api/src/main/java/me/lucko/luckperms/api/User.java @@ -30,9 +30,6 @@ import java.util.UUID; /** * Wrapper interface for internal User instances - * - *

The implementations of this interface limit access to the User and add parameter checks to further prevent - * errors and ensure all API interactions to not damage the state of the user. */ @SuppressWarnings("unused") public interface User extends PermissionHolder { @@ -55,10 +52,12 @@ public interface User extends PermissionHolder { /** * Sets a users primary group - * @param s the new primary group + * @param group the new primary group * @throws ObjectAlreadyHasException if the user already has this set as their primary group + * @throws IllegalStateException if the user is not a member of that group + * @throws NullPointerException if the group is null */ - void setPrimaryGroup(String s) throws ObjectAlreadyHasException; + void setPrimaryGroup(String group) throws ObjectAlreadyHasException; /** * Refresh and re-assign the users permissions @@ -69,6 +68,7 @@ public interface User extends PermissionHolder { * Check to see if the user is a member of a group * @param group The group to check membership of * @return true if the user is a member of the group + * @throws NullPointerException if the group is null */ boolean isInGroup(Group group); @@ -77,15 +77,19 @@ public interface User extends PermissionHolder { * @param group The group to check membership of * @param server The server to check on * @return true if the user is a member of the group + * @throws NullPointerException if the group or server is null + * @throws IllegalArgumentException if the server is invalid */ boolean isInGroup(Group group, String server); /** - * Check to see if a user is a member of a group on a specific server + * Check to see if a user is a member of a group on a specific server and world * @param group The group to check membership of * @param server The server to check on * @param world The world to check on * @return true if the user is a member of the group + * @throws NullPointerException if the group, server or world is null + * @throws IllegalArgumentException if the server or world is invalid */ boolean isInGroup(Group group, String server, String world); @@ -93,6 +97,8 @@ public interface User extends PermissionHolder { * Add a user to a group * @param group The group to add the user to * @throws ObjectAlreadyHasException if the user is already a member of the group + * @throws NullPointerException if the group is null + * @throws IllegalStateException if the group instance was not obtained from LuckPerms. */ void addGroup(Group group) throws ObjectAlreadyHasException; @@ -101,42 +107,57 @@ public interface User extends PermissionHolder { * @param group The group to add the user to * @param server The server to add the group on * @throws ObjectAlreadyHasException if the user is already a member of the group on that server + * @throws NullPointerException if the group or server is null + * @throws IllegalStateException if the group instance was not obtained from LuckPerms. + * @throws IllegalArgumentException if the server is invalid */ void addGroup(Group group, String server) throws ObjectAlreadyHasException; /** - * Add a user to a group on a specific server + * Add a user to a group on a specific server and world * @param group The group to add the user to * @param server The server to add the group on * @param world The world to add the group on * @throws ObjectAlreadyHasException if the user is already a member of the group on that server + * @throws NullPointerException if the group, server or world is null + * @throws IllegalStateException if the group instance was not obtained from LuckPerms. + * @throws IllegalArgumentException if the server or world is invalid */ void addGroup(Group group, String server, String world) throws ObjectAlreadyHasException; /** - * Add a user to a group on a specific server + * Add a user to a group temporarily on a specific server * @param group The group to add the user to * @param expireAt when the group should expire * @throws ObjectAlreadyHasException if the user is already a member of the group on that server + * @throws NullPointerException if the group is null + * @throws IllegalStateException if the group instance was not obtained from LuckPerms. + * @throws IllegalArgumentException if the expiry time is in the past */ void addGroup(Group group, long expireAt) throws ObjectAlreadyHasException; /** - * Add a user to a group on a specific server + * Add a user to a group temporarily on a specific server * @param group The group to add the user to * @param server The server to add the group on * @param expireAt when the group should expire * @throws ObjectAlreadyHasException if the user is already a member of the group on that server + * @throws NullPointerException if the group or server is null + * @throws IllegalStateException if the group instance was not obtained from LuckPerms. + * @throws IllegalArgumentException if the expiry time is in the past or the server is invalid */ void addGroup(Group group, String server, long expireAt) throws ObjectAlreadyHasException; /** - * Add a user to a group on a specific server + * Add a user to a group temporarily on a specific server and world * @param group The group to add the user to * @param server The server to add the group on * @param world The world to add the group on * @param expireAt when the group should expire * @throws ObjectAlreadyHasException if the user is already a member of the group on that server + * @throws NullPointerException if the group, server or world is null + * @throws IllegalStateException if the group instance was not obtained from LuckPerms. + * @throws IllegalArgumentException if the expiry time is in the past or the server/world is invalid */ void addGroup(Group group, String server, String world, long expireAt) throws ObjectAlreadyHasException; @@ -144,6 +165,8 @@ public interface User extends PermissionHolder { * Remove the user from a group * @param group the group to remove the user from * @throws ObjectLacksException if the user isn't a member of the group + * @throws NullPointerException if the group is null + * @throws IllegalStateException if the group instance was not obtained from LuckPerms. */ void removeGroup(Group group) throws ObjectLacksException; @@ -152,42 +175,56 @@ public interface User extends PermissionHolder { * @param group the group to remove the user from * @param temporary if the group being removed is temporary * @throws ObjectLacksException if the user isn't a member of the group + * @throws NullPointerException if the group is null + * @throws IllegalStateException if the group instance was not obtained from LuckPerms. */ void removeGroup(Group group, boolean temporary) throws ObjectLacksException; /** - * Remove the user from a group + * Remove the user from a group on a specific server * @param group The group to remove the user from * @param server The server to remove the group on * @throws ObjectLacksException if the user isn't a member of the group + * @throws NullPointerException if the group or server is null + * @throws IllegalStateException if the group instance was not obtained from LuckPerms. + * @throws IllegalArgumentException if the server is invalid */ void removeGroup(Group group, String server) throws ObjectLacksException; /** - * Remove the user from a group + * Remove the user from a group on a specific server and world * @param group The group to remove the user from * @param server The server to remove the group on * @param world The world to remove the group on * @throws ObjectLacksException if the user isn't a member of the group + * @throws NullPointerException if the group, server or world is null + * @throws IllegalStateException if the group instance was not obtained from LuckPerms. + * @throws IllegalArgumentException if the server or world is invalid */ void removeGroup(Group group, String server, String world) throws ObjectLacksException; /** - * Remove the user from a group + * Remove the user from a group on a specific server * @param group The group to remove the user from * @param server The server to remove the group on * @param temporary if the group being removed is temporary * @throws ObjectLacksException if the user isn't a member of the group + * @throws NullPointerException if the group or server is null + * @throws IllegalStateException if the group instance was not obtained from LuckPerms. + * @throws IllegalArgumentException if the expiry time is in the past or the server is invalid */ void removeGroup(Group group, String server, boolean temporary) throws ObjectLacksException; /** - * Remove the user from a group + * Remove the user from a group on a specific server and world * @param group The group to remove the user from * @param server The server to remove the group on * @param world The world to remove the group on * @param temporary if the group being removed is temporary * @throws ObjectLacksException if the user isn't a member of the group + * @throws NullPointerException if the group, server or world is null + * @throws IllegalStateException if the group instance was not obtained from LuckPerms. + * @throws IllegalArgumentException if the expiry time is in the past or the server/world is invalid */ void removeGroup(Group group, String server, String world, boolean temporary) throws ObjectLacksException; @@ -207,6 +244,8 @@ public interface User extends PermissionHolder { * @param server the server to check * @param world the world to check * @return a {@link List} of group names + * @throws NullPointerException if the server or world is null + * @throws IllegalArgumentException if the server or world is invalid */ List getLocalGroups(String server, String world); @@ -214,6 +253,8 @@ public interface User extends PermissionHolder { * Get a {@link List} of the groups the user is a member of on a specific server * @param server the server to check * @return a {@link List} of group names + * @throws NullPointerException if the server is null + * @throws IllegalArgumentException if the server is invalid */ List getLocalGroups(String server); diff --git a/api/src/main/java/me/lucko/luckperms/api/data/Callback.java b/api/src/main/java/me/lucko/luckperms/api/data/Callback.java index 9087c97d..050592be 100644 --- a/api/src/main/java/me/lucko/luckperms/api/data/Callback.java +++ b/api/src/main/java/me/lucko/luckperms/api/data/Callback.java @@ -24,8 +24,17 @@ package me.lucko.luckperms.api.data; import java.util.function.Consumer; +/** + * A callback used to wait for the completion of asynchronous operations. + * All callbacks are ran on the main Bukkit server thread. + * @param the return type + */ public interface Callback { + /** + * Called when the operation completes. + * @param t the return value, may be null + */ void onComplete(T t); static Callback empty() { diff --git a/api/src/main/java/me/lucko/luckperms/api/data/DatastoreConfiguration.java b/api/src/main/java/me/lucko/luckperms/api/data/DatastoreConfiguration.java index 4db0a188..c10c2fb6 100644 --- a/api/src/main/java/me/lucko/luckperms/api/data/DatastoreConfiguration.java +++ b/api/src/main/java/me/lucko/luckperms/api/data/DatastoreConfiguration.java @@ -22,6 +22,10 @@ package me.lucko.luckperms.api.data; +/** + * Represents the data section of the main LuckPerms configuration. + * All methods could return null. + */ @SuppressWarnings("deprecation") public interface DatastoreConfiguration extends MySQLConfiguration { diff --git a/api/src/main/java/me/lucko/luckperms/api/event/AbstractPermissionRemoveEvent.java b/api/src/main/java/me/lucko/luckperms/api/event/AbstractPermissionRemoveEvent.java index a9304008..daa26636 100644 --- a/api/src/main/java/me/lucko/luckperms/api/event/AbstractPermissionRemoveEvent.java +++ b/api/src/main/java/me/lucko/luckperms/api/event/AbstractPermissionRemoveEvent.java @@ -47,8 +47,16 @@ public class AbstractPermissionRemoveEvent extends TargetedEvent the target type + */ public class TargetedEvent extends LPEvent { private final T target; diff --git a/api/src/main/java/me/lucko/luckperms/api/event/UserEvent.java b/api/src/main/java/me/lucko/luckperms/api/event/UserEvent.java index 435c41ee..80225181 100644 --- a/api/src/main/java/me/lucko/luckperms/api/event/UserEvent.java +++ b/api/src/main/java/me/lucko/luckperms/api/event/UserEvent.java @@ -24,6 +24,9 @@ package me.lucko.luckperms.api.event; import me.lucko.luckperms.api.User; +/** + * Represents an event acting upon a user. + */ public class UserEvent extends LPEvent { private final User user; diff --git a/api/src/main/java/me/lucko/luckperms/api/event/events/GroupAddEvent.java b/api/src/main/java/me/lucko/luckperms/api/event/events/GroupAddEvent.java index 0d4836fa..c02a1adc 100644 --- a/api/src/main/java/me/lucko/luckperms/api/event/events/GroupAddEvent.java +++ b/api/src/main/java/me/lucko/luckperms/api/event/events/GroupAddEvent.java @@ -26,8 +26,14 @@ import me.lucko.luckperms.api.Group; import me.lucko.luckperms.api.PermissionHolder; import me.lucko.luckperms.api.event.AbstractPermissionAddEvent; +/** + * Called whenever a user or group is added to / starts to inherit another group + */ public class GroupAddEvent extends AbstractPermissionAddEvent { + /** + * The group being added to the target + */ private final Group group; public GroupAddEvent(PermissionHolder target, Group group, String server, String world, long expiry) { diff --git a/api/src/main/java/me/lucko/luckperms/api/event/events/GroupRemoveEvent.java b/api/src/main/java/me/lucko/luckperms/api/event/events/GroupRemoveEvent.java index 358035b3..f44a74a7 100644 --- a/api/src/main/java/me/lucko/luckperms/api/event/events/GroupRemoveEvent.java +++ b/api/src/main/java/me/lucko/luckperms/api/event/events/GroupRemoveEvent.java @@ -25,8 +25,15 @@ package me.lucko.luckperms.api.event.events; import me.lucko.luckperms.api.PermissionHolder; import me.lucko.luckperms.api.event.AbstractPermissionRemoveEvent; +/** + * Called whenever a user or group is removed from / stops inheriting another group + */ public class GroupRemoveEvent extends AbstractPermissionRemoveEvent { + /** + * The name of group being removed from the target. + * Be aware that this group may have already been deleted, and and instance may therefore not exist internally. + */ private final String group; public GroupRemoveEvent(PermissionHolder target, String group, String server, String world, boolean temporary) { diff --git a/api/src/main/java/me/lucko/luckperms/api/event/events/LogNotifyEvent.java b/api/src/main/java/me/lucko/luckperms/api/event/events/LogNotifyEvent.java index 6cfd6679..da5cc1d5 100644 --- a/api/src/main/java/me/lucko/luckperms/api/event/events/LogNotifyEvent.java +++ b/api/src/main/java/me/lucko/luckperms/api/event/events/LogNotifyEvent.java @@ -25,8 +25,16 @@ package me.lucko.luckperms.api.event.events; import me.lucko.luckperms.api.LogEntry; import me.lucko.luckperms.api.event.CancellableEvent; +/** + * Called before a LogEntry is broadcasted to players only with the notify permission. + * The log entry will still be recorded in the datastore, regardless of the cancellation state of this event. + * Cancelling this event only stops the broadcast. + */ public class LogNotifyEvent extends CancellableEvent { + /** + * The log entry to be broadcasted + */ private final LogEntry entry; public LogNotifyEvent(LogEntry entry) { diff --git a/api/src/main/java/me/lucko/luckperms/api/event/events/PermissionExpireEvent.java b/api/src/main/java/me/lucko/luckperms/api/event/events/PermissionExpireEvent.java index 4a474f3d..5f1bca90 100644 --- a/api/src/main/java/me/lucko/luckperms/api/event/events/PermissionExpireEvent.java +++ b/api/src/main/java/me/lucko/luckperms/api/event/events/PermissionExpireEvent.java @@ -25,6 +25,9 @@ package me.lucko.luckperms.api.event.events; import me.lucko.luckperms.api.PermissionHolder; import me.lucko.luckperms.api.event.TargetedEvent; +/** + * Called when a permission expires for an object. + */ public class PermissionExpireEvent extends TargetedEvent { private final String node; diff --git a/api/src/main/java/me/lucko/luckperms/api/event/events/PermissionSetEvent.java b/api/src/main/java/me/lucko/luckperms/api/event/events/PermissionSetEvent.java index b0b4b97e..66a30ba5 100644 --- a/api/src/main/java/me/lucko/luckperms/api/event/events/PermissionSetEvent.java +++ b/api/src/main/java/me/lucko/luckperms/api/event/events/PermissionSetEvent.java @@ -28,6 +28,9 @@ import me.lucko.luckperms.api.event.AbstractPermissionAddEvent; import java.util.AbstractMap; import java.util.Map; +/** + * Called whenever a user or group has a permission set. + */ public class PermissionSetEvent extends AbstractPermissionAddEvent { private final String node; diff --git a/api/src/main/java/me/lucko/luckperms/api/event/events/PermissionUnsetEvent.java b/api/src/main/java/me/lucko/luckperms/api/event/events/PermissionUnsetEvent.java index d7b2738e..65db10c1 100644 --- a/api/src/main/java/me/lucko/luckperms/api/event/events/PermissionUnsetEvent.java +++ b/api/src/main/java/me/lucko/luckperms/api/event/events/PermissionUnsetEvent.java @@ -25,6 +25,9 @@ package me.lucko.luckperms.api.event.events; import me.lucko.luckperms.api.PermissionHolder; import me.lucko.luckperms.api.event.AbstractPermissionRemoveEvent; +/** + * Called whenever a user or group has a permission unset. + */ public class PermissionUnsetEvent extends AbstractPermissionRemoveEvent { private final String node; diff --git a/api/src/main/java/me/lucko/luckperms/api/event/events/PostSyncEvent.java b/api/src/main/java/me/lucko/luckperms/api/event/events/PostSyncEvent.java index a41e0190..1dcec295 100644 --- a/api/src/main/java/me/lucko/luckperms/api/event/events/PostSyncEvent.java +++ b/api/src/main/java/me/lucko/luckperms/api/event/events/PostSyncEvent.java @@ -24,6 +24,9 @@ package me.lucko.luckperms.api.event.events; import me.lucko.luckperms.api.event.LPEvent; +/** + * Called after the sync task has ran. + */ public class PostSyncEvent extends LPEvent { public PostSyncEvent() { diff --git a/api/src/main/java/me/lucko/luckperms/api/event/events/PreSyncEvent.java b/api/src/main/java/me/lucko/luckperms/api/event/events/PreSyncEvent.java index a3817bef..126ca3e0 100644 --- a/api/src/main/java/me/lucko/luckperms/api/event/events/PreSyncEvent.java +++ b/api/src/main/java/me/lucko/luckperms/api/event/events/PreSyncEvent.java @@ -24,6 +24,10 @@ package me.lucko.luckperms.api.event.events; import me.lucko.luckperms.api.event.CancellableEvent; +/** + * Called before the sync task is about to run. + * Set this event to cancelled to prevent the sync task from running. + */ public class PreSyncEvent extends CancellableEvent { public PreSyncEvent() { diff --git a/api/src/main/java/me/lucko/luckperms/api/event/events/UserDemoteEvent.java b/api/src/main/java/me/lucko/luckperms/api/event/events/UserDemoteEvent.java index 8902290f..acaed456 100644 --- a/api/src/main/java/me/lucko/luckperms/api/event/events/UserDemoteEvent.java +++ b/api/src/main/java/me/lucko/luckperms/api/event/events/UserDemoteEvent.java @@ -26,6 +26,9 @@ import me.lucko.luckperms.api.Track; import me.lucko.luckperms.api.User; import me.lucko.luckperms.api.event.TrackEvent; +/** + * Called whenever a user is demoted down a track + */ public class UserDemoteEvent extends TrackEvent { public UserDemoteEvent(Track track, User user, String from, String to) { diff --git a/api/src/main/java/me/lucko/luckperms/api/event/events/UserFirstLoginEvent.java b/api/src/main/java/me/lucko/luckperms/api/event/events/UserFirstLoginEvent.java index d0562ce6..ed7a9feb 100644 --- a/api/src/main/java/me/lucko/luckperms/api/event/events/UserFirstLoginEvent.java +++ b/api/src/main/java/me/lucko/luckperms/api/event/events/UserFirstLoginEvent.java @@ -27,7 +27,10 @@ import me.lucko.luckperms.api.event.LPEvent; import java.util.UUID; /** - * This event is fired before the player has actually joined the game on the async login / auth event. + * Called when the user logs into the network for the first time. + * Particularly useful for networks with multiple lobbies, who want to welcome a user when they join for the first time. + * + *

This event is fired before the player has actually joined the game on the async login / auth event. * If you want to do something with the user, store the UUID in a set, and then check the set in the PlayerJoinEvent o.e. */ public class UserFirstLoginEvent extends LPEvent { diff --git a/api/src/main/java/me/lucko/luckperms/api/event/events/UserPermissionRefreshEvent.java b/api/src/main/java/me/lucko/luckperms/api/event/events/UserPermissionRefreshEvent.java index 60bb8cd8..4899aca6 100644 --- a/api/src/main/java/me/lucko/luckperms/api/event/events/UserPermissionRefreshEvent.java +++ b/api/src/main/java/me/lucko/luckperms/api/event/events/UserPermissionRefreshEvent.java @@ -25,6 +25,10 @@ package me.lucko.luckperms.api.event.events; import me.lucko.luckperms.api.User; import me.lucko.luckperms.api.event.UserEvent; +/** + * Called after a user has their permissions refreshed. + * If you cache user permissions within your own plugin, it's a good idea to update said cache whenever this event is called. + */ public class UserPermissionRefreshEvent extends UserEvent { public UserPermissionRefreshEvent(User user) { diff --git a/api/src/main/java/me/lucko/luckperms/api/event/events/UserPromoteEvent.java b/api/src/main/java/me/lucko/luckperms/api/event/events/UserPromoteEvent.java index 7bd38156..fa77972b 100644 --- a/api/src/main/java/me/lucko/luckperms/api/event/events/UserPromoteEvent.java +++ b/api/src/main/java/me/lucko/luckperms/api/event/events/UserPromoteEvent.java @@ -26,6 +26,9 @@ import me.lucko.luckperms.api.Track; import me.lucko.luckperms.api.User; import me.lucko.luckperms.api.event.TrackEvent; +/** + * Called whenever a user is promoted up a track + */ public class UserPromoteEvent extends TrackEvent { public UserPromoteEvent(Track track, User user, String from, String to) { diff --git a/common/src/main/java/me/lucko/luckperms/api/implementation/internal/UserLink.java b/common/src/main/java/me/lucko/luckperms/api/implementation/internal/UserLink.java index 313c12de..ec370fd2 100644 --- a/common/src/main/java/me/lucko/luckperms/api/implementation/internal/UserLink.java +++ b/common/src/main/java/me/lucko/luckperms/api/implementation/internal/UserLink.java @@ -66,7 +66,7 @@ public class UserLink extends PermissionHolderLink implements User { } @Override - public void setPrimaryGroup(String s) throws ObjectAlreadyHasException { + public void setPrimaryGroup(@NonNull String s) throws ObjectAlreadyHasException { if (getPrimaryGroup().equalsIgnoreCase(s)) { throw new ObjectAlreadyHasException(); } diff --git a/common/src/main/java/me/lucko/luckperms/api/implementation/internal/Utils.java b/common/src/main/java/me/lucko/luckperms/api/implementation/internal/Utils.java index af67f2ff..e43a7c17 100644 --- a/common/src/main/java/me/lucko/luckperms/api/implementation/internal/Utils.java +++ b/common/src/main/java/me/lucko/luckperms/api/implementation/internal/Utils.java @@ -33,19 +33,19 @@ class Utils { static void checkUser(User user) { if (!(user instanceof UserLink)) { - throw new IllegalArgumentException("User instance cannot be handled by this implementation."); + throw new IllegalStateException("User instance cannot be handled by this implementation."); } } static void checkGroup(Group group) { if (!(group instanceof GroupLink)) { - throw new IllegalArgumentException("Group instance cannot be handled by this implementation."); + throw new IllegalStateException("Group instance cannot be handled by this implementation."); } } static void checkTrack(Track track) { if (!(track instanceof TrackLink)) { - throw new IllegalArgumentException("Track instance cannot be handled by this implementation."); + throw new IllegalStateException("Track instance cannot be handled by this implementation."); } }