Package io.artificial.enchantments.internal

Class NativeFirstItemStorage

java.lang.Object
io.artificial.enchantments.internal.NativeFirstItemStorage
All Implemented Interfaces:
ItemStorage
public class NativeFirstItemStorage extends Object implements ItemStorage
Native-first implementation of ItemStorage.

This implementation uses Bukkit's native ItemMeta as the sole source of truth for enchantment state. NBT is used only for auxiliary metadata through NbtMetadataStorage.

Key design principles:

  • All enchantment state lives in ItemMeta (via addEnchant/removeEnchant)
  • No duplication of enchant state in NBT
  • Atomic operations ensure complete success or no change
  • Level validation uses enchantment definition bounds
Since:
0.1.0

  • Constructor Summary

    Constructors
    Constructor
    Description
    NativeFirstItemStorage(@NotNull Supplier<EnchantmentRegistryManager> registrySupplier, @NotNull NbtMetadataStorage nbtStorage)
    Creates a new native-first item storage.

  • 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.

    Methods inherited from class java.lang.Object

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

  • Constructor Details

    • NativeFirstItemStorage

      public NativeFirstItemStorage(@NotNull @NotNull Supplier<EnchantmentRegistryManager> registrySupplier, @NotNull @NotNull NbtMetadataStorage nbtStorage)
      Creates a new native-first item storage.
      Parameters:
      registrySupplier - supplier for the enchantment registry manager
      nbtStorage - the NBT metadata storage for auxiliary data
      Since:
      0.1.0

  • Method Details

    • applyEnchantment

      @NotNull public @NotNull org.bukkit.inventory.ItemStack applyEnchantment(@NotNull @NotNull org.bukkit.inventory.ItemStack item, @NotNull @NotNull EnchantmentDefinition enchantment, int level)
      Description copied from interface: ItemStorage
      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.

      Specified by:
      applyEnchantment in interface ItemStorage
      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)

    • applyEnchantment

      @NotNull public @NotNull org.bukkit.inventory.ItemStack applyEnchantment(@NotNull @NotNull org.bukkit.inventory.ItemStack item, @NotNull @NotNull org.bukkit.NamespacedKey key, int level)
      Description copied from interface: ItemStorage
      Applies an enchantment by its registry key.

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

      Specified by:
      applyEnchantment in interface ItemStorage
      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
      See Also:

    • removeEnchantment

      @NotNull public @NotNull org.bukkit.inventory.ItemStack removeEnchantment(@NotNull @NotNull org.bukkit.inventory.ItemStack item, @NotNull @NotNull EnchantmentDefinition enchantment)
      Description copied from interface: ItemStorage
      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.

      Specified by:
      removeEnchantment in interface ItemStorage
      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)

    • removeEnchantment

      @NotNull public @NotNull org.bukkit.inventory.ItemStack removeEnchantment(@NotNull @NotNull org.bukkit.inventory.ItemStack item, @NotNull @NotNull org.bukkit.NamespacedKey key)
      Description copied from interface: ItemStorage
      Removes an enchantment by its registry key.
      Specified by:
      removeEnchantment in interface ItemStorage
      Parameters:
      item - the item to modify (must not be null)
      key - the enchantment's namespaced key (must not be null)
      Returns:
      the modified item
      See Also:

    • removeAllEnchantments

      @NotNull public @NotNull org.bukkit.inventory.ItemStack removeAllEnchantments(@NotNull @NotNull org.bukkit.inventory.ItemStack item)
      Description copied from interface: ItemStorage
      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).

      Specified by:
      removeAllEnchantments in interface ItemStorage
      Parameters:
      item - the item to clear (must not be null)
      Returns:
      the modified item

    • getEnchantmentLevel

      public int getEnchantmentLevel(@NotNull @NotNull org.bukkit.inventory.ItemStack item, @NotNull @NotNull EnchantmentDefinition enchantment)
      Description copied from interface: ItemStorage
      Gets the level of a specific enchantment on an item.
      Specified by:
      getEnchantmentLevel in interface ItemStorage
      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

    • getEnchantmentLevel

      public int getEnchantmentLevel(@NotNull @NotNull org.bukkit.inventory.ItemStack item, @NotNull @NotNull org.bukkit.NamespacedKey key)
      Description copied from interface: ItemStorage
      Gets the level of an enchantment by its registry key.
      Specified by:
      getEnchantmentLevel in interface ItemStorage
      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

    • getEnchantments

      @NotNull public @NotNull Map<EnchantmentDefinition,Integer> getEnchantments(@NotNull @NotNull org.bukkit.inventory.ItemStack item)
      Description copied from interface: ItemStorage
      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.

      Specified by:
      getEnchantments in interface ItemStorage
      Parameters:
      item - the item to query (must not be null)
      Returns:
      an unmodifiable map of enchantments to levels (never null, may be empty)

    • getEnchantmentKeys

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

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

      Specified by:
      getEnchantmentKeys in interface ItemStorage
      Parameters:
      item - the item to query (must not be null)
      Returns:
      an unmodifiable map of enchantment keys to levels

    • hasEnchantment

      public boolean hasEnchantment(@NotNull @NotNull org.bukkit.inventory.ItemStack item, @NotNull @NotNull EnchantmentDefinition enchantment)
      Description copied from interface: ItemStorage
      Checks if an item has a specific enchantment.
      Specified by:
      hasEnchantment in interface ItemStorage
      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

    • hasEnchantment

      public boolean hasEnchantment(@NotNull @NotNull org.bukkit.inventory.ItemStack item, @NotNull @NotNull org.bukkit.NamespacedKey key)
      Description copied from interface: ItemStorage
      Checks if an item has an enchantment by its registry key.
      Specified by:
      hasEnchantment in interface ItemStorage
      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

    • getAuxiliaryMetadataKeys

      @NotNull public @NotNull Set<String> getAuxiliaryMetadataKeys(@NotNull @NotNull org.bukkit.inventory.ItemStack item)
      Description copied from interface: ItemStorage
      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.

      Specified by:
      getAuxiliaryMetadataKeys in interface ItemStorage
      Parameters:
      item - the item to query (must not be null)
      Returns:
      a set of auxiliary metadata keys (never null, may be empty)

    • setAuxiliaryMetadata

      @NotNull public @NotNull org.bukkit.inventory.ItemStack setAuxiliaryMetadata(@NotNull @NotNull org.bukkit.inventory.ItemStack item, @NotNull @NotNull String key, @Nullable @Nullable String value)
      Description copied from interface: ItemStorage
      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.

      Specified by:
      setAuxiliaryMetadata in interface ItemStorage
      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

    • getAuxiliaryMetadata

      @Nullable public @Nullable String getAuxiliaryMetadata(@NotNull @NotNull org.bukkit.inventory.ItemStack item, @NotNull @NotNull String key)
      Description copied from interface: ItemStorage
      Gets an auxiliary metadata string value.
      Specified by:
      getAuxiliaryMetadata in interface ItemStorage
      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

    • hasAuxiliaryMetadata

      public boolean hasAuxiliaryMetadata(@NotNull @NotNull org.bukkit.inventory.ItemStack item, @NotNull @NotNull String key)
      Description copied from interface: ItemStorage
      Checks if auxiliary metadata with the given key exists.
      Specified by:
      hasAuxiliaryMetadata in interface ItemStorage
      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

    • clearAuxiliaryMetadata

      @NotNull public @NotNull org.bukkit.inventory.ItemStack clearAuxiliaryMetadata(@NotNull @NotNull org.bukkit.inventory.ItemStack item)
      Description copied from interface: ItemStorage
      Clears all auxiliary metadata from an item.

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

      Specified by:
      clearAuxiliaryMetadata in interface ItemStorage
      Parameters:
      item - the item to modify (must not be null)
      Returns:
      the modified item