me.lucko.luckperms.api.LuckPermsApi Maven / Gradle / Ivy
Show all versions of luckperms-api Show documentation
/*
* This file is part of LuckPerms, licensed under the MIT License.
*
* Copyright (c) lucko (Luck)
* Copyright (c) contributors
*
* 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.LuckPerms;
import me.lucko.luckperms.api.context.ContextCalculator;
import me.lucko.luckperms.api.context.ContextManager;
import me.lucko.luckperms.api.context.ContextSet;
import me.lucko.luckperms.api.event.EventBus;
import me.lucko.luckperms.api.manager.GroupManager;
import me.lucko.luckperms.api.manager.TrackManager;
import me.lucko.luckperms.api.manager.UserManager;
import me.lucko.luckperms.api.messenger.MessengerProvider;
import me.lucko.luckperms.api.metastacking.MetaStackFactory;
import me.lucko.luckperms.api.platform.PlatformInfo;
import org.checkerframework.checker.nullness.qual.NonNull;
import org.checkerframework.checker.nullness.qual.Nullable;
import java.util.Collection;
import java.util.Optional;
import java.util.Set;
import java.util.UUID;
import java.util.concurrent.CompletableFuture;
/**
* 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 {@link LuckPerms#getApi()}, or the platforms
* Services Manager.
*/
public interface LuckPermsApi {
/**
* Gets information about the platform LuckPerms is running on.
*
* @return the platform info
* @since 4.0
*/
@NonNull PlatformInfo getPlatformInfo();
/**
* Gets the {@link UserManager}, responsible for managing
* {@link User} instances.
*
* This manager can be used to retrieve instances of {@link User} by uuid
* or name, or query all loaded users.
*
* The {@link #getStorage() storage} instance should be used to
* load/create/save users.
*
* @return the user manager
* @since 4.0
*/
@NonNull UserManager getUserManager();
/**
* Gets the {@link GroupManager}, responsible for managing
* {@link Group} instances.
*
* This manager can be used to retrieve instances of {@link Group} by
* name, or query all loaded groups.
*
* The {@link #getStorage() storage} instance should be used to
* load/create/save/delete groups.
*
* @return the group manager
* @since 4.0
*/
@NonNull GroupManager getGroupManager();
/**
* Gets the {@link TrackManager}, responsible for managing
* {@link Track} instances.
*
* This manager can be used to retrieve instances of {@link Track} by
* name, or query all loaded tracks.
*
* The {@link #getStorage() storage} instance should be used to
* load/create/save/delete tracks.
*
* @return the track manager
* @since 4.0
*/
@NonNull TrackManager getTrackManager();
/**
* Schedules the execution of an update task, and returns an encapsulation
* of the task as a {@link 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.
*
* @return a future
* @since 4.0
*/
@NonNull CompletableFuture runUpdateTask();
/**
* Gets the {@link EventBus}, used for subscribing to internal LuckPerms
* events.
*
* @return the event bus
* @since 3.0
*/
@NonNull EventBus getEventBus();
/**
* Gets a representation of the plugins configuration
*
* @return the configuration
*/
@NonNull LPConfiguration getConfiguration();
/**
* Gets an object representing the plugins primary {@link Storage} backend.
*
* The instance propagates calls to the internal DAO (Data Access Object),
* and applies any changes to the storage provider.
*
* @return a storage instance
* @since 2.14
*/
@NonNull Storage getStorage();
/**
* Gets the {@link 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.
*
* @return the messaging service instance, if present.
*/
@NonNull Optional getMessagingService();
/**
* Registers a {@link MessengerProvider} for use by the platform.
*
* Note that the mere action of registering a provider doesn't
* necessarily mean that it will be used.
*
* @param messengerProvider the messenger provider.
* @since 4.1
*/
void registerMessengerProvider(@NonNull MessengerProvider messengerProvider);
/**
* Gets the {@link ActionLogger}.
*
* The action logger is responsible for saving and broadcasting defined
* actions occurring on the platform.
*
* @return the action logger
* @since 4.1
*/
@NonNull ActionLogger getActionLogger();
/**
* Gets a {@link UuidCache}.
*
* The uuid cache provides read access to the internal LuckPerms uuid
* mapping system.
*
* @return the uuid cache
* @deprecated this feature is now handled internally - and the API returns a
* No-op implementation of this class.
*/
@Deprecated
@NonNull UuidCache getUuidCache();
/**
* Gets the {@link ContextManager}.
*
* The context manager manages {@link ContextCalculator}s, and calculates
* applicable contexts for a given type.
*
* @return the context manager
* @since 4.0
*/
@NonNull ContextManager getContextManager();
/**
* Gets a {@link Collection} of all known permission strings.
*
* @return a collection of the known permissions
* @since 4.4
*/
@NonNull Collection getKnownPermissions();
/**
* Gets the {@link NodeFactory}.
*
* The node factory provides methods for building {@link Node} instances.
*
* @return the node factory
*/
@NonNull NodeFactory getNodeFactory();
/**
* Gets the {@link MetaStackFactory}.
*
* The metastack factory provides methods for retrieving
* {@link me.lucko.luckperms.api.metastacking.MetaStackElement}s and constructing
* {@link me.lucko.luckperms.api.metastacking.MetaStackDefinition}s.
*
* @return the meta stack factory
* @since 3.2
*/
@NonNull MetaStackFactory getMetaStackFactory();
/*
* The following methods are provided only for convenience, and offer no
* additional functionality.
*
* They are implemented as "default" methods, using the manager and factory
* instances provided by the methods above.
*/
/**
* Gets a wrapped user object from the user storage
*
* @param uuid the uuid of the user to get
* @return a {@link User} object, if one matching the uuid is loaded, or null if not
* @throws NullPointerException if the uuid is null
*/
default @Nullable User getUser(@NonNull UUID uuid) {
return getUserManager().getUser(uuid);
}
/**
* Gets a wrapped user object from the user storage.
*
* @param uuid the uuid of the user to get
* @return an optional {@link User} object
* @throws NullPointerException if the uuid is null
*/
default @NonNull Optional getUserSafe(@NonNull UUID uuid) {
return getUserManager().getUserOpt(uuid);
}
/**
* Gets a wrapped user object from the user storage
*
* @param name the username of the user to get
* @return a {@link User} object, if one matching the uuid is loaded, or null if not
* @throws NullPointerException if the name is null
*/
default @Nullable User getUser(@NonNull String name) {
return getUserManager().getUser(name);
}
/**
* Gets a wrapped user object from the user storage.
*
* @param name the username of the user to get
* @return an optional {@link User} object
* @throws NullPointerException if the name is null
*/
default @NonNull Optional getUserSafe(@NonNull String name) {
return getUserManager().getUserOpt(name);
}
/**
* Gets a set of all loaded users.
*
* @return a {@link Set} of {@link User} objects
*/
default @NonNull Set getUsers() {
return getUserManager().getLoadedUsers();
}
/**
* Check if a user is loaded in memory
*
* @param uuid the uuid to check for
* @return true if the user is loaded
* @throws NullPointerException if the uuid is null
*/
default boolean isUserLoaded(@NonNull UUID uuid) {
return getUserManager().isLoaded(uuid);
}
/**
* Unload a user from the internal storage, if they're not currently online.
*
* @param user the user to unload
* @throws NullPointerException if the user is null
*/
default void cleanupUser(@NonNull User user) {
getUserManager().cleanupUser(user);
}
/**
* Gets a wrapped group object from the group storage
*
* @param name the name of the group to get
* @return a {@link Group} object, if one matching the name exists, or null if not
* @throws NullPointerException if the name is null
*/
default @Nullable Group getGroup(@NonNull String name) {
return getGroupManager().getGroup(name);
}
/**
* Gets a wrapped group object from the group storage.
*
* This method does not return null, unlike {@link #getGroup}
*
* @param name the name of the group to get
* @return an optional {@link Group} object
* @throws NullPointerException if the name is null
*/
default @NonNull Optional getGroupSafe(@NonNull String name) {
return getGroupManager().getGroupOpt(name);
}
/**
* Gets a set of all loaded groups.
*
* @return a {@link Set} of {@link Group} objects
*/
default @NonNull Set getGroups() {
return getGroupManager().getLoadedGroups();
}
/**
* Check if a group is loaded in memory
*
* @param name the name to check for
* @return true if the group is loaded
* @throws NullPointerException if the name is null
*/
default boolean isGroupLoaded(@NonNull String name) {
return getGroupManager().isLoaded(name);
}
/**
* Gets a wrapped track object from the track storage
*
* @param name the name of the track to get
* @return a {@link Track} object, if one matching the name exists, or null
* if not
* @throws NullPointerException if the name is null
*/
default @Nullable Track getTrack(@NonNull String name) {
return getTrackManager().getTrack(name);
}
/**
* Gets a wrapped track object from the track storage.
*
* This method does not return null, unlike {@link #getTrack}
*
* @param name the name of the track to get
* @return an optional {@link Track} object
* @throws NullPointerException if the name is null
*/
default @NonNull Optional