Package me.keehl.elevators.api

Class ElevatorsAPI

java.lang.Object

me.keehl.elevators.api.ElevatorsAPI

public final class ElevatorsAPI
extends java.lang.Object

Constructor Summary

Constructors

Constructor	Description
ElevatorsAPI()

Method Summary

Modifier and Type	Method	Description
static @NotNull IElevatorActionBuilder	actionBuilder(@NotNull java.lang.String actionKey)	Creates a builder for defining a new elevator action.
static @NotNull IElevators	getElevators()	Returns the registered IElevators service from Bukkit's ServicesManager.
static @NotNull java.util.logging.Logger	getLogger()	Returns the underlying Logger used by the Elevators logging system.
static void	holdLog()	Starts buffering subsequent log output instead of printing immediately.
static void	log(@NotNull java.lang.Object message)	Logs a message at the default level using Elevators' structured logger.
static void	log(@NotNull java.util.logging.Level level, @NotNull java.lang.Object message)	Logs a message at the given level using Elevators' structured logger.
static void	log(@NotNull java.util.logging.Level level, @NotNull java.lang.Object message, @NotNull java.lang.Throwable throwable)	Logs a message at the given level with an associated throwable.
static @NotNull ILogReleaseData	popLog()	Pops the current indentation frame from the log stack and returns release metadata.
static @NotNull ILogReleaseData	popLog(@NotNull java.util.function.Consumer<@NotNull ILogReleaseData> onPop)	Pops the current indentation frame from the log stack and returns release metadata, running a callback before any buffered log lines are printed.
static void	pushAndHoldLog()	Convenience method equivalent to calling pushLog() and then holdLog().
static void	pushLog()	Pushes a new indentation frame onto the log stack.
static @NotNull ILogReleaseData	releaseLog()	Releases buffered logs, printing them to the console, and returns release metadata.
static @NotNull ILogReleaseData	releaseLog(@NotNull java.util.function.Consumer<@NotNull ILogReleaseData> onRelease)	Releases buffered logs, running a callback before printing, and returns release metadata.
static @Nullable IElevator	resolveElevator(@NotNull org.bukkit.block.Block block)	Creates a lightweight IElevator data record from a world Block.
static @NotNull IElevator	resolveElevator(@NotNull org.bukkit.block.ShulkerBox box, @NotNull IElevatorType elevatorType)	Creates a lightweight IElevator data record for the given shulker box and elevator type.
static @Nullable IElevatorType	resolveElevatorType(@NotNull org.bukkit.block.ShulkerBox box)	Resolves the IElevatorType associated with the given shulker box.
static <T> @NotNull IElevatorSettingBuilder<T>	settingsBuilder(@NotNull java.lang.String settingKey, T defaultValue, @NotNull org.bukkit.persistence.PersistentDataType<?,T> persistentDataType)	Creates a builder for defining a new elevator setting.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ElevatorsAPI

public ElevatorsAPI()

Method Detail

getElevators

@NotNull
public static @NotNull IElevators getElevators()

Returns the registered IElevators service from Bukkit's ServicesManager.

Returns:

the registered elevators service

Throws:

java.lang.IllegalStateException - if no IElevators service is registered

settingsBuilder

@NotNull
public static <T> @NotNull IElevatorSettingBuilder<T> settingsBuilder(@NotNull @Pattern("[a-z0-9/._-]+")
                                                                      @NotNull java.lang.String settingKey,
                                                                      @NotNull
                                                                      T defaultValue,
                                                                      @NotNull
                                                                      @NotNull org.bukkit.persistence.PersistentDataType<?,T> persistentDataType)

Creates a builder for defining a new elevator setting.

This is intended for third-party developers to add custom settings that Elevators can persist and apply to both individual elevators and elevator types.

Registration: Keys are server-wide. Calling the builder's register(...) method with a key that is already registered, or with an invalid plugin instance, throws IllegalStateException.

Contract:

• settingKey, defaultValue, and persistentDataType must be non-null.
• settingKey must match [a-z0-9/._-]+.

Type Parameters:

T - the value type of the setting

Parameters:

settingKey - unique, lowercase identifier for the setting (pattern: [a-z0-9/._-]+)

defaultValue - the non-null default value used when the setting is not present

persistentDataType - the Bukkit persistent data type used to serialize/deserialize values

Returns:

a builder used to further configure and register the setting

Throws:

java.lang.NullPointerException - if any argument is null

java.lang.IllegalStateException - if the Elevators service is not registered

actionBuilder

@NotNull
public static @NotNull IElevatorActionBuilder actionBuilder(@NotNull @Pattern("[a-z0-9/._-]+")
                                                            @NotNull java.lang.String actionKey)

Creates a builder for defining a new elevator action.

Actions are executed by elevators when a player uses an elevator (on travel), allowing third-party developers to inject custom behavior.

Registration: Keys are server-wide. Calling the builder's register(...) method with a key that is already registered, or with an invalid plugin instance, throws IllegalStateException.

Contract:

• actionKey must be non-null.
• actionKey must match [a-z0-9/._-]+.

Parameters:

actionKey - unique, lowercase identifier for the action (pattern: [a-z0-9/._-]+)

Returns:

a builder used to configure and register the action

Throws:

java.lang.NullPointerException - if actionKey is null

java.lang.IllegalStateException - if the Elevators service is not registered

resolveElevator

@NotNull
public static @NotNull IElevator resolveElevator(@NotNull
                                                 @NotNull org.bukkit.block.ShulkerBox box,
                                                 @NotNull
                                                 @NotNull IElevatorType elevatorType)

Creates a lightweight IElevator data record for the given shulker box and elevator type.

IElevator is a simple representation of an elevator instance (location, dye color, type, backing shulker box) and does not perform logic by itself. It is intended to be passed into other API methods that require both state and a resolved elevator type.

Contract:

• box, elevatorType are never null.
• This method does not make modifications.

Parameters:

box - the placed shulker box backing a potential elevator

elevatorType - the elevator type definition to associate with the returned record

Returns:

an IElevator record

Throws:

java.lang.NullPointerException - if box or elevatorType is null

java.lang.IllegalStateException - if the Elevators service is not registered

resolveElevator

@Nullable
public static @Nullable IElevator resolveElevator(@NotNull
                                                  @NotNull org.bukkit.block.Block block)

Creates a lightweight IElevator data record from a world Block.

IElevator is a simple representation of an elevator instance and does not perform logic by itself.

Contract:

• block must be non-null.
• Returns null if block is not a shulker box or if the block does not represent an elevator.
• This method does not make modifications.

Parameters:

block - the block to inspect

Returns:

an IElevator record, or null if the block is not a shulker box elevator

Throws:

java.lang.NullPointerException - if block is null

java.lang.IllegalStateException - if the Elevators service is not registered

resolveElevatorType

@Nullable
public static @Nullable IElevatorType resolveElevatorType(@NotNull
                                                          @NotNull org.bukkit.block.ShulkerBox box)

Resolves the IElevatorType associated with the given shulker box.

This method performs a lookup based on the provided ShulkerBox state and returns the matching elevator type if the shulker box represents a valid elevator.

Contract:

• box must be non-null.
• Returns null if box does not represent a valid elevator shulker box or no type is associated.

Parameters:

box - the shulker box state to inspect

Returns:

the resolved elevator type, or null if the shulker box is not a valid elevator or no type is present

Throws:

java.lang.NullPointerException - if box is null

java.lang.IllegalStateException - if the Elevators service is not registered

log

public static void log(@NotNull
                       @NotNull java.lang.Object message)

Logs a message at the default level using Elevators' structured logger.

Parameters:

message - non-null message object (converted to a string by the logger)

Throws:

java.lang.NullPointerException - if message is null

java.lang.IllegalStateException - if the Elevators service is not registered

log

public static void log(@NotNull
                       @NotNull java.util.logging.Level level,
                       @NotNull
                       @NotNull java.lang.Object message)

Logs a message at the given level using Elevators' structured logger.

Parameters:

level - non-null log level

message - non-null message object (converted to a string by the logger)

Throws:

java.lang.NullPointerException - if level or message is null

java.lang.IllegalStateException - if the Elevators service is not registered

log

public static void log(@NotNull
                       @NotNull java.util.logging.Level level,
                       @NotNull
                       @NotNull java.lang.Object message,
                       @NotNull
                       @NotNull java.lang.Throwable throwable)

Logs a message at the given level with an associated throwable.

Parameters:

level - non-null log level

message - non-null message object (converted to a string by the logger)

throwable - non-null throwable to log

Throws:

java.lang.NullPointerException - if any argument is null

java.lang.IllegalStateException - if the Elevators service is not registered

pushLog

public static void pushLog()

Pushes a new indentation frame onto the log stack.

After pushing, subsequent log output is indented one additional level until popLog() is called. Nested pushes increase indentation further.

Throws:

java.lang.IllegalStateException - if the Elevators service is not registered

popLog

@NotNull
public static @NotNull ILogReleaseData popLog(@NotNull
                                              @NotNull java.util.function.Consumer<@NotNull ILogReleaseData> onPop)

Pops the current indentation frame from the log stack and returns release metadata, running a callback before any buffered log lines are printed.

This is useful for logging a summary header (e.g., duration) before emitting the buffered body.

If the current frame is being held, calling this method will also release the buffered logs.

If there is no current frame/held output, this returns an empty release data (empty list, elapsed time = 0).

Parameters:

onPop - non-null callback invoked with the release data prior to printing buffered logs

Returns:

non-null release data for the popped frame

Throws:

java.lang.NullPointerException - if onPop is null

java.lang.IllegalStateException - if the Elevators service is not registered

popLog

@NotNull
public static @NotNull ILogReleaseData popLog()

Pops the current indentation frame from the log stack and returns release metadata.

If the current frame is being held (see holdLog()), calling this method will also release the buffered logs as part of the pop operation.

The returned ILogReleaseData contains the buffered log lines for the popped frame (if any) and the elapsed time in milliseconds between the corresponding push and this pop.

If there is no current frame/held output, this returns an empty release data (empty list, elapsed time = 0).

Returns:

non-null release data for the popped frame

Throws:

java.lang.IllegalStateException - if the Elevators service is not registered

holdLog

public static void holdLog()

Starts buffering subsequent log output instead of printing immediately.

Buffered output is printed when releaseLog() is called (and will respect the current indentation).

Throws:

java.lang.IllegalStateException - if the Elevators service is not registered

pushAndHoldLog

public static void pushAndHoldLog()

Convenience method equivalent to calling pushLog() and then holdLog(). Subsequent logs are both indented and buffered until released or popped.

Throws:

java.lang.IllegalStateException - if the Elevators service is not registered

releaseLog

@NotNull
public static @NotNull ILogReleaseData releaseLog(@NotNull
                                                  @NotNull java.util.function.Consumer<@NotNull ILogReleaseData> onRelease)

Releases buffered logs, running a callback before printing, and returns release metadata.

This overload is useful for printing a header line (e.g., "completed in Xms") before the buffered body.

If there is no current frame/held output, this returns an empty release data (empty list, elapsed time = 0).

Parameters:

onRelease - non-null callback invoked with the release data prior to printing buffered logs

Returns:

non-null release data containing buffered logs and elapsed time

Throws:

java.lang.NullPointerException - if onRelease is null

java.lang.IllegalStateException - if the Elevators service is not registered

releaseLog

@NotNull
public static @NotNull ILogReleaseData releaseLog()

Releases buffered logs, printing them to the console, and returns release metadata.

The returned ILogReleaseData contains the buffered log lines and the elapsed time in milliseconds since the corresponding push/hold context began.

If there is no current frame/held output, this returns an empty release data (empty list, elapsed time = 0).

Returns:

non-null release data containing buffered logs and elapsed time

Throws:

java.lang.IllegalStateException - if the Elevators service is not registered

getLogger

@NotNull
public static @NotNull java.util.logging.Logger getLogger()

Returns the underlying Logger used by the Elevators logging system.

Returns:

the non-null logger instance

Throws:

java.lang.IllegalStateException - if the Elevators service is not registered