Add methods to facilitate conversion from IDs to new Materials

Essentials/src/com/earth2me/essentials/api/IItemDb.java

@@ -1,33 +1,156 @@
 package com.earth2me.essentials.api;
 
+import com.earth2me.essentials.CommandSource;
 import com.earth2me.essentials.User;
+import com.earth2me.essentials.utils.MaterialUtil;
+import com.earth2me.essentials.utils.NumberUtil;
+import com.earth2me.essentials.utils.StringUtil;
+import net.ess3.api.IEssentials;
 import org.bukkit.Material;
 import org.bukkit.inventory.ItemStack;
 
 import java.util.Collection;
 import java.util.List;
+import java.util.Locale;
 
 
 public interface IItemDb {
-    ItemStack get(final String name, final int quantity) throws Exception;
 
+    /**
+     * Create a stack from the given name with the given quantity.
+     *
+     * @param name Item name to look up in the database
+     * @param quantity Quantity of the item stack
+     * @return The requested item stack
+     * @throws Exception if the item stack cannot be created
+     */
+    default ItemStack get(final String name, final int quantity) throws Exception {
+        final ItemStack stack = get(name.toLowerCase(Locale.ENGLISH));
+        stack.setAmount(quantity);
+        return stack;
+    }
+
+    /**
+     * Create a stack from the given name with the maximum stack size for that material.
+     *
+     * @param name Item name to look up in the database
+     * @return The requested item stack with the maximum stack size
+     * @throws Exception if the item stack cannot be created
+     */
     ItemStack get(final String name) throws Exception;
 
-    String names(ItemStack item);
+    /**
+     * Get a comma-separated string list of up to 15 aliases for the given stack.
+     *
+     * @param item Item stack whose names to find
+     * @return Comma-separated list of up to 15 item names
+     */
+    default String names(ItemStack item) {
+        List<String> nameList = nameList(item);
 
+        if (nameList.size() > 15) {
+            nameList = nameList.subList(0, 14);
+        }
+        return StringUtil.joinList(", ", nameList);
+    };
+
+    /**
+     * Get a List of all aliases for the given item stack.
+     *
+     * @param item Item stack whose names to find
+     * @return List of all names
+     */
     List<String> nameList(ItemStack item);
 
+    /**
+     * Get the primary name for the given item stack.
+     *
+     * @param item Item stack whose name to find
+     * @return Primary name of the item
+     */
     String name(ItemStack item);
 
+    /**
+     * Get all stacks in a given User's inventory that matches the given arguments.
+     *
+     * @param user The user with the player inventory to search
+     * @param args Either an item name, or one of the following:
+     *             hand (default), inventory/invent/all, blocks
+     * @return A List of all matching ItemStacks
+     * @throws Exception if the given args are invalid or no blocks are found
+     */
     List<ItemStack> getMatching(User user, String[] args) throws Exception;
 
+    /**
+     * Serialise an ItemStack into a format that can be decoded by
+     * {@link #get(String) get} and
+     * {@link com.earth2me.essentials.MetaItemStack#parseStringMeta(CommandSource, boolean, String[], int, IEssentials)} MetaItemStack#parseStringMeta}.
+     * Useful for encoding items for usage in kits.
+     *
+     * @param is Stack to serialise
+     * @return Serialised stack
+     */
     String serialize(ItemStack is);
 
+    /**
+     * Return names recognised by the database, intended for tab-completion.
+     *
+     * @return Collection of all item names
+     */
     Collection<String> listNames();
 
+    /**
+     * Get the material matching the given legacy ID. Used for conversion from item IDs to
+     * modern names.
+     *
+     * @param id Legacy ID of material to find
+     * @return Updated material
+     */
     @Deprecated
-    Material getFromLegacyId(int id);
+    default Material getFromLegacyId(int id) {
+        return getFromLegacy(id, (byte) 0);
+    }
 
+    /**
+     * Get the legacy ID for the given material.
+     *
+     * @param material Material to look up
+     * @return Legacy ID of given material
+     * @throws Exception if the ID cannot be looked up
+     * @deprecated Item IDs are no longer supported.
+     */
     @Deprecated
     int getLegacyId(Material material) throws Exception;
+
+    /**
+     * Convert colon syntax (eg. "13", "1:5") legacy IDs to Material. Used for conversion from
+     * item IDs to modern names.
+     *
+     * @param item Legacy ID in colon syntax.
+     * @return
+     */
+    default Material getFromLegacy(String item) {
+        final String[] split = item.split(":");
+
+        final int id = Integer.parseInt(split[0]);
+        byte damage = 0;
+
+        if (split.length > 1 && NumberUtil.isInt(split[1])) {
+            damage = Byte.parseByte(split[1]);
+        }
+
+        return getFromLegacy(id, damage);
+    }
+
+    /**
+     * Convert legacy ID and damage value to Material. Used for conversion from item IDs to
+     * modern names.
+     *
+     * @param id Legacy ID
+     * @param damage Damage value
+     * @return Material
+     */
+    default Material getFromLegacy(final int id, final byte damage) {
+        return MaterialUtil.convertFromLegacy(id, damage);
+    }
 }

Essentials/src/com/earth2me/essentials/items/AbstractItemDb.java

@@ -3,6 +3,7 @@ package com.earth2me.essentials.items;
 import com.earth2me.essentials.IConf;
 import com.earth2me.essentials.User;
 import com.earth2me.essentials.utils.StringUtil;
+import com.earth2me.essentials.utils.VersionUtil;
 import org.bukkit.Color;
 import org.bukkit.FireworkEffect;
 import org.bukkit.Material;
@@ -23,13 +24,6 @@ import static com.earth2me.essentials.I18n.tl;
 
 public abstract class AbstractItemDb implements IConf, net.ess3.api.IItemDb {
 
-    @Override
-    public ItemStack get(final String id, final int quantity) throws Exception {
-        final ItemStack retval = get(id.toLowerCase(Locale.ENGLISH));
-        retval.setAmount(quantity);
-        return retval;
-    }
-
     @Override
     public List<ItemStack> getMatching(User user, String[] args) throws Exception {
         List<ItemStack> is = new ArrayList<>();
@@ -63,20 +57,10 @@ public abstract class AbstractItemDb implements IConf, net.ess3.api.IItemDb {
         return is;
     }
 
-    @Override
-    public String names(ItemStack item) {
-        List<String> nameList = nameList(item);
-
-        if (nameList.size() > 15) {
-            nameList = nameList.subList(0, 14);
-        }
-        return StringUtil.joinList(", ", nameList);
-    }
-
     @Override
     public String serialize(ItemStack is) {
         String mat = is.getType().name();
-        if (is.getData().getData() != 0) {
+        if (VersionUtil.getServerBukkitVersion().isLowerThanOrEqualTo(VersionUtil.v1_12_2_R01) && is.getData().getData() != 0) {
             mat = mat + ":" + is.getData().getData();
         }
         int quantity = is.getAmount();

Essentials/src/com/earth2me/essentials/items/FlatItemDb.java

@@ -1,6 +1,7 @@
 package com.earth2me.essentials.items;
 
 import com.earth2me.essentials.ManagedFile;
+import com.earth2me.essentials.utils.MaterialUtil;
 import com.google.gson.Gson;
 import com.google.gson.JsonElement;
 import com.google.gson.JsonObject;
@@ -177,16 +178,10 @@ public class FlatItemDb extends AbstractItemDb {
         return null;
     }
 
-    @Override
-    @Deprecated
-    public Material getFromLegacyId(int id) {
-        throw new UnsupportedOperationException("Legacy IDs aren't supported on this version of EssentialsX.");
-    }
-
     @Override
     @Deprecated
     public int getLegacyId(Material material) throws Exception {
-        throw new UnsupportedOperationException("Legacy IDs aren't supported on this version of EssentialsX.");
+        throw new UnsupportedOperationException("Legacy IDs aren't supported on this version.");
     }
 
     @Override

Essentials/src/com/earth2me/essentials/items/LegacyItemDb.java

@@ -226,7 +226,7 @@ public class LegacyItemDb extends AbstractItemDb {
     }
 
     @Override
-    public Material getFromLegacyId(int id) {
+    public Material getFromLegacy(int id, short damage) {
         ItemData data = this.legacyIds.get(id);
         if (data == null) {
             return null;

Essentials/src/com/earth2me/essentials/utils/MaterialUtil.java

@@ -1,7 +1,11 @@
 package com.earth2me.essentials.utils;
 
+import org.bukkit.Bukkit;
 import org.bukkit.Material;
+import org.bukkit.material.MaterialData;
 
+import java.util.EnumSet;
+import java.util.Optional;
 import java.util.Set;
 
 public class MaterialUtil {
@@ -97,4 +101,11 @@ public class MaterialUtil {
         return isPlayerHead(material, -1) || isMobHead(material, -1);
     }
 
+    public static Material convertFromLegacy(int id, byte damage) {
+        return EnumSet.allOf(Material.class).stream()
+            .filter(material -> material.getId() == id)
+            .findFirst()
+            .map(material -> Bukkit.getUnsafe().fromLegacy(new MaterialData(material, damage)))
+            .orElse(null);
+    }
 }