Package me.keehl.elevators.api.models

Interface IElevatorAction

All Known Subinterfaces:

IBuilderElevatorAction

public interface IElevatorAction

Represents a configurable action attached to an IElevatorType.

An action has:

• a server-wide action key (getKey()),
• a backing elevator type (getElevatorType()),
• an icon used for UI/editor display (getIcon()),
• a set of typed variables (getVariableValue(IElevatorActionVariable)),
• optional editable settings (getSettings()), and
• execution hooks (execute(IElevatorEventData, Player)).

Lifecycle

• initialize(String) is called once per action instance to parse and apply its configuration string.
• After initialization, variables and settings are available and getIdentifier() must be non-null.

Mutability

• Implementations may be mutable during initialization and when edited via settings/variables.
• getSettings() should return a snapshot list; modifying it must not affect internal state.

Method Summary

Modifier and Type	Method	Description
void	execute(@NotNull IElevatorEventData eventData, @NotNull org.bukkit.entity.Player player)	Executes the action for the given event/player.
@NotNull IElevatorType	getElevatorType()	Returns the elevator type that owns/contains this action.
@NotNull org.bukkit.inventory.ItemStack	getIcon()	Returns the icon that represents this action in user interfaces/editors.
@NotNull java.util.UUID	getIdentifier()	Returns the unique identifier for this action instance.
@NotNull java.lang.String	getKey()	Returns the server-wide action key used to identify this action type.
@NotNull java.util.List<@NotNull IElevatorActionSetting<?>>	getSettings()	Returns the list of editor settings mapped for this action.
<T> T	getVariableValue(@NotNull IElevatorActionVariable<T> variable)	Returns the current value of the given variable using global/default resolution rules.
<T> T	getVariableValue(@NotNull IElevatorActionVariable<T> variable, @Nullable IElevator elevator)	Returns the current value of the given variable, optionally using elevator-specific overrides.
void	initialize(@NotNull java.lang.String value)	Initializes this action from its serialized configuration string.
void	initIdentifier()	Ensures this action has a unique identifier.
boolean	meetsConditions(@NotNull IElevatorEventData eventData, @NotNull org.bukkit.entity.Player player)	Returns whether this action should execute for the given event/player.
void	onStartEditing(@NotNull org.bukkit.entity.Player player, @NotNull ISimpleDisplay display, @Nullable IElevator elevator)	Called when a player begins editing this action.
void	onStopEditing(@NotNull org.bukkit.entity.Player player, @NotNull ISimpleDisplay display, @Nullable IElevator elevator)	Called when a player finishes editing this action.
@NotNull java.lang.String	serialize()	Serializes this action (including its current variables) into a configuration string.
<T> void	setGroupingObject(@NotNull IElevatorActionVariable<T> variable, T value)	Sets the value of a variable (also referred to as a grouping) for this action.
void	setIcon(@NotNull org.bukkit.inventory.ItemStack item)	Sets the icon that represents this action in user interfaces/editors.

Method Detail

setIcon

void setIcon(@NotNull
             @NotNull org.bukkit.inventory.ItemStack item)

Sets the icon that represents this action in user interfaces/editors.

Contract: item must be non-null.

Parameters:

item - non-null icon item

Throws:

java.lang.NullPointerException - if item is null

initialize

void initialize(@NotNull
                @NotNull java.lang.String value)

Initializes this action from its serialized configuration string.

Implementations typically support formats like: key: alias=value alias2=value2 ... as well as a default variable value when aliases are omitted.

Contract:

• value must be non-null.
• This should be called exactly once per action instance before execution/editing APIs are used.
• After initialization, getIdentifier() must be non-null.

Parameters:

value - non-null configuration string (may include the key: prefix)

Throws:

java.lang.NullPointerException - if value is null

getElevatorType

@NotNull
@NotNull IElevatorType getElevatorType()

Returns the elevator type that owns/contains this action.

Returns:

the non-null owning elevator type

getKey

@NotNull
@NotNull java.lang.String getKey()

Returns the server-wide action key used to identify this action type.

Returns:

the non-null action key

getIcon

@NotNull
@NotNull org.bukkit.inventory.ItemStack getIcon()

Returns the icon that represents this action in user interfaces/editors.

Returns:

the non-null icon

serialize

@NotNull
@NotNull java.lang.String serialize()

Serializes this action (including its current variables) into a configuration string.

Contract: Never returns null.

Returns:

a non-null serialized representation of this action

getVariableValue

@NotNull
<T> T getVariableValue(@NotNull
                       @NotNull IElevatorActionVariable<T> variable)

Returns the current value of the given variable using global/default resolution rules.

If the variable has not been explicitly set, implementations should return the variable's default value.

Type Parameters:

T - variable value type

Parameters:

variable - non-null variable descriptor

Returns:

the resolved value

Throws:

java.lang.NullPointerException - if variable is null

getVariableValue

@NotNull
<T> T getVariableValue(@NotNull
                       @NotNull IElevatorActionVariable<T> variable,
                       @Nullable
                       @Nullable IElevator elevator)

Returns the current value of the given variable, optionally using elevator-specific overrides.

If elevator is non-null and the variable is backed by a setting that supports per-elevator values, the returned value may differ per elevator instance.

If no value is set, implementations should return the variable's default value.

Type Parameters:

T - variable value type

Parameters:

variable - non-null variable descriptor

elevator - optional elevator context for per-elevator settings; may be null

Returns:

the resolved value

Throws:

java.lang.NullPointerException - if variable is null

setGroupingObject

<T> void setGroupingObject(@NotNull
                           @NotNull IElevatorActionVariable<T> variable,
                           @NotNull
                           T value)

Sets the value of a variable (also referred to as a grouping) for this action.

Contract:

• variable and value must be non-null.
• Passing a value equal to the variable's default may remove the explicit override.

Type Parameters:

T - variable value type

Parameters:

variable - non-null variable descriptor

value - new value for the variable

Throws:

java.lang.NullPointerException - if variable is null

getIdentifier

@NotNull
@NotNull java.util.UUID getIdentifier()

Returns the unique identifier for this action instance.

This identifier is used to distinguish multiple instances of the same action type.

Lifecycle: After initialize(String) completes, this must be non-null.

Returns:

the non-null identifier

getSettings

@NotNull
@NotNull java.util.List<@NotNull IElevatorActionSetting<?>> getSettings()

Returns the list of editor settings mapped for this action.

Mutability: The returned list must be a snapshot; modifying it must not affect internal state.

Returns:

a non-null list of settings (possibly empty)

initIdentifier

void initIdentifier()

Ensures this action has a unique identifier.

Implementations may generate and assign a new identifier if one is not present.

onStartEditing

void onStartEditing(@NotNull
                    @NotNull org.bukkit.entity.Player player,
                    @NotNull
                    @NotNull ISimpleDisplay display,
                    @Nullable
                    @Nullable IElevator elevator)

Called when a player begins editing this action.

Parameters:

player - non-null player editing the action

display - non-null display/controller for presenting UI

elevator - non-null elevator context being edited

onStopEditing

void onStopEditing(@NotNull
                   @NotNull org.bukkit.entity.Player player,
                   @NotNull
                   @NotNull ISimpleDisplay display,
                   @Nullable
                   @Nullable IElevator elevator)

Called when a player finishes editing this action.

Parameters:

player - non-null player editing the action

display - non-null display/controller for presenting UI

elevator - non-null elevator context being edited

meetsConditions

boolean meetsConditions(@NotNull
                        @NotNull IElevatorEventData eventData,
                        @NotNull
                        @NotNull org.bukkit.entity.Player player)

Returns whether this action should execute for the given event/player.

This is a pure predicate; it should not have side effects.

Parameters:

eventData - non-null event context

player - non-null player involved in the event

Returns:

true if the action should execute; otherwise false

execute

void execute(@NotNull
             @NotNull IElevatorEventData eventData,
             @NotNull
             @NotNull org.bukkit.entity.Player player)

Executes the action for the given event/player.

Implementations should assume meetsConditions(IElevatorEventData, Player) has already been checked unless documented otherwise.

Parameters:

eventData - non-null event context

player - non-null player involved in the event