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

API changes for 2.17 - closes #123

Browse Source
This commit is contained in:
Luck
2017-01-16 20:01:41 +00:00
parent c0da9d49d9
commit aea44fc8bc
59 changed files with 898 additions and 325 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
api/pom.xml
View File

@@ -5,7 +5,7 @@
<parent>
<artifactId>luckperms</artifactId>
<groupId>me.lucko.luckperms</groupId>
<version>2.16-SNAPSHOT</version>
<version>2.17-SNAPSHOT</version>
</parent>
<modelVersion>4.0.0</modelVersion>

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

@@ -27,13 +27,16 @@ import me.lucko.luckperms.api.LuckPermsApi;
import java.util.Optional;
/**
* Static access to LuckPerms
* 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.
*/
public final class LuckPerms {
private static LuckPermsApi api = null;
/**
* Gets an instance of {@link LuckPermsApi}
* Gets an instance of {@link LuckPermsApi}, throwing {@link IllegalStateException} if the API is not loaded.
*
* @return an api instance
* @throws IllegalStateException if the api is not loaded
@@ -46,8 +49,10 @@ public final class LuckPerms {
}
/**
* Gets an instance of {@link LuckPermsApi} safely. Unlike {@link LuckPerms#getApi}, this method will not throw an
* {@link IllegalStateException} if the api is not loaded, rather return an empty {@link Optional}.
* Gets an instance of {@link LuckPermsApi} safely.
*
* <p> Unlike {@link LuckPerms#getApi}, this method will not throw an {@link IllegalStateException} if the API is
* not loaded, rather return an empty {@link Optional}.
*
* @return an optional api instance
*/

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

@@ -27,8 +27,9 @@ import me.lucko.luckperms.api.context.ContextSet;
import java.util.Map;
/**
* Represents the context and options for a permission lookup.
* All values are immutable.
* Context and options for a permission lookup.
*
* <p> All values are immutable.
*
* @since 2.11
*/
@@ -67,28 +68,34 @@ public class Contexts {
* The keys for servers and worlds are defined as static values.
*/
private final ContextSet context;
/**
* The mode to parse defaults on Bukkit
*
* @since 2.12
*/
private final boolean op;
/**
* If global or non server specific nodes should be applied
*/
private final boolean includeGlobal;
/**
* If global or non world specific nodes should be applied
*/
private final boolean includeGlobalWorld;
/**
* If parent groups should be applied
*/
private final boolean applyGroups;
/**
* If global or non server specific group memberships should be applied
*/
private final boolean applyGlobalGroups;
/**
* If global or non world specific group memberships should be applied
*/

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

@@ -28,7 +28,7 @@ import java.util.Set;
import java.util.UUID;
/**
* Interface for the internal Datastore instance
* Deprecated Storage interface. Use {@link Storage} instead.
*
* @deprecated as of version 2.14 in favour of {@link Storage}.
*/

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

@@ -26,14 +26,16 @@ import me.lucko.luckperms.exceptions.ObjectAlreadyHasException;
import me.lucko.luckperms.exceptions.ObjectLacksException;
import java.util.List;
import java.util.OptionalInt;
/**
* Interface for internal Group instances
* A group which holds permission data.
*/
@SuppressWarnings("unused")
public interface Group extends PermissionHolder {
/**
* Get the name of the group
*
* @return the name of the group
*/
String getName();
@@ -220,11 +222,6 @@ public interface Group extends PermissionHolder {
*/
void unsetInheritGroup(Group group, String server, String world, boolean temporary) throws ObjectLacksException;
/**
* Clear all of the groups permission nodes
*/
void clearNodes();
/**
* Get a {@link List} of all of the groups the group inherits, on all servers
*
@@ -236,6 +233,17 @@ 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);
/**
* Get a {@link List} of the groups the group inherits on a specific server and world
*
* @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
@@ -244,12 +252,11 @@ public interface Group extends PermissionHolder {
List<String> getLocalGroups(String server, String world);
/**
* Get a {@link List} of the groups the group inherits on a specific server
* Gets the weight of this group, is present.
*
* @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
* @return the group weight
* @since 2.17
*/
List<String> getLocalGroups(String server);
OptionalInt getWeight();
}

94
api/src/main/java/me/lucko/luckperms/api/HeldPermission.java Normal file
View File

@@ -0,0 +1,94 @@
/*
* 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 com.google.common.collect.Multimap;
import java.util.Optional;
import java.util.OptionalLong;
/**
* A relationship between a Holder and a permission
*
* @param <T> the identifier type of the holder
* @since 2.17
*/
public interface HeldPermission<T> {
/**
* Gets the holder of the permission
*
* @return the holder
*/
T getHolder();
/**
* Gets the permission being held
*
* @return the permission
*/
String getPermission();
/**
* Gets the value of the permission
*
* @return the value
*/
boolean getValue();
/**
* Gets the server where the permission is held
*
* @return the server
*/
Optional<String> getServer();
/**
* Gets the world where the permission is held
*
* @return the world
*/
Optional<String> getWorld();
/**
* Gets the time in unix time when the permission will expire
*
* @return the expiry time
*/
OptionalLong getExpiry();
/**
* Gets the context for the permission.
*
* @return the context
*/
Multimap<String, String> getContext();
/**
* Converts this permission into a Node
*
* @return a Node copy of this permission
*/
Node asNode();
}

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

@@ -28,22 +28,24 @@ import me.lucko.luckperms.api.data.MySQLConfiguration;
import java.util.Map;
/**
* A wrapper interface for the internal LuckPerms configuration, providing read only access.
* Read-only access to the LuckPerms configuration settings
*/
@SuppressWarnings("unused")
public interface LPConfiguration {
/**
* Returns the name of this server
* @return the name of this server
*/
String getServer();
/**
* Returns how often a sync task will run in minutes
* @return how often a sync task will run in minutes
*/
int getSyncTime();
/**
* Returns the default group, in a node representation
* @return the default group, in a node representation
* @deprecated as of 2.6, the default group is always "default"
*/
@@ -51,6 +53,7 @@ public interface LPConfiguration {
String getDefaultGroupNode();
/**
* Returns the name of the default group
* @return the name of the default group
* @deprecated as of 2.6, the default group is always "default"
*/
@@ -58,55 +61,65 @@ public interface LPConfiguration {
String getDefaultGroupName();
/**
* Returns if the users on this server will have their global permissions applied
* @return if the users on this server will have their global permissions applied
*/
boolean getIncludeGlobalPerms();
/**
* Returns if the users on this server will have their global world permissions applied
* @return if the users on this server will have their global world permissions applied
* @since 2.9
*/
boolean getIncludeGlobalWorldPerms();
/**
* Returns true if the platform is applying global groups
* @return true if the platform is applying global groups
* @since 2.9
*/
boolean getApplyGlobalGroups();
/**
* Returns true if the platform is applying global world groups
* @return true if the platform is applying global world groups
* @since 2.9
*/
boolean getApplyGlobalWorldGroups();
/**
* @return the online mode setting in the config
* Returns the online mode setting
* @return the online mode setting
*/
boolean getOnlineMode();
/**
* Returns if LuckPerms is applying wildcard permissions
* @return if LuckPerms is applying wildcard permissions
*/
boolean getApplyWildcards();
/**
* Returns if LuckPerms is resolving and applying regex permissions
* @return if LuckPerms is resolving and applying regex permissions
*/
boolean getApplyRegex();
/**
* Returns if LuckPerms is expanding shorthand permissions
* @return if LuckPerms is expanding shorthand permissions
*/
boolean getApplyShorthand();
/**
* Returns if LuckPerms will send notifications to users when permissions are modified
* @return if LuckPerms will send notifications to users when permissions are modified
* @since 2.7
*/
boolean getLogNotify();
/**
* Returns true if permission checks are being recorded / debugged
* @return true if permission checks are being recorded / debugged
* @since 2.9
* @deprecated as this value is now always false. Functionality was replaced by the verbose command.
@@ -115,36 +128,42 @@ public interface LPConfiguration {
boolean getDebugPermissionChecks();
/**
* Returns true if the vanilla op system is enabled
* @return true if the vanilla op system is enabled
* @since 2.8
*/
boolean getEnableOps();
/**
* Returns true if opped players are allowed to use LuckPerms commands
* @return true if opped players are allowed to use LuckPerms commands
* @since 2.8
*/
boolean getCommandsAllowOp();
/**
* Returns true if auto op is enabled
* @return true if auto op is enabled
* @since 2.9
*/
boolean getAutoOp();
/**
* Returns the name of the server used within Vault operations
* @return the name of the server used within Vault operations
* @since 2.7
*/
String getVaultServer();
/**
* Returns true if global permissions should be considered when retrieving meta or player groups
* @return true if global permissions should be considered when retrieving meta or player groups
* @since 2.7
*/
boolean getVaultIncludeGlobal();
/**
* Returns the database values set in the configuration
* @return the database values set in the configuration
* @deprecated use {@link #getDatastoreConfig()}
*/
@@ -153,22 +172,26 @@ public interface LPConfiguration {
MySQLConfiguration getDatabaseValues();
/**
* Returns the values set for data storage in the configuration
* @return the values set for data storage in the configuration
*/
DatastoreConfiguration getDatastoreConfig();
/**
* Returns the storage method string from the configuration
* @return the storage method string from the configuration
*/
String getStorageMethod();
/**
* Returns true if split storage is enabled
* @return true if split storage is enabled
* @since 2.7
*/
boolean getSplitStorage();
/**
* Returns a map of split storage options
* @return a map of split storage options, where the key is the storage section, and the value is the storage
* method. For example: key = user, value = json
* @since 2.7

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

@@ -23,14 +23,14 @@
package me.lucko.luckperms.api;
/**
* Represents a Node and where it was inherited from.
* A node with a traceable origin
*
* @since 2.11
*/
public interface LocalizedNode extends Node {
/**
* Gets the node
* Gets the delegate node
*
* @return the node this instance is representing
*/

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

@@ -27,10 +27,11 @@ import java.util.SortedSet;
import java.util.UUID;
/**
* Represents the internal LuckPerms log. All content internally is immutable. You can add to the log using the {@link
* Datastore}, and then request an updated copy.
* 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.
*/
@SuppressWarnings("unused")
public interface Log {
/**
@@ -48,6 +49,8 @@ public interface Log {
*
* @param pageNo the page number
* @return the page content
* @throws IllegalArgumentException if the pageNo is less than 1
* @throws IllegalStateException if the log doesn't contain enough entries to populate the page. See {@link #getRecentMaxPages()}}
*/
SortedMap<Integer, LogEntry> getRecent(int pageNo);
@@ -69,6 +72,8 @@ public interface Log {
* @param pageNo the page number
* @param actor the uuid of the actor to filter by
* @return the page content
* @throws IllegalArgumentException if the pageNo is less than 1
* @throws IllegalStateException if the log doesn't contain enough entries to populate the page. See {@link #getRecentMaxPages(UUID)}}
*/
SortedMap<Integer, LogEntry> getRecent(int pageNo, UUID actor);
@@ -91,6 +96,8 @@ public interface Log {
* @param pageNo the page number
* @param uuid the uuid of the acted user to filter by
* @return the page content
* @throws IllegalArgumentException if the pageNo is less than 1
* @throws IllegalStateException if the log doesn't contain enough entries to populate the page. See {@link #getUserHistoryMaxPages(UUID)}}
*/
SortedMap<Integer, LogEntry> getUserHistory(int pageNo, UUID uuid);
@@ -113,6 +120,8 @@ public interface Log {
* @param pageNo the page number
* @param name the name of the acted group to filter by
* @return the page content
* @throws IllegalArgumentException if the pageNo is less than 1
* @throws IllegalStateException if the log doesn't contain enough entries to populate the page. See {@link #getGroupHistoryMaxPages(String)}}
*/
SortedMap<Integer, LogEntry> getGroupHistory(int pageNo, String name);
@@ -141,9 +150,12 @@ public interface Log {
/**
* @param name the name to filter by
* @return the max page number allowed in the {@link #getTrackHistory(int, String)} method
* @throws IllegalArgumentException if the pageNo is less than 1
* @throws IllegalStateException if the log doesn't contain enough entries to populate the page. See {@link #getTrackHistoryMaxPages(String)}}
*/
int getTrackHistoryMaxPages(String name);
/**
* @param query the query to filter by
* @return all content in this log where the content matches query
@@ -156,6 +168,8 @@ public interface Log {
* @param pageNo the page number
* @param query the query to filter by
* @return the page content
* @throws IllegalArgumentException if the pageNo is less than 1
* @throws IllegalStateException if the log doesn't contain enough entries to populate the page. See {@link #getSearchMaxPages(String)}}
*/
SortedMap<Integer, LogEntry> getSearch(int pageNo, String query);

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

@@ -25,9 +25,10 @@ package me.lucko.luckperms.api;
import java.util.UUID;
/**
* Represents a single entry in a log
* A single entry in the log
*
* <p> Implements {@link Comparable} ordering based upon the timestamp of the entry.
*/
@SuppressWarnings({"unused", "WeakerAccess"})
public class LogEntry implements Comparable<LogEntry> {
private static final String FORMAT = "&8(&e%s&8) [&a%s&8] (&b%s&8) &7--> &f%s";
@@ -154,9 +155,15 @@ public class LogEntry implements Comparable<LogEntry> {
@Override
public String toString() {
return "LogEntry(timestamp=" + this.getTimestamp() + ", actor=" + this.getActor() + ", actorName=" +
this.getActorName() + ", type=" + this.getType() + ", acted=" + this.getActed() + ", actedName=" +
this.getActedName() + ", action=" + this.getAction() + ")";
return "LogEntry(" +
"timestamp=" + this.getTimestamp() + ", " +
"actor=" + this.getActor() + ", " +
"actorName=" + this.getActorName() + ", " +
"type=" + this.getType() + ", " +
"acted=" + this.getActed() + ", " +
"actedName=" + this.getActedName() + ", " +
"action=" + this.getAction() +
")";
}
@Override
@@ -165,41 +172,25 @@ public class LogEntry implements Comparable<LogEntry> {
if (!(o instanceof LogEntry)) return false;
final LogEntry other = (LogEntry) o;
if (this.getTimestamp() != other.getTimestamp()) return false;
final Object this$actor = this.getActor();
final Object other$actor = other.getActor();
if (this$actor == null ? other$actor != null : !this$actor.equals(other$actor)) return false;
final Object this$actorName = this.getActorName();
final Object other$actorName = other.getActorName();
if (this$actorName == null ? other$actorName != null : !this$actorName.equals(other$actorName)) return false;
if (this.getActor() == null ? other.getActor() != null : !this.getActor().equals(other.getActor())) return false;
if (this.getActorName() == null ? other.getActorName() != null : !this.getActorName().equals(other.getActorName())) return false;
if (this.getType() != other.getType()) return false;
final Object this$acted = this.getActed();
final Object other$acted = other.getActed();
if (this$acted == null ? other$acted != null : !this$acted.equals(other$acted)) return false;
final Object this$actedName = this.getActedName();
final Object other$actedName = other.getActedName();
if (this$actedName == null ? other$actedName != null : !this$actedName.equals(other$actedName)) return false;
final Object this$action = this.getAction();
final Object other$action = other.getAction();
return this$action == null ? other$action == null : this$action.equals(other$action);
if (this.getActed() == null ? other.getActed() != null : !this.getActed().equals(other.getActed())) return false;
if (this.getActedName() == null ? other.getActedName() != null : !this.getActedName().equals(other.getActedName())) return false;
return this.getAction() == null ? other.getAction() == null : this.getAction().equals(other.getAction());
}
@Override
public int hashCode() {
final int PRIME = 59;
int result = 1;
final long $timestamp = this.getTimestamp();
result = result * PRIME + (int) ($timestamp >>> 32 ^ $timestamp);
final Object $actor = this.getActor();
result = result * PRIME + ($actor == null ? 43 : $actor.hashCode());
final Object $actorName = this.getActorName();
result = result * PRIME + ($actorName == null ? 43 : $actorName.hashCode());
result = result * PRIME + (int) (this.getTimestamp() >>> 32 ^ this.getTimestamp());
result = result * PRIME + (this.getActor() == null ? 43 : this.getActor().hashCode());
result = result * PRIME + (this.getActorName() == null ? 43 : this.getActorName().hashCode());
result = result * PRIME + this.getType();
final Object $acted = this.getActed();
result = result * PRIME + ($acted == null ? 43 : $acted.hashCode());
final Object $actedName = this.getActedName();
result = result * PRIME + ($actedName == null ? 43 : $actedName.hashCode());
final Object $action = this.getAction();
result = result * PRIME + ($action == null ? 43 : $action.hashCode());
result = result * PRIME + (this.getActed() == null ? 43 : this.getActed().hashCode());
result = result * PRIME + (this.getActedName() == null ? 43 : this.getActedName().hashCode());
result = result * PRIME + (this.getAction() == null ? 43 : this.getAction().hashCode());
return result;
}
@@ -214,6 +205,7 @@ public class LogEntry implements Comparable<LogEntry> {
protected LogEntryBuilder getThis() {
return this;
}
}
public static abstract class AbstractLogEntryBuilder<T extends LogEntry, B extends AbstractLogEntryBuilder<T, B>> {
@@ -311,9 +303,15 @@ public class LogEntry implements Comparable<LogEntry> {
@Override
public String toString() {
return "LogEntry.LogEntryBuilder(timestamp=" + getTimestamp() + ", actor=" + getActor() + ", actorName=" +
getActorName() + ", type=" + getType() + ", acted=" + getActed() + ", actedName=" + getActedName() +
", action=" + getAction() + ")";
return "LogEntry.LogEntryBuilder(" +
"timestamp=" + this.getTimestamp() + ", " +
"actor=" + this.getActor() + ", " +
"actorName=" + this.getActorName() + ", " +
"type=" + this.getType() + ", " +
"acted=" + this.getActed() + ", " +
"actedName=" + this.getActedName() + ", " +
"action=" + this.getAction() +
")";
}
}

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

@@ -23,7 +23,7 @@
package me.lucko.luckperms.api;
/**
* A wrapper interface for platform logger instances.
* 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.

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

@@ -23,6 +23,7 @@
package me.lucko.luckperms.api;
import me.lucko.luckperms.api.context.ContextListener;
import me.lucko.luckperms.api.context.ContextSet;
import me.lucko.luckperms.api.context.IContextCalculator;
import me.lucko.luckperms.api.event.LPListener;
@@ -31,9 +32,8 @@ import java.util.Set;
import java.util.UUID;
/**
* The root API interface in LuckPerms
* The root API interface for LuckPerms
*/
@SuppressWarnings("unused")
public interface LuckPermsApi {
/**
@@ -250,6 +250,13 @@ public interface LuckPermsApi {
*/
boolean isTrackLoaded(String name);
/**
* Gets the node factory instance for the platform
*
* @return the node factory
*/
NodeFactory getNodeFactory();
/**
* Returns a permission builder instance
*
@@ -279,11 +286,21 @@ public interface LuckPermsApi {
/**
* Gets a calculated context instance for the user using the rules of the platform.
* These values are calculated using the options in the configuration, and the provided calculators.
*
* <p> These values are calculated using the options in the configuration, and the provided calculators.
*
* @param user the user to get contexts for
* @return an optional containing contexts. Will return empty if the user is not online.
*/
Optional<Contexts> getContextForUser(User user);
/**
* Gets set of contexts applicable to a player using the platforms {@link IContextCalculator}s.
*
* @param player the player to calculate for. Must be the player instance for the platform.
* @return a set of contexts.
* @since 2.17
*/
ContextSet getContextForPlayer(Object player);
}

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

@@ -23,7 +23,7 @@
package me.lucko.luckperms.api;
/**
* Exposes any networking provider being used on the platform. e.g. Redis
* A means to push changes to other servers using the platforms networking
*
* @since 2.14
*/
@@ -31,7 +31,9 @@ public interface MessagingService {
/**
* Uses the messaging service to inform other servers about changes.
* This will push the update asynchronously, and this method will return almost immediately.
*
* <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.
*/
void pushUpdate();

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

@@ -31,12 +31,12 @@ import java.util.Optional;
import java.util.Set;
/**
* Represents an immutable node object
* An immutable permission node
*
* <p> Use {@link LuckPermsApi#buildNode(String)} to get an instance.
*
* @since 2.6
*/
@SuppressWarnings("unused")
public interface Node extends Map.Entry<String, Boolean> {
/**

101
api/src/main/java/me/lucko/luckperms/api/NodeFactory.java Normal file
View File

@@ -0,0 +1,101 @@
/*
* 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;
/**
* Builds {@link Node} instances
*
* @since 2.17
*/
public interface NodeFactory {
/**
* Creates a node from a serialised node string
*
* @param serialisedPermission the serialised permission string
* @param value the value of the node
* @return a node instance
* @throws NullPointerException if the permission is null
*/
Node fromSerialisedNode(String serialisedPermission, boolean value);
/**
* Creates a new node builder from a given base permission string
*
* @param permission the permission
* @return a node builder instance
* @throws NullPointerException if the permission is null
*/
Node.Builder newBuilder(String permission);
/**
* Creates a node builder instance from an existing node
*
* @param other the other node
* @return a node builder instance
* @throws NullPointerException if the other node is null
*/
Node.Builder newBuilderFromExisting(Node other);
/**
* Creates a node builder from a serialised node string
* @param serialisedPermission the serialised permission string
* @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 key value pair
*
* @param key the key
* @param value the value
* @return a node builder instance
* @throws NullPointerException if the key or value is null
*/
Node.Builder makeMetaNode(String key, String value);
/**
* Creates a node builder from a prefix string and priority
*
* @param priority the priority
* @param prefix the prefix string
* @return a node builder instance
* @throws NullPointerException if the prefix is null
*/
Node.Builder makePrefixNode(int priority, String prefix);
/**
* Creates a node builder from a prefix string and priority
*
* @param priority the priority
* @param suffix the suffix string
* @return a node builder instance
* @throws NullPointerException if the suffix is null
*/
Node.Builder makeSuffixNode(int priority, String suffix);
}

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

@@ -31,19 +31,24 @@ import java.util.Set;
import java.util.SortedSet;
/**
* Interface for internal PermissionHolder (user/group) instances
* An object capable of holding permissions
*
* <p> Any changes made will be lost unless the instance is saved back to the {@link Storage}.
*/
@SuppressWarnings("unused")
public interface PermissionHolder {
/**
* @return the identifier for this object. either a uuid string or name However, you should really just use {@link
* User#getUuid()}, {@link User#getName()} or {@link Group#getName()}
* Gets the objects name
*
* <p> {@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.
*/
String getObjectName();
/**
* Gets an immutable Set of the objects permission nodes
* Gets a sorted set of all held permissions.
*
* @return an immutable set of permissions in priority order
* @since 2.6
@@ -51,20 +56,22 @@ public interface PermissionHolder {
SortedSet<? extends Node> getPermissions();
/**
* Similar to {@link #getPermissions()}, except excluding transient permissions
* Similar to {@link #getPermissions()}, except without transient permissions
*
* @return a set of nodes
* @since 2.6
*/
Set<Node> getEnduringPermissions();
Set<? extends Node> getEnduringPermissions();
/**
* Similar to {@link #getPermissions()}, except excluding non-transient permissions
* Gets an immutable set of all transiently held permissions.
*
* <p> Transient permissions only exist for the duration of the session.
*
* @return a set of nodes
* @since 2.6
*/
Set<Node> getTransientPermissions();
Set<? extends Node> getTransientPermissions();
/**
@@ -91,7 +98,7 @@ public interface PermissionHolder {
SortedSet<LocalizedNode> getAllNodes(Contexts contexts);
/**
* Gets a mutable set of the nodes that is objects has and inherits, filtered by context.
* 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.
*
@@ -102,6 +109,14 @@ public interface PermissionHolder {
*/
Set<LocalizedNode> getAllNodesFiltered(Contexts contexts);
/**
* 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
*/
Map<String, Boolean> exportNodes(Contexts contexts, boolean lowerCase);
/**
* Gets an immutable Map of the objects permission nodes
*
@@ -111,6 +126,11 @@ public interface PermissionHolder {
@Deprecated
Map<String, Boolean> getNodes();
/**
* Removes temporary permissions that have expired
*/
void auditTemporaryPermissions();
/**
* Checks to see if the object has a certain permission
*
@@ -508,6 +528,109 @@ public interface PermissionHolder {
@Deprecated
void unsetPermission(String node, String server, String world, boolean temporary) throws ObjectLacksException;
/**
* Clears all nodes held by the object
*
* @since 2.17
*/
void clearNodes();
/**
* Clears all nodes held by the object on a specific server
*
* @param server the server to filter by, can be null
* @since 2.17
*/
void clearNodes(String server);
/**
* Clears all nodes held by the object on a specific server and world
*
* @param server the server to filter by, can be null
* @param world the world to filter by, can be null
* @since 2.17
*/
void clearNodes(String server, String world);
/**
* Clears all parent groups
*
* @since 2.17
*/
void clearParents();
/**
* Clears all parents on a specific server
*
* @param server the server to filter by, can be null
* @since 2.17
*/
void clearParents(String server);
/**
* Clears all parents on a specific server and world
*
* @param server the server to filter by, can be null
* @param world the world to filter by, can be null
* @since 2.17
*/
void clearParents(String server, String world);
/**
* Clears all meta held by the object
*
* @since 2.17
*/
void clearMeta();
/**
* Clears all meta held by the object on a specific server
*
* @param server the server to filter by, can be null
* @since 2.17
*/
void clearMeta(String server);
/**
* Clears all meta held by the object on a specific server and world
*
* @param server the server to filter by, can be null
* @param world the world to filter by, can be null
* @since 2.17
*/
void clearMeta(String server, String world);
/**
* Clears all meta for a given key.
*
* @param key the meta key
* @param server the server to filter by, can be null
* @param world the world to filter by, can be null
* @param temporary whether the query is for temporary nodes or not.
*/
void clearMetaKeys(String key, String server, String world, boolean temporary);
/**
* Clears all transient permissions the holder has.
*/
void clearTransientNodes();
/**
* Processes the nodes and returns the non-temporary ones.
*
* @return a set of permanent nodes
* @since 2.6
*/
Set<Node> getPermanentPermissionNodes();
/**
* Processes the nodes and returns the temporary ones.
*
* @return a set of temporary nodes
* @since 2.6
*/
Set<Node> getTemporaryPermissionNodes();
/**
* Gets the permissions and inherited permissions that apply to a specific server and world
*
@@ -581,14 +704,6 @@ public interface PermissionHolder {
@Deprecated
Map<Map.Entry<String, Boolean>, Long> getTemporaryNodes();
/**
* Processes the nodes and returns the temporary ones.
*
* @return a set of temporary nodes
* @since 2.6
*/
Set<Node> getTemporaryPermissionNodes();
/**
* Processes the nodes and returns the non-temporary ones.
*
@@ -598,17 +713,4 @@ public interface PermissionHolder {
@Deprecated
Map<String, Boolean> getPermanentNodes();
/**
* Processes the nodes and returns the non-temporary ones.
*
* @return a set of permanent nodes
* @since 2.6
*/
Set<Node> getPermanentPermissionNodes();
/**
* Removes temporary permissions that have expired
*/
void auditTemporaryPermissions();
}

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

@@ -23,7 +23,7 @@
package me.lucko.luckperms.api;
/**
* Represents the platform type that LuckPerms is running on
* The platforms which LuckPerms can run on
*
* @since 2.7
*/

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

@@ -22,6 +22,7 @@
package me.lucko.luckperms.api;
import java.util.List;
import java.util.Set;
import java.util.UUID;
import java.util.concurrent.CompletableFuture;
@@ -29,7 +30,7 @@ import java.util.concurrent.Executor;
import java.util.function.Consumer;
/**
* Interface for the internal Storage instance
* A means of loading and saving data to/from the Storage provider.
*
* <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
@@ -124,6 +125,16 @@ public interface Storage {
*/
CompletableFuture<Set<UUID>> getUniqueUsers();
/**
* Searches for a list of users with a given permission.
*
* @param permission the permission to search for
* @return a list of held permissions, or null if the operation failed
* @throws NullPointerException if the permission is null
* @since 2.17
*/
CompletableFuture<List<HeldPermission<UUID>>> getUsersWithPermission(String permission);
/**
* Creates and loads a group into the plugins local storage
*
@@ -171,6 +182,16 @@ public interface Storage {
*/
CompletableFuture<Boolean> deleteGroup(Group group);
/**
* Searches for a list of groups with a given permission.
*
* @param permission the permission to search for
* @return a list of held permissions, or null if the operation failed
* @throws NullPointerException if the permission is null
* @since 2.17
*/
CompletableFuture<List<HeldPermission<String>>> getGroupsWithPermission(String permission);
/**
* Creates and loads a track into the plugins local storage
*
@@ -239,4 +260,14 @@ public interface Storage {
*/
CompletableFuture<UUID> getUUID(String username);
/**
* Gets a username from a UUID
*
* @param uuid the corresponding uuid
* @return a name string, could be null
* @throws NullPointerException if either parameters are null
* @since 2.17
*/
CompletableFuture<String> getName(UUID uuid);
}

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

@@ -28,19 +28,20 @@ import me.lucko.luckperms.exceptions.ObjectLacksException;
import java.util.List;
/**
* Interface for internal Track instances
* An ordered collection of groups for easy promotions and demotions
*/
@SuppressWarnings("unused")
public interface Track {
/**
* Gets the name of this track
* @return the name of this track
*/
String getName();
/**
* Gets an ordered list of the groups on this track
* 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
*
* @return an ordered {@link List} of the groups on this track
*/
@@ -136,7 +137,7 @@ public interface Track {
boolean containsGroup(String group);
/**
* Clear all of the groups within this track
* Clear all of the groups from this track
*/
void clearGroups();

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

@@ -23,14 +23,34 @@
package me.lucko.luckperms.api;
/**
* Represents a permission value
* 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.
*/
public enum Tristate {
/**
* A value indicating a holder has a permission set.
*/
TRUE(true),
/**
* A value indicating a holder has a negated value for a permission.
*/
FALSE(false),
/**
* A value indicating a holder doesn't have a value for a permission set.
*/
UNDEFINED(false);
/**
* Converts from {@link Boolean} a boolean
*
* @param b the boolean
* @return {@link #TRUE} or {@link #FALSE}, depending on the value of the boolean.
*/
public static Tristate fromBoolean(boolean b) {
return b ? TRUE : FALSE;
}
@@ -41,6 +61,12 @@ public enum Tristate {
this.booleanValue = booleanValue;
}
/**
* Returns the value of the Tristate as a boolean.
* <p> A value of {@link #UNDEFINED} converts to false.
*
* @return a boolean representation of the Tristate.
*/
public boolean asBoolean() {
return booleanValue;
}

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

@@ -31,17 +31,20 @@ import java.util.Optional;
import java.util.UUID;
/**
* Interface for internal User instances
* A player holding permission data
*/
@SuppressWarnings("unused")
public interface User extends PermissionHolder {
/**
* Gets the users unique ID
*
* @return the users Mojang assigned unique id
*/
UUID getUuid();
/**
* Gets the users username
*
* @return the Users Username
*/
String getName();
@@ -64,7 +67,10 @@ public interface User extends PermissionHolder {
void setPrimaryGroup(String group) throws ObjectAlreadyHasException;
/**
* Refresh and re-assign the users permissions
* 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.
*/
void refreshPermissions();
@@ -76,6 +82,13 @@ public interface User extends PermissionHolder {
*/
Optional<UserData> getUserDataCache();
/**
* Sets up the users data cache, if the don't have one setup already.
*
* @since 2.17
*/
void setupDataCache();
/**
* Check to see if the user is a member of a group
*
@@ -255,11 +268,6 @@ public interface User extends PermissionHolder {
*/
void removeGroup(Group group, String server, String world, boolean temporary) throws ObjectLacksException;
/**
* Clear all of the users permission nodes
*/
void clearNodes();
/**
* Get a {@link List} of all of the groups the user is a member of, on all servers
*

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

@@ -28,16 +28,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
* servers or mixed offline mode and online mode servers. Platforms running in offline mode generate a random UUID for a
* 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
* this cache, OR use Storage#getUUID, for users that are not online.
*
* <p> WARNING: THIS IS ONLY EFFECTIVE FOR ONLINE PLAYERS. USE THE DATASTORE METHODS FOR OFFLINE PLAYERS.
* <p> THIS IS ONLY EFFECTIVE FOR ONLINE PLAYERS. USE THE DATASTORE METHODS FOR OFFLINE PLAYERS.
*/
@SuppressWarnings("unused")
public interface UuidCache {
/**

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

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

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

@@ -38,7 +38,8 @@ 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.
*
* <p> 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
@@ -48,7 +49,8 @@ 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.
*
* <p> 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
@@ -75,8 +77,10 @@ public interface UserData {
MetaData calculateMeta(Contexts contexts);
/**
* 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.
* 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.
*
* @param contexts the contexts to recalculate in.
* @throws NullPointerException if contexts is null
@@ -84,8 +88,10 @@ public interface UserData {
void recalculatePermissions(Contexts contexts);
/**
* 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.
* 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.
*
* @param contexts the contexts to recalculate in.
* @throws NullPointerException if contexts is null
@@ -111,8 +117,9 @@ public interface UserData {
void preCalculate(Set<Contexts> contexts);
/**
* 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.
* 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.
*
* @param contexts the contexts to pre-calculate for
* @throws NullPointerException if contexts is null