Replace ItemTag API with new API that also expands to Tiles and Entities

By: Bjarne Koll <LynxPlay101@gmail.com>

paper-api/src/main/java/org/bukkit/block/Banner.java

@@ -8,7 +8,7 @@ import org.jetbrains.annotations.NotNull;
 /**
  * Represents a captured state of a banner.
  */
-public interface Banner extends BlockState {
+public interface Banner extends TileState {
 
     /**
      * Returns the base color for this banner

paper-api/src/main/java/org/bukkit/block/Beacon.java

@@ -11,7 +11,7 @@ import org.jetbrains.annotations.Nullable;
 /**
  * Represents a captured state of a beacon.
  */
-public interface Beacon extends BlockState, Lockable, Nameable {
+public interface Beacon extends TileState, Lockable, Nameable {
 
     /**
      * Returns the list of players within the beacon's range of effect.

paper-api/src/main/java/org/bukkit/block/Bed.java

@@ -7,4 +7,4 @@ import org.bukkit.material.Colorable;
  * @deprecated does not provide useful information beyond the material itself
  */
 @Deprecated
-public interface Bed extends BlockState, Colorable { }
+public interface Bed extends TileState, Colorable { }

paper-api/src/main/java/org/bukkit/block/Bell.java

@@ -3,4 +3,4 @@ package org.bukkit.block;
 /**
  * Represents a captured state of Bell.
  */
-public interface Bell extends BlockState { }
+public interface Bell extends TileState { }

paper-api/src/main/java/org/bukkit/block/Campfire.java

@@ -7,7 +7,7 @@ import org.jetbrains.annotations.Nullable;
 /**
  * Represents a captured state of a campfire.
  */
-public interface Campfire extends BlockState {
+public interface Campfire extends TileState {
 
     /**
      * @see Inventory#getSize()

paper-api/src/main/java/org/bukkit/block/CommandBlock.java

@@ -6,7 +6,7 @@ import org.jetbrains.annotations.Nullable;
 /**
  * Represents a captured state of a command block.
  */
-public interface CommandBlock extends BlockState {
+public interface CommandBlock extends TileState {
 
     /**
      * Gets the command that this CommandBlock will run when powered.

paper-api/src/main/java/org/bukkit/block/Comparator.java

@@ -3,4 +3,4 @@ package org.bukkit.block;
 /**
  * Represents a captured state of an on / off comparator.
  */
-public interface Comparator extends BlockState { }
+public interface Comparator extends TileState { }

paper-api/src/main/java/org/bukkit/block/Conduit.java

@@ -3,4 +3,4 @@ package org.bukkit.block;
 /**
  * Represents a captured state of a conduit.
  */
-public interface Conduit extends BlockState { }
+public interface Conduit extends TileState { }

paper-api/src/main/java/org/bukkit/block/Container.java

@@ -8,7 +8,7 @@ import org.jetbrains.annotations.NotNull;
 /**
  * Represents a captured state of a container block.
  */
-public interface Container extends BlockState, BlockInventoryHolder, Lockable, Nameable {
+public interface Container extends TileState, BlockInventoryHolder, Lockable, Nameable {
 
     /**
      * Gets the inventory of the block represented by this block state.

paper-api/src/main/java/org/bukkit/block/CreatureSpawner.java

@@ -6,7 +6,7 @@ import org.jetbrains.annotations.NotNull;
 /**
  * Represents a captured state of a creature spawner.
  */
-public interface CreatureSpawner extends BlockState {
+public interface CreatureSpawner extends TileState {
 
     /**
      * Get the spawner's creature type.

paper-api/src/main/java/org/bukkit/block/DaylightDetector.java

@@ -3,4 +3,4 @@ package org.bukkit.block;
 /**
  * Represents a captured state of a (possibly inverted) daylight detector.
  */
-public interface DaylightDetector extends BlockState { }
+public interface DaylightDetector extends TileState { }

paper-api/src/main/java/org/bukkit/block/EnchantingTable.java

@@ -5,4 +5,4 @@ import org.bukkit.Nameable;
 /**
  * Represents a captured state of an enchanting table.
  */
-public interface EnchantingTable extends BlockState, Nameable { }
+public interface EnchantingTable extends TileState, Nameable { }

paper-api/src/main/java/org/bukkit/block/EndGateway.java

@@ -6,7 +6,7 @@ import org.jetbrains.annotations.Nullable;
 /**
  * Represents a captured state of an end gateway.
  */
-public interface EndGateway extends BlockState {
+public interface EndGateway extends TileState {
 
     /**
      * Gets the location that entities are teleported to when

paper-api/src/main/java/org/bukkit/block/EnderChest.java

@@ -3,4 +3,4 @@ package org.bukkit.block;
 /**
  * Represents a captured state of an ender chest.
  */
-public interface EnderChest extends BlockState { }
+public interface EnderChest extends TileState { }

paper-api/src/main/java/org/bukkit/block/Jigsaw.java

@@ -3,4 +3,4 @@ package org.bukkit.block;
 /**
  * Represents a captured state of a jigsaw.
  */
-public interface Jigsaw extends BlockState { }
+public interface Jigsaw extends TileState { }

paper-api/src/main/java/org/bukkit/block/Jukebox.java

@@ -8,7 +8,7 @@ import org.jetbrains.annotations.Nullable;
 /**
  * Represents a captured state of a jukebox.
  */
-public interface Jukebox extends BlockState {
+public interface Jukebox extends TileState {
 
     /**
      * Gets the record inserted into the jukebox.

paper-api/src/main/java/org/bukkit/block/Lectern.java

@@ -7,7 +7,7 @@ import org.jetbrains.annotations.NotNull;
 /**
  * Represents a captured state of a lectern.
  */
-public interface Lectern extends BlockState, BlockInventoryHolder {
+public interface Lectern extends TileState, BlockInventoryHolder {
 
     /**
      * Get the current lectern page.

paper-api/src/main/java/org/bukkit/block/Sign.java

@@ -5,7 +5,7 @@ import org.jetbrains.annotations.NotNull;
 /**
  * Represents a captured state of either a SignPost or a WallSign.
  */
-public interface Sign extends BlockState {
+public interface Sign extends TileState {
 
     /**
      * Gets all the lines of text currently on this sign.

paper-api/src/main/java/org/bukkit/block/Skull.java

@@ -11,7 +11,7 @@ import org.jetbrains.annotations.Nullable;
 /**
  * Represents a captured state of a skull block.
  */
-public interface Skull extends BlockState {
+public interface Skull extends TileState {
 
     /**
      * Checks to see if the skull has an owner

paper-api/src/main/java/org/bukkit/block/Structure.java

@@ -11,7 +11,7 @@ import org.jetbrains.annotations.NotNull;
  * Represents a structure block that can save and load blocks from a file. They
  * can only be used by OPs, and are not obtainable in survival.
  */
-public interface Structure extends BlockState {
+public interface Structure extends TileState {
 
     /**
      * The name of this structure.

paper-api/src/main/java/org/bukkit/block/TileState.java

@@ -0,0 +1,39 @@
+package org.bukkit.block;
+
+import org.bukkit.persistence.PersistentDataContainer;
+import org.bukkit.persistence.PersistentDataHolder;
+import org.jetbrains.annotations.NotNull;
+
+/**
+ * Represents a block state that also hosts a tile entity at the given location.
+ *
+ * This interface alone is merely a marker that does not provide any data.
+ *
+ * Data about the tile entities is provided by the respective interface for each
+ * tile entity type.
+ *
+ * After modifying the data provided by a TileState, {@link #update()} needs to
+ * be called to store the data.
+ */
+public interface TileState extends BlockState, PersistentDataHolder {
+
+    /**
+     * Returns a custom tag container capable of storing tags on the object.
+     *
+     * Note that the tags stored on this container are all stored under their
+     * own custom namespace therefore modifying default tags using this
+     * {@link PersistentDataHolder} is impossible.
+     * <p>
+     * This {@link PersistentDataHolder} is only linked to the snapshot instance
+     * stored by the {@link BlockState}.
+     *
+     * When storing changes on the {@link PersistentDataHolder}, the updated
+     * content will only be applied to the actual tile entity after one of the
+     * {@link #update()} methods is called.
+     *
+     * @return the custom tag container
+     */
+    @NotNull
+    @Override
+    PersistentDataContainer getPersistentDataContainer();
+}

paper-api/src/main/java/org/bukkit/entity/Entity.java

@@ -15,6 +15,7 @@ import org.bukkit.event.entity.EntityDamageEvent;
 import org.bukkit.event.player.PlayerTeleportEvent.TeleportCause;
 import org.bukkit.material.Directional;
 import org.bukkit.metadata.Metadatable;
+import org.bukkit.persistence.PersistentDataHolder;
 import org.bukkit.util.BoundingBox;
 import org.bukkit.util.Vector;
 import org.jetbrains.annotations.Contract;
@@ -24,7 +25,7 @@ import org.jetbrains.annotations.Nullable;
 /**
  * Represents a base entity in the world
  */
-public interface Entity extends Metadatable, CommandSender, Nameable {
+public interface Entity extends Metadatable, CommandSender, Nameable, PersistentDataHolder {
 
     /**
      * Gets the entity's current position

paper-api/src/main/java/org/bukkit/inventory/meta/ItemMeta.java

@@ -12,6 +12,7 @@ import org.bukkit.enchantments.Enchantment;
 import org.bukkit.inventory.EquipmentSlot;
 import org.bukkit.inventory.ItemFlag;
 import org.bukkit.inventory.meta.tags.CustomItemTagContainer;
+import org.bukkit.persistence.PersistentDataHolder;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 
@@ -21,7 +22,7 @@ import org.jetbrains.annotations.Nullable;
  * An implementation will handle the creation and application for ItemMeta.
  * This class should not be implemented by a plugin in a live environment.
  */
-public interface ItemMeta extends Cloneable, ConfigurationSerializable {
+public interface ItemMeta extends Cloneable, ConfigurationSerializable, PersistentDataHolder {
 
     /**
      * Checks for existence of a display name.
@@ -368,8 +369,11 @@ public interface ItemMeta extends Cloneable, ConfigurationSerializable {
      * These tags can also be modified by the client once in creative mode
      *
      * @return the custom tag container
+     * @deprecated this API part has been replaced by the {@link PersistentDataHolder} API.
+     * Please use {@link PersistentDataHolder#getPersistentDataContainer()} instead of this.
      */
     @NotNull
+    @Deprecated
     CustomItemTagContainer getCustomTagContainer();
 
     /**

paper-api/src/main/java/org/bukkit/inventory/meta/tags/CustomItemTagContainer.java

@@ -8,7 +8,12 @@ import org.jetbrains.annotations.Nullable;
 /**
  * This interface represents a map like object, capable of storing custom tags
  * in it.
+ *
+ * @deprecated this API part has been replaced by the
+ * {@link org.bukkit.persistence.PersistentDataHolder} API. Please use
+ * {@link org.bukkit.persistence.PersistentDataHolder} instead of this.
  */
+@Deprecated
 public interface CustomItemTagContainer {
 
     /**

paper-api/src/main/java/org/bukkit/inventory/meta/tags/ItemTagAdapterContext.java

@@ -1,11 +1,17 @@
 package org.bukkit.inventory.meta.tags;
 
+import org.bukkit.persistence.PersistentDataAdapterContext;
+import org.bukkit.persistence.PersistentDataHolder;
 import org.jetbrains.annotations.NotNull;
 
 /**
  * This interface represents the context in which the {@link ItemTagType} can
  * serialize and deserialize the passed values.
+ *
+ * @deprecated this API part has been replaced by {@link PersistentDataHolder}.
+ * Please use {@link PersistentDataAdapterContext} instead of this.
  */
+@Deprecated
 public interface ItemTagAdapterContext {
 
     /**

paper-api/src/main/java/org/bukkit/inventory/meta/tags/ItemTagType.java

@@ -1,5 +1,6 @@
 package org.bukkit.inventory.meta.tags;
 
+import org.bukkit.persistence.PersistentDataType;
 import org.jetbrains.annotations.NotNull;
 
 /**
@@ -42,7 +43,10 @@ import org.jetbrains.annotations.NotNull;
  *
  * @param <T> the primary object type that is stored in the given tag
  * @param <Z> the retrieved object type when applying this item tag type
+ *
+ * @deprecated please use {@link PersistentDataType} as this part of the api is being replaced
  */
+@Deprecated
 public interface ItemTagType<T, Z> {
 
     /*

paper-api/src/main/java/org/bukkit/persistence/PersistentDataAdapterContext.java

@@ -0,0 +1,18 @@
+package org.bukkit.persistence;
+
+import org.jetbrains.annotations.NotNull;
+
+/**
+ * This interface represents the context in which the {@link PersistentDataType} can
+ * serialize and deserialize the passed values.
+ */
+public interface PersistentDataAdapterContext {
+
+    /**
+     * Creates a new and empty meta container instance.
+     *
+     * @return the fresh container instance
+     */
+    @NotNull
+    PersistentDataContainer newPersistentDataContainer();
+}

paper-api/src/main/java/org/bukkit/persistence/PersistentDataContainer.java

@@ -0,0 +1,141 @@
+package org.bukkit.persistence;
+
+import org.bukkit.NamespacedKey;
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
+
+/**
+ * This interface represents a map like object, capable of storing custom tags
+ * in it.
+ */
+public interface PersistentDataContainer {
+
+    /**
+     * Stores a metadata value on the {@link PersistentDataHolder} instance.
+     * <p>
+     * This API cannot be used to manipulate minecraft data, as the values will
+     * be stored using your namespace. This method will override any existing
+     * value the {@link PersistentDataHolder} may have stored under the provided
+     * key.
+     *
+     * @param key the key this value will be stored under
+     * @param type the type this tag uses
+     * @param value the value stored in the tag
+     * @param <T> the generic java type of the tag value
+     * @param <Z> the generic type of the object to store
+     *
+     * @throws NullPointerException if the key is null
+     * @throws NullPointerException if the type is null
+     * @throws NullPointerException if the value is null. Removing a tag should
+     * be done using {@link #remove(NamespacedKey)}
+     * @throws IllegalArgumentException if no suitable adapter will be found for
+     * the {@link PersistentDataType#getPrimitiveType()}
+     */
+    <T, Z> void set(@NotNull NamespacedKey key, @NotNull PersistentDataType<T, Z> type, @NotNull Z value);
+
+    /**
+     * Returns if the persistent metadata provider has metadata registered
+     * matching the provided parameters.
+     * <p>
+     * This method will only return if the found value has the same primitive
+     * data type as the provided key.
+     * <p>
+     * Storing a value using a custom {@link PersistentDataType} implementation
+     * will not store the complex data type. Therefore storing a UUID (by
+     * storing a byte[]) will match has("key" ,
+     * {@link PersistentDataType#BYTE_ARRAY}). Likewise a stored byte[] will
+     * always match your UUID {@link PersistentDataType} even if it is not 16
+     * bytes long.
+     * <p>
+     * This method is only usable for custom object keys. Overwriting existing
+     * tags, like the the display name, will not work as the values are stored
+     * using your namespace.
+     *
+     * @param key the key the value is stored under
+     * @param type the type which primitive storage type has to match the value
+     * @param <T> the generic type of the stored primitive
+     * @param <Z> the generic type of the eventually created complex object
+     *
+     * @return if a value
+     *
+     * @throws NullPointerException if the key to look up is null
+     * @throws NullPointerException if the type to cast the found object to is
+     * null
+     */
+    <T, Z> boolean has(@NotNull NamespacedKey key, @NotNull PersistentDataType<T, Z> type);
+
+    /**
+     * Returns the metadata value that is stored on the
+     * {@link PersistentDataHolder} instance.
+     *
+     * @param key the key to look up in the custom tag map
+     * @param type the type the value must have and will be casted to
+     * @param <T> the generic type of the stored primitive
+     * @param <Z> the generic type of the eventually created complex object
+     *
+     * @return the value or {@code null} if no value was mapped under the given
+     * value
+     *
+     * @throws NullPointerException if the key to look up is null
+     * @throws NullPointerException if the type to cast the found object to is
+     * null
+     * @throws IllegalArgumentException if the value exists under the given key,
+     * but cannot be access using the given type
+     * @throws IllegalArgumentException if no suitable adapter will be found for
+     * the {@link
+     * PersistentDataType#getPrimitiveType()}
+     */
+    @Nullable
+    <T, Z> Z get(@NotNull NamespacedKey key, @NotNull PersistentDataType<T, Z> type);
+
+    /**
+     * Returns the metadata value that is stored on the
+     * {@link PersistentDataHolder} instance. If the value does not exist in the
+     * container, the default value provided is returned.
+     *
+     * @param key the key to look up in the custom tag map
+     * @param type the type the value must have and will be casted to
+     * @param defaultValue the default value to return if no value was found for
+     * the provided key
+     * @param <T> the generic type of the stored primitive
+     * @param <Z> the generic type of the eventually created complex object
+     *
+     * @return the value or the default value if no value was mapped under the
+     * given value
+     *
+     * @throws NullPointerException if the key to look up is null
+     * @throws NullPointerException if the type to cast the found object to is
+     * null
+     * @throws IllegalArgumentException if the value exists under the given key,
+     * but cannot be access using the given type
+     * @throws IllegalArgumentException if no suitable adapter will be found for
+     * the {@link PersistentDataType#getPrimitiveType()}
+     */
+    @NotNull
+    <T, Z> Z getOrDefault(@NotNull NamespacedKey key, @NotNull PersistentDataType<T, Z> type, @NotNull Z defaultValue);
+
+    /**
+     * Removes a custom key from the {@link PersistentDataHolder} instance.
+     *
+     * @param key the key
+     *
+     * @throws NullPointerException if the provided key is null
+     */
+    void remove(@NotNull NamespacedKey key);
+
+    /**
+     * Returns if the container instance is empty, therefore has no entries
+     * inside it.
+     *
+     * @return the boolean
+     */
+    boolean isEmpty();
+
+    /**
+     * Returns the adapter context this tag container uses.
+     *
+     * @return the tag context
+     */
+    @NotNull
+    PersistentDataAdapterContext getAdapterContext();
+}

paper-api/src/main/java/org/bukkit/persistence/PersistentDataHolder.java

@@ -0,0 +1,23 @@
+package org.bukkit.persistence;
+
+import org.jetbrains.annotations.NotNull;
+
+/**
+ * The {@link PersistentDataHolder} interface defines an object that can store
+ * custom persistent meta data on it.
+ */
+public interface PersistentDataHolder {
+
+    /**
+     * Returns a custom tag container capable of storing tags on the object.
+     *
+     * Note that the tags stored on this container are all stored under their
+     * own custom namespace therefore modifying default tags using this
+     * {@link PersistentDataHolder} is impossible.
+     *
+     * @return the persistent metadata container
+     */
+    @NotNull
+    PersistentDataContainer getPersistentDataContainer();
+
+}

paper-api/src/main/java/org/bukkit/persistence/PersistentDataType.java

@@ -0,0 +1,153 @@
+package org.bukkit.persistence;
+
+import org.jetbrains.annotations.NotNull;
+
+/**
+ * This class represents an enum with a generic content type. It defines the
+ * types a custom tag can have.
+ * <p>
+ * This interface can be used to create your own custom
+ * {@link PersistentDataType} with different complex types. This may be useful
+ * for the likes of a UUIDTagType:
+ * <pre>
+ * <code>{@code
+ * public class UUIDTagType implements PersistentDataType<byte[], UUID> {
+ *
+ *         {@literal @Override}
+ *         public Class<byte[]> getPrimitiveType() {
+ *             return byte[].class;
+ *         }
+ *
+ *         {@literal @Override}
+ *         public Class<UUID> getComplexType() {
+ *             return UUID.class;
+ *         }
+ *
+ *         {@literal @Override}
+ *         public byte[] toPrimitive(UUID complex, PersistentDataAdapterContext context) {
+ *             ByteBuffer bb = ByteBuffer.wrap(new byte[16]);
+ *             bb.putLong(complex.getMostSignificantBits());
+ *             bb.putLong(complex.getLeastSignificantBits());
+ *             return bb.array();
+ *         }
+ *
+ *         {@literal @Override}
+ *         public UUID fromPrimitive(byte[] primitive, PersistentDataAdapterContext context) {
+ *             ByteBuffer bb = ByteBuffer.wrap(primitive);
+ *             long firstLong = bb.getLong();
+ *             long secondLong = bb.getLong();
+ *             return new UUID(firstLong, secondLong);
+ *         }
+ *     }}</code></pre>
+ *
+ * @param <T> the primary object type that is stored in the given tag
+ * @param <Z> the retrieved object type when applying this tag type
+ */
+public interface PersistentDataType<T, Z> {
+
+    /*
+        The primitive one value types.
+     */
+    PersistentDataType<Byte, Byte> BYTE = new PrimitivePersistentDataType<>(Byte.class);
+    PersistentDataType<Short, Short> SHORT = new PrimitivePersistentDataType<>(Short.class);
+    PersistentDataType<Integer, Integer> INTEGER = new PrimitivePersistentDataType<>(Integer.class);
+    PersistentDataType<Long, Long> LONG = new PrimitivePersistentDataType<>(Long.class);
+    PersistentDataType<Float, Float> FLOAT = new PrimitivePersistentDataType<>(Float.class);
+    PersistentDataType<Double, Double> DOUBLE = new PrimitivePersistentDataType<>(Double.class);
+
+    /*
+        String.
+     */
+    PersistentDataType<String, String> STRING = new PrimitivePersistentDataType<>(String.class);
+
+    /*
+        Primitive Arrays.
+     */
+    PersistentDataType<byte[], byte[]> BYTE_ARRAY = new PrimitivePersistentDataType<>(byte[].class);
+    PersistentDataType<int[], int[]> INTEGER_ARRAY = new PrimitivePersistentDataType<>(int[].class);
+    PersistentDataType<long[], long[]> LONG_ARRAY = new PrimitivePersistentDataType<>(long[].class);
+
+    /*
+        Nested PersistentDataContainer.
+     */
+    PersistentDataType<PersistentDataContainer, PersistentDataContainer> TAG_CONTAINER = new PrimitivePersistentDataType<>(PersistentDataContainer.class);
+
+    /**
+     * Returns the primitive data type of this tag.
+     *
+     * @return the class
+     */
+    @NotNull
+    Class<T> getPrimitiveType();
+
+    /**
+     * Returns the complex object type the primitive value resembles.
+     *
+     * @return the class type
+     */
+    @NotNull
+    Class<Z> getComplexType();
+
+    /**
+     * Returns the primitive data that resembles the complex object passed to
+     * this method.
+     *
+     * @param complex the complex object instance
+     * @param context the context this operation is running in
+     * @return the primitive value
+     */
+    @NotNull
+    T toPrimitive(@NotNull Z complex, @NotNull PersistentDataAdapterContext context);
+
+    /**
+     * Creates a complex object based of the passed primitive value
+     *
+     * @param primitive the primitive value
+     * @param context the context this operation is running in
+     * @return the complex object instance
+     */
+    @NotNull
+    Z fromPrimitive(@NotNull T primitive, @NotNull PersistentDataAdapterContext context);
+
+    /**
+     * A default implementation that simply exists to pass on the retrieved or
+     * inserted value to the next layer.
+     * <p>
+     * This implementation does not add any kind of logic, but is used to
+     * provide default implementations for the primitive types.
+     *
+     * @param <T> the generic type of the primitive objects
+     */
+    class PrimitivePersistentDataType<T> implements PersistentDataType<T, T> {
+
+        private final Class<T> primitiveType;
+
+        PrimitivePersistentDataType(@NotNull Class<T> primitiveType) {
+            this.primitiveType = primitiveType;
+        }
+
+        @NotNull
+        @Override
+        public Class<T> getPrimitiveType() {
+            return primitiveType;
+        }
+
+        @NotNull
+        @Override
+        public Class<T> getComplexType() {
+            return primitiveType;
+        }
+
+        @NotNull
+        @Override
+        public T toPrimitive(@NotNull T complex, @NotNull PersistentDataAdapterContext context) {
+            return complex;
+        }
+
+        @NotNull
+        @Override
+        public T fromPrimitive(@NotNull T primitive, @NotNull PersistentDataAdapterContext context) {
+            return primitive;
+        }
+    }
+}