worldofcraft/LuckPerms-DBA
10
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Improvements to the JavaDocs in the API

Browse Source
This commit is contained in:
Luck 2016-08-22 15:50:20 +01:00
parent 692bf30cf5
commit f7baf67985
No known key found for this signature in database
GPG Key ID: EFA9B3EC5FD90F8B
30 changed files with 607 additions and 106 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

213
api/src/main/java/me/lucko/luckperms/api/Datastore.java
View File

@ -28,9 +28,6 @@ import java.util.UUID;
/**
* Wrapper interface for the internal Datastore instance
*
* <p> 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 <code>null</code> 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<Boolean> callback);
void getLog(Callback<Log> callback);
@ -62,26 +240,13 @@ public interface Datastore {
void getUUID(String username, Callback<UUID> 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<Boolean> logAction(LogEntry entry);
java.util.concurrent.Future<Log> getLog();

106
api/src/main/java/me/lucko/luckperms/api/Group.java
View File

@ -29,9 +29,6 @@ import java.util.List;
/**
* Wrapper interface for internal Group instances
*
* <p> 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<String> 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<String> getLocalGroups(String server);
}

1
api/src/main/java/me/lucko/luckperms/api/LPConfiguration.java
View File

@ -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 {
/**

99
api/src/main/java/me/lucko/luckperms/api/Log.java
View File

@ -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<LogEntry> getContent();
/**
* @return all content in this log
*/
SortedSet<LogEntry> getRecent();
/**
* Gets the recent content separated by page
* @param pageNo the page number
* @return the page content
*/
SortedMap<Integer, LogEntry> 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<LogEntry> 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<Integer, LogEntry> 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<LogEntry> 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<Integer, LogEntry> 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<LogEntry> 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<Integer, LogEntry> 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<LogEntry> 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<Integer, LogEntry> 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<LogEntry> 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<Integer, LogEntry> 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);
}

3
api/src/main/java/me/lucko/luckperms/api/LogEntry.java
View File

@ -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<LogEntry> {
public static LogEntryBuilder builder() {
return new LogEntryBuilder();

2
api/src/main/java/me/lucko/luckperms/api/LuckPermsApi.java
View File

@ -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 {

99
api/src/main/java/me/lucko/luckperms/api/PermissionHolder.java
View File

@ -30,15 +30,20 @@ import java.util.Map;
/**
* Wrapper interface for internal PermissionHolder (user/group) instances
*
* <p> 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<String, Boolean> 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<String, Boolean> getLocalPermissions(String server, String world, List<String> excludedGroups, List<String> 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<String, Boolean> getLocalPermissions(String server, List<String> excludedGroups);
/**
* Processes the objects and returns the temporary ones.
* Processes the nodes and returns the temporary ones.
* @return a map of temporary nodes
*/
Map<Map.Entry<String, Boolean>, 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<String, Boolean> getPermanentNodes();

25
api/src/main/java/me/lucko/luckperms/api/Track.java
View File

@ -29,18 +29,19 @@ import java.util.List;
/**
* Wrapper interface for internal Track instances
*
* <p> 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<String> 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);

69
api/src/main/java/me/lucko/luckperms/api/User.java
View File

@ -30,9 +30,6 @@ import java.util.UUID;
/**
* Wrapper interface for internal User instances
*
* <p> 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<String> 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<String> getLocalGroups(String server);

9
api/src/main/java/me/lucko/luckperms/api/data/Callback.java
View File

@ -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 <T> the return type
*/
public interface Callback<T> {
/**
* Called when the operation completes.
* @param t the return value, may be null
*/
void onComplete(T t);
static <T> Callback<T> empty() {

4
api/src/main/java/me/lucko/luckperms/api/data/DatastoreConfiguration.java
View File

@ -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 {

8
api/src/main/java/me/lucko/luckperms/api/event/AbstractPermissionRemoveEvent.java
View File

@ -47,8 +47,16 @@ public class AbstractPermissionRemoveEvent extends TargetedEvent<PermissionHolde
return Optional.ofNullable(world);
}
/**
* @deprecated use {@link #isTemporary()}
*/
@Deprecated
public boolean getTemporary() {
return temporary;
}
public boolean isTemporary() {
return temporary;
}
}

5
api/src/main/java/me/lucko/luckperms/api/event/CancellableEvent.java
View File

@ -22,7 +22,10 @@
package me.lucko.luckperms.api.event;
public class CancellableEvent extends LPEvent {
/**
* Event that allows listeners to set the cancelled state of an event.
*/
public abstract class CancellableEvent extends LPEvent {
private boolean cancelled = false;

3
api/src/main/java/me/lucko/luckperms/api/event/LPEvent.java
View File

@ -24,6 +24,9 @@ package me.lucko.luckperms.api.event;
import me.lucko.luckperms.api.LuckPermsApi;
/**
* Abstract LuckPerms Event class.
*/
public abstract class LPEvent {
/**

4
api/src/main/java/me/lucko/luckperms/api/event/TargetedEvent.java
View File

@ -22,6 +22,10 @@
package me.lucko.luckperms.api.event;
/**
* Represents an event acting upon a target
* @param <T> the target type
*/
public class TargetedEvent<T> extends LPEvent {
private final T target;

3
api/src/main/java/me/lucko/luckperms/api/event/UserEvent.java
View File

@ -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;

6
api/src/main/java/me/lucko/luckperms/api/event/events/GroupAddEvent.java
View File

@ -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) {

7
api/src/main/java/me/lucko/luckperms/api/event/events/GroupRemoveEvent.java
View File

@ -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) {

8
api/src/main/java/me/lucko/luckperms/api/event/events/LogNotifyEvent.java
View File

@ -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) {

3
api/src/main/java/me/lucko/luckperms/api/event/events/PermissionExpireEvent.java
View File

@ -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<PermissionHolder> {
private final String node;

3
api/src/main/java/me/lucko/luckperms/api/event/events/PermissionSetEvent.java
View File

@ -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;

3
api/src/main/java/me/lucko/luckperms/api/event/events/PermissionUnsetEvent.java
View File

@ -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;

3
api/src/main/java/me/lucko/luckperms/api/event/events/PostSyncEvent.java
View File

@ -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() {

4
api/src/main/java/me/lucko/luckperms/api/event/events/PreSyncEvent.java
View File

@ -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() {

3
api/src/main/java/me/lucko/luckperms/api/event/events/UserDemoteEvent.java
View File

@ -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) {

5
api/src/main/java/me/lucko/luckperms/api/event/events/UserFirstLoginEvent.java
View File

@ -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.
*
* <p>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 {

4
api/src/main/java/me/lucko/luckperms/api/event/events/UserPermissionRefreshEvent.java
View File

@ -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) {

3
api/src/main/java/me/lucko/luckperms/api/event/events/UserPromoteEvent.java
View File

@ -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) {

2
common/src/main/java/me/lucko/luckperms/api/implementation/internal/UserLink.java
View File

@ -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();
}

6
common/src/main/java/me/lucko/luckperms/api/implementation/internal/Utils.java
View File

@ -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.");
}
}