me.lucko.luckperms.api

Interface LuckPermsApi

public interface LuckPermsApi

The LuckPerms API.

This interface is the base of the entire API package. All API functions are accessed via this interface.

An instance can be obtained via LuckPerms.getApi(), or the platforms Services Manager.

Method Summary

Modifier and Type	Method and Description
default Node.Builder	buildNode(String permission) Returns a permission builder instance
default void	cleanupUser(User user) Unload a user from the internal storage, if they're not currently online.
ActionLogger	getActionLogger() Gets the ActionLogger.
LPConfiguration	getConfiguration() Gets a representation of the plugins configuration
default ContextSet	getContextForPlayer(Object player) Gets set of contexts applicable to a player using the platforms ContextCalculators.
default Optional<Contexts>	getContextForUser(User user) Gets a calculated context instance for the user using the rules of the platform.
ContextManager	getContextManager() Gets the ContextManager.
default Contexts	getContextsForPlayer(Object player) Gets a Contexts instance for the player using the platforms ContextCalculators.
EventBus	getEventBus() Gets the EventBus, used for subscribing to internal LuckPerms events.
default Group	getGroup(String name) Gets a wrapped group object from the group storage
GroupManager	getGroupManager() Gets the GroupManager, responsible for managing Group instances.
default Set<Group>	getGroups() Gets a set of all loaded groups.
default Optional<Group>	getGroupSafe(String name) Gets a wrapped group object from the group storage.
Optional<MessagingService>	getMessagingService() Gets the MessagingService, if present.
MetaStackFactory	getMetaStackFactory() Gets the MetaStackFactory.
NodeFactory	getNodeFactory() Gets the NodeFactory.
PlatformInfo	getPlatformInfo() Gets information about the platform LuckPerms is running on.
Storage	getStorage() Gets an object representing the plugins primary Storage backend.
default Track	getTrack(String name) Gets a wrapped track object from the track storage
TrackManager	getTrackManager() Gets the TrackManager, responsible for managing Track instances.
default Set<Track>	getTracks() Gets a set of all loaded tracks.
default Optional<Track>	getTrackSafe(String name) Gets a wrapped track object from the track storage.
default User	getUser(String name) Gets a wrapped user object from the user storage
default User	getUser(UUID uuid) Gets a wrapped user object from the user storage
UserManager	getUserManager() Gets the UserManager, responsible for managing User instances.
default Set<User>	getUsers() Gets a set of all loaded users.
default Optional<User>	getUserSafe(String name) Gets a wrapped user object from the user storage.
default Optional<User>	getUserSafe(UUID uuid) Gets a wrapped user object from the user storage.
UuidCache	getUuidCache() Deprecated. this feature is now handled internally - and the API returns a No-op implementation of this class.
default boolean	isGroupLoaded(String name) Check if a group is loaded in memory
default boolean	isTrackLoaded(String name) Check if a track is loaded in memory
default boolean	isUserLoaded(UUID uuid) Check if a user is loaded in memory
default LogEntry.Builder	newLogEntryBuilder() Returns a new LogEntry Builder instance
default void	registerContextCalculator(ContextCalculator<?> calculator) Register a custom context calculator to the server
void	registerMessengerProvider(MessengerProvider messengerProvider) Registers a MessengerProvider for use by the platform.
CompletableFuture<Void>	runUpdateTask() Schedules the execution of an update task, and returns an encapsulation of the task as a CompletableFuture.

Method Detail

getPlatformInfo

@Nonnull
PlatformInfo getPlatformInfo()

Gets information about the platform LuckPerms is running on.

Returns:

the platform info

Since:

4.0

getUserManager

@Nonnull
UserManager getUserManager()

Gets the UserManager, responsible for managing User instances.

This manager can be used to retrieve instances of User by uuid or name, or query all loaded users.

The storage instance should be used to load/create/save users.

Returns:

the user manager

Since:

4.0

getGroupManager

@Nonnull
GroupManager getGroupManager()

Gets the GroupManager, responsible for managing Group instances.

This manager can be used to retrieve instances of Group by name, or query all loaded groups.

The storage instance should be used to load/create/save/delete groups.

Returns:

the group manager

Since:

4.0

getTrackManager

@Nonnull
TrackManager getTrackManager()

Gets the TrackManager, responsible for managing Track instances.

This manager can be used to retrieve instances of Track by name, or query all loaded tracks.

The storage instance should be used to load/create/save/delete tracks.

Returns:

the track manager

Since:

4.0

runUpdateTask

@Nonnull
CompletableFuture<Void> runUpdateTask()

Schedules the execution of an update task, and returns an encapsulation of the task as a CompletableFuture.

The exact actions performed in an update task remains an implementation detail of the plugin, however, as a minimum, it is expected to perform a full reload of user, group and track data, and ensure that any changes are fully applied and propagated.

Returns:

a future

Since:

4.0

getEventBus

@Nonnull
EventBus getEventBus()

Gets the EventBus, used for subscribing to internal LuckPerms events.

Returns:

the event bus

Since:

3.0

getConfiguration

@Nonnull
LPConfiguration getConfiguration()

Gets a representation of the plugins configuration

Returns:

the configuration

getStorage

@Nonnull
Storage getStorage()

Gets an object representing the plugins primary Storage backend.

The instance propagates calls to the internal DAO (Data Access Object), and applies any changes to the storage provider.

Returns:

a storage instance

Since:

2.14

getMessagingService

@Nonnull
Optional<MessagingService> getMessagingService()

Gets the MessagingService, if present.

The MessagingService is used to dispatch updates throughout a network of servers running the plugin.

Not all instances of LuckPerms will have a messaging service setup and configured, but it is recommended that all users of the API account for and make use of this.

Returns:

the messaging service instance, if present.

registerMessengerProvider

void registerMessengerProvider(@Nonnull
                               MessengerProvider messengerProvider)

Registers a MessengerProvider for use by the platform.

Note that the mere action of registering a provider doesn't necessarily mean that it will be used.

Parameters:

messengerProvider - the messenger provider.

Since:

4.1

getActionLogger

ActionLogger getActionLogger()

Gets the ActionLogger.

The action logger is responsible for saving and broadcasting defined actions occurring on the platform.

Returns:

the action logger

Since:

4.1

getUuidCache

@Nonnull
 @Deprecated
UuidCache getUuidCache()

Deprecated. this feature is now handled internally - and the API returns a No-op implementation of this class.

Gets a UuidCache.

The uuid cache provides read access to the internal LuckPerms uuid mapping system.

Returns:

the uuid cache

getContextManager

ContextManager getContextManager()

Gets the ContextManager.

The context manager manages ContextCalculators, and calculates applicable contexts for a given type.

Returns:

the context manager

Since:

4.0

getNodeFactory

@Nonnull
NodeFactory getNodeFactory()

Gets the NodeFactory.

The node factory provides methods for building Node instances.

Returns:

the node factory

getMetaStackFactory

@Nonnull
MetaStackFactory getMetaStackFactory()

Gets the MetaStackFactory.

The metastack factory provides methods for retrieving MetaStackElements and constructing MetaStackDefinitions.

Returns:

the meta stack factory

Since:

3.2

getUser

@Nullable
default User getUser(@Nonnull
                                UUID uuid)

Gets a wrapped user object from the user storage

Parameters:

uuid - the uuid of the user to get

Returns:

a User object, if one matching the uuid is loaded, or null if not

Throws:

NullPointerException - if the uuid is null

getUserSafe

@Nonnull
default Optional<User> getUserSafe(@Nonnull
                                             UUID uuid)

Gets a wrapped user object from the user storage.

Parameters:

uuid - the uuid of the user to get

Returns:

an optional User object

Throws:

NullPointerException - if the uuid is null

getUser

@Nullable
default User getUser(@Nonnull
                                String name)

Gets a wrapped user object from the user storage

Parameters:

name - the username of the user to get

Returns:

a User object, if one matching the uuid is loaded, or null if not

Throws:

NullPointerException - if the name is null

getUserSafe

@Nonnull
default Optional<User> getUserSafe(@Nonnull
                                             String name)

Gets a wrapped user object from the user storage.

Parameters:

name - the username of the user to get

Returns:

an optional User object

Throws:

NullPointerException - if the name is null

getUsers

@Nonnull
default Set<User> getUsers()

Gets a set of all loaded users.

Returns:

a Set of User objects

isUserLoaded

default boolean isUserLoaded(@Nonnull
                             UUID uuid)

Check if a user is loaded in memory

Parameters:

uuid - the uuid to check for

Returns:

true if the user is loaded

Throws:

NullPointerException - if the uuid is null

cleanupUser

default void cleanupUser(@Nonnull
                         User user)

Unload a user from the internal storage, if they're not currently online.

Parameters:

user - the user to unload

Throws:

NullPointerException - if the user is null

getGroup

@Nullable
default Group getGroup(@Nonnull
                                  String name)

Gets a wrapped group object from the group storage

Parameters:

name - the name of the group to get

Returns:

a Group object, if one matching the name exists, or null if not

Throws:

NullPointerException - if the name is null

getGroupSafe

@Nonnull
default Optional<Group> getGroupSafe(@Nonnull
                                               String name)

Gets a wrapped group object from the group storage.

This method does not return null, unlike getGroup(java.lang.String)

Parameters:

name - the name of the group to get

Returns:

an optional Group object

Throws:

NullPointerException - if the name is null

getGroups

@Nonnull
default Set<Group> getGroups()

Gets a set of all loaded groups.

Returns:

a Set of Group objects

isGroupLoaded

default boolean isGroupLoaded(@Nonnull
                              String name)

Check if a group is loaded in memory

Parameters:

name - the name to check for

Returns:

true if the group is loaded

Throws:

NullPointerException - if the name is null

getTrack

@Nullable
default Track getTrack(@Nonnull
                                  String name)

Gets a wrapped track object from the track storage

Parameters:

name - the name of the track to get

Returns:

a Track object, if one matching the name exists, or null if not

Throws:

NullPointerException - if the name is null

getTrackSafe

@Nonnull
default Optional<Track> getTrackSafe(@Nonnull
                                               String name)

Gets a wrapped track object from the track storage.

This method does not return null, unlike getTrack(java.lang.String)

Parameters:

name - the name of the track to get

Returns:

an optional Track object

Throws:

NullPointerException - if the name is null

getTracks

@Nonnull
default Set<Track> getTracks()

Gets a set of all loaded tracks.

Returns:

a Set of Track objects

isTrackLoaded

default boolean isTrackLoaded(@Nonnull
                              String name)

Check if a track is loaded in memory

Parameters:

name - the name to check for

Returns:

true if the track is loaded

Throws:

NullPointerException - if the name is null

newLogEntryBuilder

@Nonnull
default LogEntry.Builder newLogEntryBuilder()

Returns a new LogEntry Builder instance

Returns:

a new builder

Since:

4.0

buildNode

@Nonnull
default Node.Builder buildNode(@Nonnull
                                         String permission)
                                  throws IllegalArgumentException

Returns a permission builder instance

Parameters:

permission - the main permission node to build

Returns:

a Node.Builder instance

Throws:

IllegalArgumentException - if the permission is invalid

NullPointerException - if the permission is null

Since:

2.6

registerContextCalculator

default void registerContextCalculator(@Nonnull
                                       ContextCalculator<?> calculator)

Register a custom context calculator to the server

Parameters:

calculator - the context calculator to register. The type MUST be the player class of the platform.

Throws:

ClassCastException - if the type is not the player class of the platform.

getContextForUser

@Nonnull
default Optional<Contexts> getContextForUser(@Nonnull
                                                       User user)

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.

Parameters:

user - the user to get contexts for

Returns:

an optional containing contexts. Will return empty if the user is not online.

getContextForPlayer

@Nonnull
default ContextSet getContextForPlayer(@Nonnull
                                                 Object player)

Gets set of contexts applicable to a player using the platforms ContextCalculators.

Parameters:

player - the player to calculate for. Must be the player instance for the platform.

Returns:

a set of contexts.

Since:

2.17

getContextsForPlayer

@Nonnull
default Contexts getContextsForPlayer(@Nonnull
                                                Object player)

Gets a Contexts instance for the player using the platforms ContextCalculators.

Parameters:

player - the player to calculate for. Must be the player instance for the platform.

Returns:

a set of contexts.

Since:

3.3