Package io.artificial.enchantments.api

Interface ItemStorage

All Known Implementing Classes:
NativeFirstItemStorage
public interface ItemStorage
Abstraction for storing and retrieving enchantment data on items.

Implementations must follow the native-first storage policy:

  • Native ItemMeta is the source of truth for enchantment state
  • NBT is used only for auxiliary metadata (display flags, compatibility markers)
  • No duplication of enchant state between native and NBT stores

This interface provides atomic operations for enchantment mutation to prevent state drift between the native ItemMeta and any auxiliary storage.

Since:
0.1.0
See Also:

  • Method Summary

    Modifier and Type
    Method
    Description
    @NotNull org.bukkit.inventory.ItemStack
    applyEnchantment(@NotNull org.bukkit.inventory.ItemStack item, @NotNull EnchantmentDefinition enchantment, int level)
    Applies an enchantment to an item at the specified level.
    @NotNull org.bukkit.inventory.ItemStack
    applyEnchantment(@NotNull org.bukkit.inventory.ItemStack item, @NotNull org.bukkit.NamespacedKey key, int level)
    Applies an enchantment by its registry key.
    @NotNull org.bukkit.inventory.ItemStack
    clearAuxiliaryMetadata(@NotNull org.bukkit.inventory.ItemStack item)
    Clears all auxiliary metadata from an item.
    @Nullable String
    getAuxiliaryMetadata(@NotNull org.bukkit.inventory.ItemStack item, @NotNull String key)
    Gets an auxiliary metadata string value.
    @NotNull Set<String>
    getAuxiliaryMetadataKeys(@NotNull org.bukkit.inventory.ItemStack item)
    Gets the names of all auxiliary metadata keys stored for this item.
    @NotNull Map<org.bukkit.NamespacedKey,Integer>
    getEnchantmentKeys(@NotNull org.bukkit.inventory.ItemStack item)
    Gets all artificial enchantment keys on an item as NamespacedKey to level mapping.
    int
    getEnchantmentLevel(@NotNull org.bukkit.inventory.ItemStack item, @NotNull EnchantmentDefinition enchantment)
    Gets the level of a specific enchantment on an item.
    int
    getEnchantmentLevel(@NotNull org.bukkit.inventory.ItemStack item, @NotNull org.bukkit.NamespacedKey key)
    Gets the level of an enchantment by its registry key.
    @NotNull Map<EnchantmentDefinition,Integer>
    getEnchantments(@NotNull org.bukkit.inventory.ItemStack item)
    Gets all artificial enchantments on an item.
    boolean
    hasAuxiliaryMetadata(@NotNull org.bukkit.inventory.ItemStack item, @NotNull String key)
    Checks if auxiliary metadata with the given key exists.
    boolean
    hasEnchantment(@NotNull org.bukkit.inventory.ItemStack item, @NotNull EnchantmentDefinition enchantment)
    Checks if an item has a specific enchantment.
    boolean
    hasEnchantment(@NotNull org.bukkit.inventory.ItemStack item, @NotNull org.bukkit.NamespacedKey key)
    Checks if an item has an enchantment by its registry key.
    @NotNull org.bukkit.inventory.ItemStack
    removeAllEnchantments(@NotNull org.bukkit.inventory.ItemStack item)
    Removes all artificial enchantments from an item.
    @NotNull org.bukkit.inventory.ItemStack
    removeEnchantment(@NotNull org.bukkit.inventory.ItemStack item, @NotNull EnchantmentDefinition enchantment)
    Removes an enchantment from an item.
    @NotNull org.bukkit.inventory.ItemStack
    removeEnchantment(@NotNull org.bukkit.inventory.ItemStack item, @NotNull org.bukkit.NamespacedKey key)
    Removes an enchantment by its registry key.
    @NotNull org.bukkit.inventory.ItemStack
    setAuxiliaryMetadata(@NotNull org.bukkit.inventory.ItemStack item, @NotNull String key, @Nullable String value)
    Sets an auxiliary metadata string value.

  • Method Details

    • applyEnchantment

      @NotNull @NotNull org.bukkit.inventory.ItemStack applyEnchantment(@NotNull @NotNull org.bukkit.inventory.ItemStack item, @NotNull @NotNull EnchantmentDefinition enchantment, int level)
      Applies an enchantment to an item at the specified level.

      The enchantment level is validated against the definition's bounds before application. If the level is outside the valid range, the operation fails.

      This operation is atomic - either the enchantment is fully applied with all auxiliary metadata updated, or the item remains unchanged.

      Parameters:
      item - the item to enchant (must not be null or air)
      enchantment - the enchantment definition to apply (must not be null)
      level - the level to apply (must be within enchantment's min/max bounds)
      Returns:
      the enchanted item (may be the same instance if item is mutable)
      Throws:
      IllegalArgumentException - if item is null, air, or level is invalid
      IllegalStateException - if the enchantment conflicts with existing ones and conflict resolution fails

    • applyEnchantment

      @NotNull @NotNull org.bukkit.inventory.ItemStack applyEnchantment(@NotNull @NotNull org.bukkit.inventory.ItemStack item, @NotNull @NotNull org.bukkit.NamespacedKey key, int level)
      Applies an enchantment by its registry key.

      This is a convenience method that looks up the definition in the registry before delegating to applyEnchantment(ItemStack, EnchantmentDefinition, int).

      Parameters:
      item - the item to enchant (must not be null or air)
      key - the enchantment's namespaced key (must not be null)
      level - the level to apply
      Returns:
      the enchanted item
      Throws:
      IllegalArgumentException - if the enchantment is not registered
      See Also:

    • removeEnchantment

      @NotNull @NotNull org.bukkit.inventory.ItemStack removeEnchantment(@NotNull @NotNull org.bukkit.inventory.ItemStack item, @NotNull @NotNull EnchantmentDefinition enchantment)
      Removes an enchantment from an item.

      If the item does not have the specified enchantment, this operation is a no-op and returns the item unchanged.

      Auxiliary metadata associated with this enchantment is also cleaned up.

      Parameters:
      item - the item to modify (must not be null)
      enchantment - the enchantment to remove (must not be null)
      Returns:
      the modified item (may be the same instance if item is mutable)
      Throws:
      IllegalArgumentException - if item or enchantment is null

    • removeEnchantment

      @NotNull @NotNull org.bukkit.inventory.ItemStack removeEnchantment(@NotNull @NotNull org.bukkit.inventory.ItemStack item, @NotNull @NotNull org.bukkit.NamespacedKey key)
      Removes an enchantment by its registry key.
      Parameters:
      item - the item to modify (must not be null)
      key - the enchantment's namespaced key (must not be null)
      Returns:
      the modified item
      Throws:
      IllegalArgumentException - if the enchantment is not registered
      See Also:

    • removeAllEnchantments

      @NotNull @NotNull org.bukkit.inventory.ItemStack removeAllEnchantments(@NotNull @NotNull org.bukkit.inventory.ItemStack item)
      Removes all artificial enchantments from an item.

      This removes all enchantments registered through this API while preserving vanilla enchantments and the item's base properties (durability, lore, etc).

      Parameters:
      item - the item to clear (must not be null)
      Returns:
      the modified item
      Throws:
      IllegalArgumentException - if item is null

    • getEnchantmentLevel

      int getEnchantmentLevel(@NotNull @NotNull org.bukkit.inventory.ItemStack item, @NotNull @NotNull EnchantmentDefinition enchantment)
      Gets the level of a specific enchantment on an item.
      Parameters:
      item - the item to query (must not be null)
      enchantment - the enchantment to check (must not be null)
      Returns:
      the enchantment level, or 0 if not present
      Throws:
      IllegalArgumentException - if item or enchantment is null

    • getEnchantmentLevel

      int getEnchantmentLevel(@NotNull @NotNull org.bukkit.inventory.ItemStack item, @NotNull @NotNull org.bukkit.NamespacedKey key)
      Gets the level of an enchantment by its registry key.
      Parameters:
      item - the item to query (must not be null)
      key - the enchantment's namespaced key (must not be null)
      Returns:
      the enchantment level, or 0 if not present or not registered
      Throws:
      IllegalArgumentException - if item or key is null

    • getEnchantments

      @NotNull @NotNull Map<EnchantmentDefinition,Integer> getEnchantments(@NotNull @NotNull org.bukkit.inventory.ItemStack item)
      Gets all artificial enchantments on an item.

      Returns a map of enchantment definitions to their levels. Only enchantments registered through this API are included; vanilla enchantments are excluded.

      The returned map is unmodifiable and represents a snapshot of the item's state at the time of the call.

      Parameters:
      item - the item to query (must not be null)
      Returns:
      an unmodifiable map of enchantments to levels (never null, may be empty)
      Throws:
      IllegalArgumentException - if item is null

    • getEnchantmentKeys

      @NotNull @NotNull Map<org.bukkit.NamespacedKey,Integer> getEnchantmentKeys(@NotNull @NotNull org.bukkit.inventory.ItemStack item)
      Gets all artificial enchantment keys on an item as NamespacedKey to level mapping.

      This is a lower-level alternative to getEnchantments(ItemStack) that returns raw keys rather than resolved definitions. Useful when definitions may not be available (e.g., cross-plugin compatibility).

      Parameters:
      item - the item to query (must not be null)
      Returns:
      an unmodifiable map of enchantment keys to levels
      Throws:
      IllegalArgumentException - if item is null

    • hasEnchantment

      boolean hasEnchantment(@NotNull @NotNull org.bukkit.inventory.ItemStack item, @NotNull @NotNull EnchantmentDefinition enchantment)
      Checks if an item has a specific enchantment.
      Parameters:
      item - the item to check (must not be null)
      enchantment - the enchantment to look for (must not be null)
      Returns:
      true if the item has the enchantment at any level
      Throws:
      IllegalArgumentException - if item or enchantment is null

    • hasEnchantment

      boolean hasEnchantment(@NotNull @NotNull org.bukkit.inventory.ItemStack item, @NotNull @NotNull org.bukkit.NamespacedKey key)
      Checks if an item has an enchantment by its registry key.
      Parameters:
      item - the item to check (must not be null)
      key - the enchantment's namespaced key (must not be null)
      Returns:
      true if the item has the enchantment at any level
      Throws:
      IllegalArgumentException - if item or key is null

    • getAuxiliaryMetadataKeys

      @NotNull @NotNull Set<String> getAuxiliaryMetadataKeys(@NotNull @NotNull org.bukkit.inventory.ItemStack item)
      Gets the names of all auxiliary metadata keys stored for this item.

      Auxiliary metadata is stored in NBT and used for compatibility markers, display flags, and other non-enchantment data.

      Parameters:
      item - the item to query (must not be null)
      Returns:
      a set of auxiliary metadata keys (never null, may be empty)
      Throws:
      IllegalArgumentException - if item is null

    • setAuxiliaryMetadata

      @NotNull @NotNull org.bukkit.inventory.ItemStack setAuxiliaryMetadata(@NotNull @NotNull org.bukkit.inventory.ItemStack item, @NotNull @NotNull String key, @Nullable @Nullable String value)
      Sets an auxiliary metadata string value.

      This stores data in NBT that is not part of the core enchantment state. Use this for compatibility markers, display configuration, etc.

      Parameters:
      item - the item to modify (must not be null)
      key - the metadata key (must not be null or empty)
      value - the value to store, or null to remove
      Returns:
      the modified item
      Throws:
      IllegalArgumentException - if item or key is null/invalid

    • getAuxiliaryMetadata

      @Nullable @Nullable String getAuxiliaryMetadata(@NotNull @NotNull org.bukkit.inventory.ItemStack item, @NotNull @NotNull String key)
      Gets an auxiliary metadata string value.
      Parameters:
      item - the item to query (must not be null)
      key - the metadata key (must not be null)
      Returns:
      the stored value, or null if not present
      Throws:
      IllegalArgumentException - if item or key is null

    • hasAuxiliaryMetadata

      boolean hasAuxiliaryMetadata(@NotNull @NotNull org.bukkit.inventory.ItemStack item, @NotNull @NotNull String key)
      Checks if auxiliary metadata with the given key exists.
      Parameters:
      item - the item to query (must not be null)
      key - the metadata key (must not be null)
      Returns:
      true if metadata exists for the key
      Throws:
      IllegalArgumentException - if item or key is null

    • clearAuxiliaryMetadata

      @NotNull @NotNull org.bukkit.inventory.ItemStack clearAuxiliaryMetadata(@NotNull @NotNull org.bukkit.inventory.ItemStack item)
      Clears all auxiliary metadata from an item.

      This does not affect native enchantment state, only the NBT auxiliary store.

      Parameters:
      item - the item to modify (must not be null)
      Returns:
      the modified item
      Throws:
      IllegalArgumentException - if item is null