minecraft/LuckPerms
1
0
Fork 0
mirror of https://github.com/lucko/LuckPerms.git synced 2025-09-02 02:42:33 +02:00
Code Issues Releases Wiki Activity

API changes for 3.1

Browse Source
This commit is contained in:
Luck
2017-04-10 22:26:20 +01:00
parent 4631dcf857
commit 4fb07ff181
52 changed files with 392 additions and 298 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
api/pom.xml
View File

@@ -5,12 +5,13 @@
<parent>
<artifactId>luckperms</artifactId>
<groupId>me.lucko.luckperms</groupId>
<version>3.0-SNAPSHOT</version>
<version>3.1-SNAPSHOT</version>
</parent>
<modelVersion>4.0.0</modelVersion>
<artifactId>luckperms-api</artifactId>
<build>
<finalName>LuckPerms-API-${release.version}</finalName>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>

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

@@ -29,8 +29,8 @@ import java.util.Optional;
/**
* Singleton for the {@link LuckPermsApi}.
*
* <p> 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.
* <p>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.</p>
*/
public final class LuckPerms {
private static LuckPermsApi api = null;

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

@@ -27,7 +27,7 @@ import me.lucko.luckperms.api.context.ContextSet;
/**
* Context and options for a permission lookup.
*
* <p> All values are immutable.
* <p>All values are immutable.</p>
*
* @since 2.11
*/

65
api/src/main/java/me/lucko/luckperms/api/DataMutateResult.java Normal file
View File

@@ -0,0 +1,65 @@
/*
* Copyright (c) 2016 Lucko (Luck) <luck@lucko.me>
*
* Permission is hereby granted, free of charge, to any person obtaining a copy
* of this software and associated documentation files (the "Software"), to deal
* in the Software without restriction, including without limitation the rights
* to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
* copies of the Software, and to permit persons to whom the Software is
* furnished to do so, subject to the following conditions:
*
* The above copyright notice and this permission notice shall be included in all
* copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
* SOFTWARE.
*/
package me.lucko.luckperms.api;
import me.lucko.luckperms.exceptions.ObjectAlreadyHasException;
import me.lucko.luckperms.exceptions.ObjectLacksException;
import java.util.function.Supplier;
public enum DataMutateResult {
SUCCESS(true, null),
ALREADY_HAS(false, ObjectAlreadyHasException::new),
LACKS(false, ObjectLacksException::new),
FAIL(false, RuntimeException::new);
private boolean value;
private final Supplier<? extends Exception> exceptionSupplier;
DataMutateResult(boolean value, Supplier<? extends Exception> exceptionSupplier) {
this.value = value;
this.exceptionSupplier = exceptionSupplier;
}
public void throwException() {
if (exceptionSupplier != null) {
sneakyThrow(exceptionSupplier.get());
}
}
public boolean asBoolean() {
return value;
}
// allows us to throw checked exceptions without declaring it, as #throwException throws a number of
// exception types.
private static void sneakyThrow(Throwable t) {
sneakyThrow0(t);
}
private static <T extends Throwable> void sneakyThrow0(Throwable t) throws T {
throw (T) t;
}
}

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

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

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

@@ -29,8 +29,8 @@ import java.util.UUID;
/**
* Represents the internal LuckPerms log.
*
* <p> 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.
* <p>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.</p>
*/
public interface Log {

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

@@ -27,7 +27,7 @@ import java.util.UUID;
/**
* A single entry in the log
*
* <p> Implements {@link Comparable} ordering based upon the timestamp of the entry.
* <p>Implements {@link Comparable} ordering based upon the timestamp of the entry.</p>
*/
public class LogEntry implements Comparable<LogEntry> {
private static final String FORMAT = "&8(&e%s&8) [&a%s&8] (&b%s&8) &7--> &f%s";

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

@@ -25,8 +25,8 @@ package me.lucko.luckperms.api;
/**
* A wrapper interface for platform logger instances
*
* <p> 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.
* <p>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.</p>
*/
public interface Logger {

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

@@ -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.
*
* <p>This method does not return null, unlike {@link #getUser(UUID)}</p>
*
* @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.
*
* <p>This method does not return null, unlike {@link #getUser(String)}</p>
*
* @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.
*
* <p>This method does not return null, unlike {@link #getGroup}</p>
*
* @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.
*
* <p>This method does not return null, unlike {@link #getTrack}</p>
*
* @param name the name of the track to get
* @return an optional {@link Track} object

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

@@ -32,8 +32,8 @@ public interface MessagingService {
/**
* Uses the messaging service to inform other servers about changes.
*
* <p> 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.
* <p>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.</p>
*/
void pushUpdate();

108
api/src/main/java/me/lucko/luckperms/api/MetaUtils.java
View File

@@ -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);
Set<Node> toRemove = new HashSet<>();
for (Node n : holder.getEnduringPermissions()) {
if (n.isMeta() && n.getMeta().getKey().equals(node)) {
if (n.isMeta() && n.getMeta().getKey().equals(key)) {
toRemove.add(n);
}
}
@@ -138,12 +122,12 @@ public class MetaUtils {
} catch (ObjectLacksException ignored) {}
}
Node.Builder metaNode = LuckPerms.getApi().buildNode("meta." + node + "." + value).setValue(true);
if (!server.equalsIgnoreCase("global")) {
Node.Builder metaNode = LuckPerms.getApi().buildNode("meta." + key + "." + value).setValue(true);
if (server != null) {
metaNode.setServer(server);
}
if (world != null && !world.equals("")) {
metaNode.setServer(server).setWorld(world);
if (world != null) {
metaNode.setWorld(world);
}
try {
@@ -165,18 +149,8 @@ public class MetaUtils {
* @throws IllegalArgumentException if the node is empty
*/
public static String getMeta(PermissionHolder holder, String server, String world, String node, String defaultValue, boolean includeGlobal) {
if (holder == null) {
throw new NullPointerException("holder");
}
if (server == null || server.equals("")) {
server = "global";
}
if (node == null) {
throw new NullPointerException("node");
}
if (holder == null) throw new NullPointerException("holder");
if (node == null) throw new NullPointerException("node");
if (node.equals("")) {
throw new IllegalArgumentException("node is empty");
}
@@ -184,23 +158,10 @@ public class MetaUtils {
node = escapeCharacters(node);
for (Node n : holder.getPermissions()) {
if (!n.getValue()) {
continue;
}
if (!n.getValue() || !n.isMeta()) continue;
if (!n.isMeta()) {
continue;
}
if (!server.equalsIgnoreCase("global")) {
if (!n.shouldApplyOnServer(server, includeGlobal, false)) {
continue;
}
}
if (!n.shouldApplyOnWorld(world, includeGlobal, false)) {
continue;
}
if (!n.shouldApplyOnServer(server, includeGlobal, false)) continue;
if (!n.shouldApplyOnWorld(world, includeGlobal, false)) continue;
Map.Entry<String, String> meta = n.getMeta();
if (meta.getKey().equalsIgnoreCase(node)) {
@@ -212,21 +173,18 @@ public class MetaUtils {
}
private static void setChatMeta(boolean prefix, PermissionHolder holder, String value, int priority, String server, String world) {
if (holder == null) {
throw new NullPointerException("holder");
}
if (holder == null) throw new NullPointerException("holder");
if (value == null || value.equals("")) {
throw new IllegalArgumentException("value is null/empty");
}
Node.Builder node = LuckPerms.getApi().buildNode(prefix ? "prefix" : "suffix" + "." + priority + "." + escapeCharacters(value));
node.setValue(true);
if (!server.equalsIgnoreCase("global")) {
if (server != null) {
node.setServer(server);
}
if (world != null && !world.equals("")) {
node.setServer(server).setWorld(world);
if (world != null) {
node.setWorld(world);
}
try {
@@ -268,26 +226,14 @@ public class MetaUtils {
if (holder == null) {
throw new NullPointerException("holder");
}
if (server == null) {
server = "global";
}
int priority = Integer.MIN_VALUE;
String meta = null;
for (Node n : holder.getAllNodes(Contexts.allowAll())) {
if (!n.getValue()) {
continue;
}
if (!n.getValue()) continue;
if (!server.equalsIgnoreCase("global")) {
if (!n.shouldApplyOnServer(server, includeGlobal, false)) {
continue;
}
}
if (!n.shouldApplyOnWorld(world, includeGlobal, false)) {
continue;
}
if (!n.shouldApplyOnServer(server, includeGlobal, false)) continue;
if (!n.shouldApplyOnWorld(world, includeGlobal, false)) continue;
if (prefix ? !n.isPrefix() : !n.isSuffix()) {
continue;

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

@@ -33,7 +33,7 @@ import java.util.Set;
/**
* An immutable permission node
*
* <p> Use {@link LuckPermsApi#buildNode(String)} to get an instance.
* <p>Use {@link LuckPermsApi#buildNode(String)} to get an instance.</p>
*
* @since 2.6
*/

22
api/src/main/java/me/lucko/luckperms/api/NodeFactory.java
View File

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

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

@@ -32,15 +32,15 @@ import java.util.SortedSet;
/**
* An object capable of holding permissions
*
* <p> Any changes made will be lost unless the instance is saved back to the {@link Storage}.
* <p>Any changes made will be lost unless the instance is saved back to the {@link Storage}.</p>
*/
public interface PermissionHolder {
/**
* Gets the objects name
*
* <p> {@link User#getUuid()}, {@link User#getName()} or {@link Group#getName()} should normally be used instead of
* this method.
* <p>{@link User#getUuid()}, {@link User#getName()} or {@link Group#getName()} should normally be used instead of
* this method.</p>
*
* @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.
*
* <p>Unlike {@link #getAllNodesFiltered(Contexts)}, this method will not filter individual nodes. The context is only
* used to determine which groups should apply.</p>
*
* <p>Nodes are sorted into priority order.</p>
*
* @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.
*
* <p>Unlike {@link #getAllNodes(Contexts)}, this method WILL filter individual nodes, and only return ones that fully
* meet the context provided.</p>
*
* @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
*
* <p> A transient node is a permission that does not persist.
* <p>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.</p>
*
* <p> 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.
* <p>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.</p>
*
* <p> For unsetting a transient permission, see {@link #unsetTransientPermission(Node)}
* <p>For unsetting a transient permission, see {@link #unsetTransientPermission(Node)}</p>
*
* @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
*
* <p>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.</p>
*
* <p>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.</p>
*
* <p>For unsetting a transient permission, see {@link #unsetTransientPermission(Node)}</p>
*
* @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
*

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

@@ -34,11 +34,11 @@ import java.util.function.Consumer;
*
* <p>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.</p>
*
* <p>Methods such as {@link CompletableFuture#get()} and equivalent should <strong>not</strong> 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()}.</p>
*
* @since 2.14
*/

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

@@ -41,7 +41,7 @@ public interface Track {
/**
* Gets an ordered list of the groups on this track
*
* <p> Index 0 is the first/lowest group in (or start of) the track
* <p>Index 0 is the first/lowest group in (or start of) the track</p>
*
* @return an ordered {@link List} of the groups on this track
*/

7
api/src/main/java/me/lucko/luckperms/api/Tristate.java
View File

@@ -25,8 +25,8 @@ package me.lucko.luckperms.api;
/**
* Represents a permission setting.
*
* <p> Consider a value of {@link #FALSE} to be a "negated" setting, and a value of {@link #UNDEFINED} to be a
* non-existent value.
* <p>Consider a value of {@link #FALSE} to be a "negated" setting, and a value of {@link #UNDEFINED} to be a
* non-existent value.</p>
*/
public enum Tristate {
@@ -63,7 +63,8 @@ public enum Tristate {
/**
* Returns the value of the Tristate as a boolean.
* <p> A value of {@link #UNDEFINED} converts to false.
*
* <p>A value of {@link #UNDEFINED} converts to false.</p>
*
* @return a boolean representation of the Tristate.
*/

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

@@ -69,8 +69,8 @@ public interface User extends PermissionHolder {
/**
* Refresh and re-assign the users permissions.
*
* <p> This request is not buffered, and the refresh call will be ran directly. This should ideally be called on
* an asynchronous thread.
* <p>This request is not buffered, and the refresh call will be ran directly. This should ideally be called on
* an asynchronous thread.</p>
*/
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;
/**

6
api/src/main/java/me/lucko/luckperms/api/UuidCache.java
View File

@@ -27,15 +27,15 @@ import java.util.UUID;
/**
* A UUID cache for online users, between external Mojang UUIDs, and internal LuckPerms UUIDs.
*
* <p> This UuidCache is a means of allowing users to have the same internal UUID across a network of offline mode
* <p>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.
*
* <p> 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
* <p>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.
*
* <p> THIS IS ONLY EFFECTIVE FOR ONLINE PLAYERS. USE THE DATASTORE METHODS FOR OFFLINE PLAYERS.
* <p><strong>This is only effective for online players. Use {@link Storage#getUUID(String)} for offline players.</strong></p>
*/
public interface UuidCache {

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

@@ -45,7 +45,7 @@ public interface PermissionData {
/**
* Invalidates the underlying permission calculator cache.
*
* <p> Can be called to allow for an update in defaults.
* <p>Can be called to allow for an update in defaults.</p>
*/
void invalidateCache();

19
api/src/main/java/me/lucko/luckperms/api/caching/UserData.java
View File

@@ -30,7 +30,7 @@ import java.util.Set;
* Holds cached permission and meta lookup data for a {@link me.lucko.luckperms.api.User}.
*
* <p>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.</p>
*
* @since 2.13
*/
@@ -39,7 +39,7 @@ public interface UserData {
/**
* Gets PermissionData from the cache, given a specified context.
*
* <p> If the data is not cached, it is calculated. Therefore, this call could be costly.
* <p>If the data is not cached, it is calculated. Therefore, this call could be costly.</p>
*
* @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.
*
* <p> If the data is not cached, it is calculated. Therefore, this call could be costly.
* <p>If the data is not cached, it is calculated. Therefore, this call could be costly.</p>
*
* @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.
*
* <p> If there is already data cached for the given contexts, and if the resultant output is different,
* the cached value is updated.
* <p>If there is already data cached for the given contexts, and if the resultant output is different,
* the cached value is updated.</p>
*
* @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.
*
* <p> If there is already data cached for the given contexts, and if the resultant output is different,
* the cached value is updated.
* <p>If there is already data cached for the given contexts, and if the resultant output is different,
* the cached value is updated.</p>
*
* @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.
*
* <p> If the cache does not contain any data for the context, it will be calculated and saved.
* <p>If the cache does not contain any data for the context, it will be calculated and saved.</p>
*
* @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.
*
* <p>Can be called to allow for an update in defaults.</p>
*/
void invalidatePermissionCalculators();

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

@@ -25,9 +25,8 @@ package me.lucko.luckperms.api.context;
/**
* Calculates whether contexts are applicable to {@link T}
*
* <p>Somewhat inspired by the system used on Sponge.
*
* @param <T> the subject type. Is ALWAYS the player class of the platform.
* @since 2.13
*/
public interface ContextCalculator<T> {

5
api/src/main/java/me/lucko/luckperms/api/context/ContextSet.java
View File

@@ -29,8 +29,9 @@ import java.util.Optional;
import java.util.Set;
/**
* Holds contexts.
* Implementations may be either mutable or immutable.
* Holder of contexts.
*
* <p>Implementations may be either mutable or immutable.</p>
*
* @since 2.13
*/