Ideally, the ServiceManager for the platform should be used to obtain and cache an instance, however, this can be - * used if you need static access. + *
Ideally, the ServiceManager for the platform should be used to obtain and cache an instance, however, this can be + * used if you need static access.
*/ public final class LuckPerms { private static LuckPermsApi api = null; diff --git a/api/src/main/java/me/lucko/luckperms/api/Contexts.java b/api/src/main/java/me/lucko/luckperms/api/Contexts.java index ae272883a..1326909cf 100644 --- a/api/src/main/java/me/lucko/luckperms/api/Contexts.java +++ b/api/src/main/java/me/lucko/luckperms/api/Contexts.java @@ -27,7 +27,7 @@ import me.lucko.luckperms.api.context.ContextSet; /** * Context and options for a permission lookup. * - *All values are immutable. + *
All values are immutable.
* * @since 2.11 */ diff --git a/common/src/main/java/me/lucko/luckperms/common/core/DataMutateResult.java b/api/src/main/java/me/lucko/luckperms/api/DataMutateResult.java similarity index 89% rename from common/src/main/java/me/lucko/luckperms/common/core/DataMutateResult.java rename to api/src/main/java/me/lucko/luckperms/api/DataMutateResult.java index 673b134ef..05f587ca9 100644 --- a/common/src/main/java/me/lucko/luckperms/common/core/DataMutateResult.java +++ b/api/src/main/java/me/lucko/luckperms/api/DataMutateResult.java @@ -20,16 +20,13 @@ * SOFTWARE. */ -package me.lucko.luckperms.common.core; - -import lombok.AllArgsConstructor; +package me.lucko.luckperms.api; import me.lucko.luckperms.exceptions.ObjectAlreadyHasException; import me.lucko.luckperms.exceptions.ObjectLacksException; import java.util.function.Supplier; -@AllArgsConstructor public enum DataMutateResult { SUCCESS(true, null), @@ -37,9 +34,14 @@ public enum DataMutateResult { LACKS(false, ObjectLacksException::new), FAIL(false, RuntimeException::new); - private boolean bool; + private boolean value; private final Supplier exceptionSupplier; + DataMutateResult(boolean value, Supplier exceptionSupplier) { + this.value = value; + this.exceptionSupplier = exceptionSupplier; + } + public void throwException() { if (exceptionSupplier != null) { sneakyThrow(exceptionSupplier.get()); @@ -47,7 +49,7 @@ public enum DataMutateResult { } public boolean asBoolean() { - return bool; + return value; } // allows us to throw checked exceptions without declaring it, as #throwException throws a number of 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 bad6ed0da..c9595c2a0 100644 --- a/api/src/main/java/me/lucko/luckperms/api/Group.java +++ b/api/src/main/java/me/lucko/luckperms/api/Group.java @@ -82,7 +82,9 @@ public interface Group extends PermissionHolder { * @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. + * @deprecated in favour of {@link NodeFactory#makeGroupNode(Group)} */ + @Deprecated void setInheritGroup(Group group) throws ObjectAlreadyHasException; /** @@ -94,7 +96,9 @@ public interface Group extends PermissionHolder { * @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 + * @deprecated in favour of {@link NodeFactory#makeGroupNode(Group)} */ + @Deprecated void setInheritGroup(Group group, String server) throws ObjectAlreadyHasException; /** @@ -107,7 +111,9 @@ public interface Group extends PermissionHolder { * @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 + * @deprecated in favour of {@link NodeFactory#makeGroupNode(Group)} */ + @Deprecated void setInheritGroup(Group group, String server, String world) throws ObjectAlreadyHasException; /** @@ -119,7 +125,9 @@ public interface Group extends PermissionHolder { * @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 + * @deprecated in favour of {@link NodeFactory#makeGroupNode(Group)} */ + @Deprecated void setInheritGroup(Group group, long expireAt) throws ObjectAlreadyHasException; /** @@ -132,7 +140,9 @@ public interface Group extends PermissionHolder { * @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 + * @deprecated in favour of {@link NodeFactory#makeGroupNode(Group)} */ + @Deprecated void setInheritGroup(Group group, String server, long expireAt) throws ObjectAlreadyHasException; /** @@ -146,7 +156,9 @@ public interface Group extends PermissionHolder { * @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 + * @deprecated in favour of {@link NodeFactory#makeGroupNode(Group)} */ + @Deprecated void setInheritGroup(Group group, String server, String world, long expireAt) throws ObjectAlreadyHasException; /** @@ -156,7 +168,9 @@ public interface Group extends PermissionHolder { * @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. + * @deprecated in favour of {@link NodeFactory#makeGroupNode(Group)} */ + @Deprecated void unsetInheritGroup(Group group) throws ObjectLacksException; /** @@ -167,7 +181,9 @@ public interface Group extends PermissionHolder { * @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. + * @deprecated in favour of {@link NodeFactory#makeGroupNode(Group)} */ + @Deprecated void unsetInheritGroup(Group group, boolean temporary) throws ObjectLacksException; /** @@ -179,7 +195,9 @@ public interface Group extends PermissionHolder { * @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 + * @deprecated in favour of {@link NodeFactory#makeGroupNode(Group)} */ + @Deprecated void unsetInheritGroup(Group group, String server) throws ObjectLacksException; /** @@ -192,7 +210,9 @@ public interface Group extends PermissionHolder { * @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 + * @deprecated in favour of {@link NodeFactory#makeGroupNode(Group)} */ + @Deprecated void unsetInheritGroup(Group group, String server, String world) throws ObjectLacksException; /** @@ -205,7 +225,9 @@ public interface Group extends PermissionHolder { * @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 + * @deprecated in favour of {@link NodeFactory#makeGroupNode(Group)} */ + @Deprecated void unsetInheritGroup(Group group, String server, boolean temporary) throws ObjectLacksException; /** @@ -219,7 +241,9 @@ public interface Group extends PermissionHolder { * @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 + * @deprecated in favour of {@link NodeFactory#makeGroupNode(Group)} */ + @Deprecated void unsetInheritGroup(Group group, String server, String world, boolean temporary) throws ObjectLacksException; /** 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 b66964d0a..bc0afca6e 100644 --- a/api/src/main/java/me/lucko/luckperms/api/Log.java +++ b/api/src/main/java/me/lucko/luckperms/api/Log.java @@ -29,8 +29,8 @@ import java.util.UUID; /** * Represents the internal LuckPerms log. * - *The returned instance provides a copy of the data at the time of retrieval. Any changes made to log entries will - * only apply to this instance of the log. You can add to the log using the {@link Storage}, and then request an updated copy. + *
The returned instance provides a copy of the data at the time of retrieval. Any changes made to log entries will + * only apply to this instance of the log. You can add to the log using the {@link Storage}, and then request an updated copy.
*/ public interface Log { 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 46cfcf6c1..fbdfe6dc5 100644 --- a/api/src/main/java/me/lucko/luckperms/api/LogEntry.java +++ b/api/src/main/java/me/lucko/luckperms/api/LogEntry.java @@ -27,7 +27,7 @@ import java.util.UUID; /** * A single entry in the log * - *Implements {@link Comparable} ordering based upon the timestamp of the entry. + *
Implements {@link Comparable} ordering based upon the timestamp of the entry.
*/ public class LogEntry implements ComparableBukkit/Bungee both use java.util.logging, and Sponge uses org.slf4j. This class wraps those classes so the - * commons module can access a logger. + *
Bukkit/Bungee both use java.util.logging, and Sponge uses org.slf4j. This class wraps those classes so the + * commons module can access a logger.
*/ public interface Logger { 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 112006362..891b1a1e1 100644 --- a/api/src/main/java/me/lucko/luckperms/api/LuckPermsApi.java +++ b/api/src/main/java/me/lucko/luckperms/api/LuckPermsApi.java @@ -113,7 +113,9 @@ public interface LuckPermsApi { User getUser(UUID uuid); /** - * Gets a wrapped user object from the user storage. This method does not return null, unlike {@link #getUser(UUID)} + * Gets a wrapped user object from the user storage. + * + *This method does not return null, unlike {@link #getUser(UUID)}
* * @param uuid the uuid of the user to get * @return an optional {@link User} object @@ -131,8 +133,9 @@ public interface LuckPermsApi { User getUser(String name); /** - * Gets a wrapped user object from the user storage. This method does not return null, unlike {@link - * #getUser(String)} + * Gets a wrapped user object from the user storage. + * + *This method does not return null, unlike {@link #getUser(String)}
* * @param name the username of the user to get * @return an optional {@link User} object @@ -175,7 +178,9 @@ public interface LuckPermsApi { Group getGroup(String name); /** - * Gets a wrapped group object from the group storage. This method does not return null, unlike {@link #getGroup} + * Gets a wrapped group object from the group storage. + * + *This method does not return null, unlike {@link #getGroup}
* * @param name the name of the group to get * @return an optional {@link Group} object @@ -209,7 +214,9 @@ public interface LuckPermsApi { Track getTrack(String name); /** - * Gets a wrapped track object from the track storage. This method does not return null, unlike {@link #getTrack} + * Gets a wrapped track object from the track storage. + * + *This method does not return null, unlike {@link #getTrack}
* * @param name the name of the track to get * @return an optional {@link Track} object diff --git a/api/src/main/java/me/lucko/luckperms/api/MessagingService.java b/api/src/main/java/me/lucko/luckperms/api/MessagingService.java index 99e5c4e67..661d345e3 100644 --- a/api/src/main/java/me/lucko/luckperms/api/MessagingService.java +++ b/api/src/main/java/me/lucko/luckperms/api/MessagingService.java @@ -32,8 +32,8 @@ public interface MessagingService { /** * Uses the messaging service to inform other servers about changes. * - *This will push the update asynchronously, and this method will return immediately. Calling this method is - * equivalent to running "/lp networksync", except will not sync this server. + *
This will push the update asynchronously, and this method will return immediately. Calling this method is + * equivalent to running "/lp networksync", except will not sync this server.
*/ void pushUpdate(); diff --git a/api/src/main/java/me/lucko/luckperms/api/MetaUtils.java b/api/src/main/java/me/lucko/luckperms/api/MetaUtils.java index 481d68fb5..bcdec7f4b 100644 --- a/api/src/main/java/me/lucko/luckperms/api/MetaUtils.java +++ b/api/src/main/java/me/lucko/luckperms/api/MetaUtils.java @@ -34,7 +34,9 @@ import java.util.Set; * A collection of utilities to help retrieve meta values for {@link PermissionHolder}s * * @since 2.7 + * @deprecated in favour of using {@link NodeFactory#makeMetaNode(String, String)} or {@link me.lucko.luckperms.api.caching.MetaData}. */ +@Deprecated public class MetaUtils { private static String escapeDelimiters(String s, String... delims) { @@ -92,42 +94,24 @@ public class MetaUtils { * @param holder the holder to apply the meta node to * @param server the server to apply the meta on, can be null * @param world the world to apply the meta on, can be null - * @param node the meta node + * @param key the meta key * @param value the meta value * @throws NullPointerException if the holder, node or value is null * @throws IllegalArgumentException if the node or value is empty */ - public static void setMeta(PermissionHolder holder, String server, String world, String node, String value) { - if (holder == null) { - throw new NullPointerException("holder"); - } + public static void setMeta(PermissionHolder holder, String server, String world, String key, String value) { + if (holder == null) throw new NullPointerException("holder"); + if (key == null) throw new NullPointerException("node"); + if (value == null) throw new NullPointerException("value"); + if (key.equals("")) throw new IllegalArgumentException("node is empty"); + if (value.equals("")) throw new IllegalArgumentException("value is empty"); - if (node == null) { - throw new NullPointerException("node"); - } - - if (value == null) { - throw new NullPointerException("value"); - } - - if (node.equals("")) { - throw new IllegalArgumentException("node is empty"); - } - - if (value.equals("")) { - throw new IllegalArgumentException("value is empty"); - } - - if (server == null || server.equals("")) { - server = "global"; - } - - node = escapeCharacters(node); + key = escapeCharacters(key); value = escapeCharacters(value); SetUse {@link LuckPermsApi#buildNode(String)} to get an instance. + *
Use {@link LuckPermsApi#buildNode(String)} to get an instance.
* * @since 2.6 */ diff --git a/api/src/main/java/me/lucko/luckperms/api/NodeFactory.java b/api/src/main/java/me/lucko/luckperms/api/NodeFactory.java index 11bf81fd6..33800e42e 100644 --- a/api/src/main/java/me/lucko/luckperms/api/NodeFactory.java +++ b/api/src/main/java/me/lucko/luckperms/api/NodeFactory.java @@ -33,7 +33,7 @@ public interface NodeFactory { * Creates a node from a serialised node string * * @param serialisedPermission the serialised permission string - * @param value the value of the node + * @param value the value of the node * @return a node instance * @throws NullPointerException if the permission is null */ @@ -60,18 +60,30 @@ public interface NodeFactory { /** * Creates a node builder from a serialised node string + * * @param serialisedPermission the serialised permission string - * @param value the value of the node + * @param value the value of the node * @return a node builder instance * @throws NullPointerException if the permission is null */ Node.Builder newBuilderFromSerialisedNode(String serialisedPermission, boolean value); + /** + * Creates a node builder from a group + * + * @param group the group + * @return a node builder instance + * @throws NullPointerException if the group is null + * @throws IllegalStateException if the group instance was not obtained from LuckPerms. + * @since 3.1 + */ + Node.Builder makeGroupNode(Group group); + /** * Creates a node builder from a key value pair * - * @param key the key + * @param key the key * @param value the value * @return a node builder instance * @throws NullPointerException if the key or value is null @@ -82,7 +94,7 @@ public interface NodeFactory { * Creates a node builder from a prefix string and priority * * @param priority the priority - * @param prefix the prefix string + * @param prefix the prefix string * @return a node builder instance * @throws NullPointerException if the prefix is null */ @@ -92,7 +104,7 @@ public interface NodeFactory { * Creates a node builder from a prefix string and priority * * @param priority the priority - * @param suffix the suffix string + * @param suffix the suffix string * @return a node builder instance * @throws NullPointerException if the suffix is null */ 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 5d2a85d67..8714f254a 100644 --- a/api/src/main/java/me/lucko/luckperms/api/PermissionHolder.java +++ b/api/src/main/java/me/lucko/luckperms/api/PermissionHolder.java @@ -32,15 +32,15 @@ import java.util.SortedSet; /** * An object capable of holding permissions * - *Any changes made will be lost unless the instance is saved back to the {@link Storage}. + *
Any changes made will be lost unless the instance is saved back to the {@link Storage}.
*/ public interface PermissionHolder { /** * Gets the objects name * - *{@link User#getUuid()}, {@link User#getName()} or {@link Group#getName()} should normally be used instead of - * this method. + *
{@link User#getUuid()}, {@link User#getName()} or {@link Group#getName()} should normally be used instead of + * this method.
* * @return the identifier for this object. Either a uuid string or name. */ @@ -74,9 +74,11 @@ public interface PermissionHolder { /** * Gets a mutable sorted set of the nodes that this object has and inherits, filtered by context - * Unlike {@link #getAllNodesFiltered(Contexts)}, this method will not filter individual nodes. The context is only - * used to determine which groups should apply. - * Nodes are sorted into priority order. + * + *Unlike {@link #getAllNodesFiltered(Contexts)}, this method will not filter individual nodes. The context is only + * used to determine which groups should apply.
+ * + *Nodes are sorted into priority order.
* * @param contexts the context for the lookup, * @return a mutable sorted set of permissions @@ -87,8 +89,9 @@ public interface PermissionHolder { /** * Gets a mutable set of the nodes that this object has and inherits, filtered by context. - * Unlike {@link #getAllNodes(Contexts)}, this method WILL filter individual nodes, and only return ones that fully - * meet the context provided. + * + *Unlike {@link #getAllNodes(Contexts)}, this method WILL filter individual nodes, and only return ones that fully + * meet the context provided.
* * @param contexts the context for the lookup * @return a mutable set of permissions @@ -99,6 +102,7 @@ public interface PermissionHolder { /** * Converts the output of {@link #getAllNodesFiltered(Contexts)}, and expands shorthand permissions. + * * @param contexts the context for the lookup * @param lowerCase if the keys should be made lowercase whilst being exported * @return a mutable map of permissions @@ -206,7 +210,7 @@ public interface PermissionHolder { boolean hasPermission(String node, boolean b, String server, String world, boolean temporary); /** - * Cheks to see if the object inherits a certain permission + * Checks to see if the object inherits a certain permission * * @param node the node to check for * @return a Tristate for the holders inheritance status for the node @@ -300,17 +304,27 @@ public interface PermissionHolder { */ void setPermission(Node node) throws ObjectAlreadyHasException; + /** + * Sets a permission for the object + * + * @param node The node to be set + * @throws NullPointerException if the node is null + * @return the result of the operation + * @since 3.1 + */ + DataMutateResult setPermissionUnchecked(Node node); + /** * Sets a transient permission for the object * - *A transient node is a permission that does not persist. + *
A transient node is a permission that does not persist. * Whenever a user logs out of the server, or the server restarts, this permission will disappear. - * It is never saved to the datastore, and therefore will not apply on other servers. + * It is never saved to the datastore, and therefore will not apply on other servers.
* - *This is useful if you want to temporarily set a permission for a user while they're online, but don't - * want it to persist, and have to worry about removing it when they log out. + *
This is useful if you want to temporarily set a permission for a user while they're online, but don't + * want it to persist, and have to worry about removing it when they log out.
* - *For unsetting a transient permission, see {@link #unsetTransientPermission(Node)} + *
For unsetting a transient permission, see {@link #unsetTransientPermission(Node)}
* * @param node The node to be set * @throws ObjectAlreadyHasException if the object already has the permission @@ -319,6 +333,25 @@ public interface PermissionHolder { */ void setTransientPermission(Node node) throws ObjectAlreadyHasException; + /** + * Sets a transient permission for the object + * + *A transient node is a permission that does not persist. + * Whenever a user logs out of the server, or the server restarts, this permission will disappear. + * It is never saved to the datastore, and therefore will not apply on other servers.
+ * + *This is useful if you want to temporarily set a permission for a user while they're online, but don't + * want it to persist, and have to worry about removing it when they log out.
+ * + *For unsetting a transient permission, see {@link #unsetTransientPermission(Node)}
+ * + * @param node The node to be set + * @throws NullPointerException if the node is null + * @return the result of the operation + * @since 3.1 + */ + DataMutateResult setTransientPermissionUnchecked(Node node); + /** * Sets a permission for the object * @@ -416,6 +449,16 @@ public interface PermissionHolder { */ void unsetPermission(Node node) throws ObjectLacksException; + /** + * Unsets a permission for the object + * + * @param node The node to be unset + * @throws NullPointerException if the node is null + * @return the result of the operation + * @since 3.1 + */ + DataMutateResult unsetPermissionUnchecked(Node node); + /** * Unsets a transient permission for the object * @@ -426,6 +469,16 @@ public interface PermissionHolder { */ void unsetTransientPermission(Node node) throws ObjectLacksException; + /** + * Unsets a transient permission for the object + * + * @param node The node to be unset + * @throws NullPointerException if the node is null + * @return the result of the operation + * @since 3.1 + */ + DataMutateResult unsetTransientPermissionUnchecked(Node node); + /** * Unsets a permission for the object * diff --git a/api/src/main/java/me/lucko/luckperms/api/Storage.java b/api/src/main/java/me/lucko/luckperms/api/Storage.java index e7341ae87..f9e4713a7 100644 --- a/api/src/main/java/me/lucko/luckperms/api/Storage.java +++ b/api/src/main/java/me/lucko/luckperms/api/Storage.java @@ -34,11 +34,11 @@ import java.util.function.Consumer; * *All methods return {@link CompletableFuture}s, which will be populated with the result once the data has been * loaded asynchronously. Care should be taken when using the methods to ensure that the main server thread is not - * blocked. + * blocked.
* *Methods such as {@link CompletableFuture#get()} and equivalent should not be called on the main * server thread. If you need to use the result of these operations on the main server thread, please register a - * callback using {@link CompletableFuture#thenAcceptAsync(Consumer, Executor)} and {@link #getSyncExecutor()}. + * callback using {@link CompletableFuture#thenAcceptAsync(Consumer, Executor)} and {@link #getSyncExecutor()}.
* * @since 2.14 */ 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 1a1918788..a5f969fca 100644 --- a/api/src/main/java/me/lucko/luckperms/api/Track.java +++ b/api/src/main/java/me/lucko/luckperms/api/Track.java @@ -41,7 +41,7 @@ public interface Track { /** * Gets an ordered list of the groups on this track * - *Index 0 is the first/lowest group in (or start of) the 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 */ diff --git a/api/src/main/java/me/lucko/luckperms/api/Tristate.java b/api/src/main/java/me/lucko/luckperms/api/Tristate.java index bcc17e082..dbc5ed1ba 100644 --- a/api/src/main/java/me/lucko/luckperms/api/Tristate.java +++ b/api/src/main/java/me/lucko/luckperms/api/Tristate.java @@ -25,8 +25,8 @@ package me.lucko.luckperms.api; /** * Represents a permission setting. * - *Consider a value of {@link #FALSE} to be a "negated" setting, and a value of {@link #UNDEFINED} to be a - * non-existent value. + *
Consider a value of {@link #FALSE} to be a "negated" setting, and a value of {@link #UNDEFINED} to be a + * non-existent value.
*/ public enum Tristate { @@ -63,7 +63,8 @@ public enum Tristate { /** * Returns the value of the Tristate as a boolean. - *A value of {@link #UNDEFINED} converts to false. + * + *
A value of {@link #UNDEFINED} converts to false.
* * @return a boolean representation of the Tristate. */ 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 c6d0a2af4..41ccaafc9 100644 --- a/api/src/main/java/me/lucko/luckperms/api/User.java +++ b/api/src/main/java/me/lucko/luckperms/api/User.java @@ -69,8 +69,8 @@ public interface User extends PermissionHolder { /** * Refresh and re-assign the users permissions. * - *This request is not buffered, and the refresh call will be ran directly. This should ideally be called on - * an asynchronous thread. + *
This request is not buffered, and the refresh call will be ran directly. This should ideally be called on + * an asynchronous thread.
*/ void refreshPermissions(); @@ -128,7 +128,9 @@ public interface User extends PermissionHolder { * @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. + * @deprecated in favour of {@link NodeFactory#makeGroupNode(Group)} */ + @Deprecated void addGroup(Group group) throws ObjectAlreadyHasException; /** @@ -140,7 +142,9 @@ public interface User extends PermissionHolder { * @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 + * @deprecated in favour of {@link NodeFactory#makeGroupNode(Group)} */ + @Deprecated void addGroup(Group group, String server) throws ObjectAlreadyHasException; /** @@ -153,7 +157,9 @@ public interface User extends PermissionHolder { * @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 + * @deprecated in favour of {@link NodeFactory#makeGroupNode(Group)} */ + @Deprecated void addGroup(Group group, String server, String world) throws ObjectAlreadyHasException; /** @@ -165,7 +171,9 @@ public interface User extends PermissionHolder { * @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 + * @deprecated in favour of {@link NodeFactory#makeGroupNode(Group)} */ + @Deprecated void addGroup(Group group, long expireAt) throws ObjectAlreadyHasException; /** @@ -178,7 +186,9 @@ public interface User extends PermissionHolder { * @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 + * @deprecated in favour of {@link NodeFactory#makeGroupNode(Group)} */ + @Deprecated void addGroup(Group group, String server, long expireAt) throws ObjectAlreadyHasException; /** @@ -192,7 +202,9 @@ public interface User extends PermissionHolder { * @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 + * @deprecated in favour of {@link NodeFactory#makeGroupNode(Group)} */ + @Deprecated void addGroup(Group group, String server, String world, long expireAt) throws ObjectAlreadyHasException; /** @@ -202,7 +214,9 @@ public interface User extends PermissionHolder { * @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. + * @deprecated in favour of {@link NodeFactory#makeGroupNode(Group)} */ + @Deprecated void removeGroup(Group group) throws ObjectLacksException; /** @@ -213,7 +227,9 @@ public interface User extends PermissionHolder { * @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. + * @deprecated in favour of {@link NodeFactory#makeGroupNode(Group)} */ + @Deprecated void removeGroup(Group group, boolean temporary) throws ObjectLacksException; /** @@ -225,7 +241,9 @@ public interface User extends PermissionHolder { * @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 + * @deprecated in favour of {@link NodeFactory#makeGroupNode(Group)} */ + @Deprecated void removeGroup(Group group, String server) throws ObjectLacksException; /** @@ -238,7 +256,9 @@ public interface User extends PermissionHolder { * @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 + * @deprecated in favour of {@link NodeFactory#makeGroupNode(Group)} */ + @Deprecated void removeGroup(Group group, String server, String world) throws ObjectLacksException; /** @@ -251,7 +271,9 @@ public interface User extends PermissionHolder { * @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 + * @deprecated in favour of {@link NodeFactory#makeGroupNode(Group)} */ + @Deprecated void removeGroup(Group group, String server, boolean temporary) throws ObjectLacksException; /** @@ -265,7 +287,9 @@ public interface User extends PermissionHolder { * @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 + * @deprecated in favour of {@link NodeFactory#makeGroupNode(Group)} */ + @Deprecated void removeGroup(Group group, String server, String world, boolean temporary) throws ObjectLacksException; /** diff --git a/api/src/main/java/me/lucko/luckperms/api/UuidCache.java b/api/src/main/java/me/lucko/luckperms/api/UuidCache.java index 545051069..6bea46b38 100644 --- a/api/src/main/java/me/lucko/luckperms/api/UuidCache.java +++ b/api/src/main/java/me/lucko/luckperms/api/UuidCache.java @@ -27,15 +27,15 @@ import java.util.UUID; /** * A UUID cache for online users, between external Mojang UUIDs, and internal LuckPerms UUIDs. * - *This UuidCache is a means of allowing users to have the same internal UUID across a network of offline mode + *
This UuidCache is a means of allowing users to have the same internal UUID across a network of offline mode * servers or mixed offline mode and online mode servers. Platforms running in offline mode generate a UUID for a * user when they first join the server, but this UUID will then not be consistent across the network. LuckPerms will * instead check the datastore cache, to get a UUID for a user that is consistent across an entire network. * - *
If you want to get a user object from the Storage using the api on a server in offline mode, you will need to use + *
If you want to get a user object from the Storage using the api on a server in offline mode, you will need to use * this cache, OR use Storage#getUUID, for users that are not online. * - *
THIS IS ONLY EFFECTIVE FOR ONLINE PLAYERS. USE THE DATASTORE METHODS FOR OFFLINE PLAYERS. + *
This is only effective for online players. Use {@link Storage#getUUID(String)} for offline players.
*/ public interface UuidCache { diff --git a/api/src/main/java/me/lucko/luckperms/api/caching/PermissionData.java b/api/src/main/java/me/lucko/luckperms/api/caching/PermissionData.java index 082686534..f5c762ff7 100644 --- a/api/src/main/java/me/lucko/luckperms/api/caching/PermissionData.java +++ b/api/src/main/java/me/lucko/luckperms/api/caching/PermissionData.java @@ -45,7 +45,7 @@ public interface PermissionData { /** * Invalidates the underlying permission calculator cache. * - *Can be called to allow for an update in defaults. + *
Can be called to allow for an update in defaults.
*/ void invalidateCache(); diff --git a/api/src/main/java/me/lucko/luckperms/api/caching/UserData.java b/api/src/main/java/me/lucko/luckperms/api/caching/UserData.java index e752f71d1..c61885134 100644 --- a/api/src/main/java/me/lucko/luckperms/api/caching/UserData.java +++ b/api/src/main/java/me/lucko/luckperms/api/caching/UserData.java @@ -30,7 +30,7 @@ import java.util.Set; * Holds cached permission and meta lookup data for a {@link me.lucko.luckperms.api.User}. * *Data is only likely to be available for online users. All calls will account for inheritance, as well as any - * default data provided by the platform. This calls are heavily cached and are therefore fast. + * default data provided by the platform. This calls are heavily cached and are therefore fast.
* * @since 2.13 */ @@ -39,7 +39,7 @@ public interface UserData { /** * Gets PermissionData from the cache, given a specified context. * - *If the data is not cached, it is calculated. Therefore, this call could be costly. + *
If the data is not cached, it is calculated. Therefore, this call could be costly.
* * @param contexts the contexts to get the permission data in * @return a permission data instance @@ -50,7 +50,7 @@ public interface UserData { /** * Gets MetaData from the cache, given a specified context. * - *If the data is not cached, it is calculated. Therefore, this call could be costly. + *
If the data is not cached, it is calculated. Therefore, this call could be costly.
* * @param contexts the contexts to get the permission data in * @return a meta data instance @@ -79,8 +79,8 @@ public interface UserData { /** * Calculates permission data and stores it in the cache. * - *If there is already data cached for the given contexts, and if the resultant output is different, - * the cached value is updated. + *
If there is already data cached for the given contexts, and if the resultant output is different, + * the cached value is updated.
* * @param contexts the contexts to recalculate in. * @throws NullPointerException if contexts is null @@ -90,8 +90,8 @@ public interface UserData { /** * Calculates meta data and stores it in the cache. * - *If there is already data cached for the given contexts, and if the resultant output is different, - * the cached value is updated. + *
If there is already data cached for the given contexts, and if the resultant output is different, + * the cached value is updated.
* * @param contexts the contexts to recalculate in. * @throws NullPointerException if contexts is null @@ -119,7 +119,7 @@ public interface UserData { /** * Ensures that PermissionData and MetaData is cached for a context. * - *If the cache does not contain any data for the context, it will be calculated and saved. + *
If the cache does not contain any data for the context, it will be calculated and saved.
* * @param contexts the contexts to pre-calculate for * @throws NullPointerException if contexts is null @@ -128,7 +128,8 @@ public interface UserData { /** * Invalidates all of the underlying Permission calculators. - * Can be called to allow for an update in defaults. + * + *Can be called to allow for an update in defaults.
*/ void invalidatePermissionCalculators(); diff --git a/api/src/main/java/me/lucko/luckperms/api/context/ContextCalculator.java b/api/src/main/java/me/lucko/luckperms/api/context/ContextCalculator.java index 5ebf34950..0e69014eb 100644 --- a/api/src/main/java/me/lucko/luckperms/api/context/ContextCalculator.java +++ b/api/src/main/java/me/lucko/luckperms/api/context/ContextCalculator.java @@ -25,9 +25,8 @@ package me.lucko.luckperms.api.context; /** * Calculates whether contexts are applicable to {@link T} * - *Somewhat inspired by the system used on Sponge.
- *
* @param Implementations may be either mutable or immutable.