#1088: Deprecate HumanEntity#open[Menu]; Add Server#createMerchant()

src/main/java/org/bukkit/Bukkit.java

@@ -40,6 +40,7 @@ import org.bukkit.inventory.InventoryHolder;
 import org.bukkit.inventory.ItemCraftResult;
 import org.bukkit.inventory.ItemFactory;
 import org.bukkit.inventory.ItemStack;
+import org.bukkit.inventory.MenuType;
 import org.bukkit.inventory.Merchant;
 import org.bukkit.inventory.Recipe;
 import org.bukkit.inventory.meta.ItemMeta;
@@ -1561,12 +1562,25 @@ public final class Bukkit {
      * @param title the title of the corresponding merchant inventory, displayed
      * when the merchant inventory is viewed
      * @return a new merchant
+     * @deprecated The title parameter is no-longer needed when used with
+     * {@link MenuType#MERCHANT} and {@link MenuType.Typed#builder()}.
      */
+    @Deprecated(since = "1.21.4")
     @NotNull
     public static Merchant createMerchant(@Nullable String title) {
         return server.createMerchant(title);
     }
 
+    /**
+     * Creates an empty merchant.
+     *
+     * @return a new merchant
+     */
+    @NotNull
+    public static Merchant createMerchant() {
+        return server.createMerchant();
+    }
+
     /**
      * Gets the amount of consecutive neighbor updates before skipping
      * additional ones.

src/main/java/org/bukkit/Server.java

@@ -40,6 +40,7 @@ import org.bukkit.inventory.InventoryHolder;
 import org.bukkit.inventory.ItemCraftResult;
 import org.bukkit.inventory.ItemFactory;
 import org.bukkit.inventory.ItemStack;
+import org.bukkit.inventory.MenuType;
 import org.bukkit.inventory.Merchant;
 import org.bukkit.inventory.Recipe;
 import org.bukkit.inventory.meta.ItemMeta;
@@ -1254,11 +1255,11 @@ public interface Server extends PluginMessageRecipient {
      * <br>
      * {@link InventoryType#WORKBENCH} will not process crafting recipes if
      * created with this method. Use
-     * {@link Player#openWorkbench(Location, boolean)} instead.
+     * {@link MenuType#CRAFTING} instead.
      * <br>
      * {@link InventoryType#ENCHANTING} will not process {@link ItemStack}s
      * for possible enchanting results. Use
-     * {@link Player#openEnchanting(Location, boolean)} instead.
+     * {@link MenuType#ENCHANTMENT} instead.
      *
      * @param owner the holder of the inventory, or null to indicate no holder
      * @param type the type of inventory to create
@@ -1280,11 +1281,11 @@ public interface Server extends PluginMessageRecipient {
      * <br>
      * {@link InventoryType#WORKBENCH} will not process crafting recipes if
      * created with this method. Use
-     * {@link Player#openWorkbench(Location, boolean)} instead.
+     * {@link MenuType#CRAFTING} instead.
      * <br>
      * {@link InventoryType#ENCHANTING} will not process {@link ItemStack}s
      * for possible enchanting results. Use
-     * {@link Player#openEnchanting(Location, boolean)} instead.
+     * {@link MenuType#ENCHANTMENT} instead.
      *
      * @param owner The holder of the inventory; can be null if there's no holder.
      * @param type The type of inventory to create.
@@ -1330,10 +1331,21 @@ public interface Server extends PluginMessageRecipient {
      * @param title the title of the corresponding merchant inventory, displayed
      * when the merchant inventory is viewed
      * @return a new merchant
+     * @deprecated The title parameter is no-longer needed when used with
+     * {@link MenuType#MERCHANT} and {@link MenuType.Typed#builder()}.
      */
+    @Deprecated(since = "1.21.4")
     @NotNull
     Merchant createMerchant(@Nullable String title);
 
+    /**
+     * Creates an empty merchant.
+     *
+     * @return a new merchant
+     */
+    @NotNull
+    Merchant createMerchant();
+
     /**
      * Gets the amount of consecutive neighbor updates before skipping
      * additional ones.

src/main/java/org/bukkit/entity/HumanEntity.java

@@ -11,6 +11,7 @@ import org.bukkit.inventory.InventoryHolder;
 import org.bukkit.inventory.InventoryView;
 import org.bukkit.inventory.ItemStack;
 import org.bukkit.inventory.MainHand;
+import org.bukkit.inventory.MenuType;
 import org.bukkit.inventory.Merchant;
 import org.bukkit.inventory.PlayerInventory;
 import org.bukkit.inventory.meta.FireworkMeta;
@@ -118,7 +119,10 @@ public interface HumanEntity extends LivingEntity, AnimalTamer, InventoryHolder
      *     no inventory will be opened and null will be returned.
      * @return The newly opened inventory view, or null if it could not be
      *     opened.
+     * @deprecated This method should be replaced by {@link MenuType#CRAFTING}
+     * see {@link MenuType.Typed#builder()} and its options for more information.
      */
+    @Deprecated(since = "1.21.4")
     @Nullable
     public InventoryView openWorkbench(@Nullable Location location, boolean force);
 
@@ -132,7 +136,10 @@ public interface HumanEntity extends LivingEntity, AnimalTamer, InventoryHolder
      *     location, no inventory will be opened and null will be returned.
      * @return The newly opened inventory view, or null if it could not be
      *     opened.
+     * @deprecated This method should be replaced by {@link MenuType#ENCHANTMENT}
+     * see {@link MenuType.Typed#builder()} and its options for more information.
      */
+    @Deprecated(since = "1.21.4")
     @Nullable
     public InventoryView openEnchanting(@Nullable Location location, boolean force);
 
@@ -159,7 +166,10 @@ public interface HumanEntity extends LivingEntity, AnimalTamer, InventoryHolder
      * @param force whether to force the trade even if another player is trading
      * @return The newly opened inventory view, or null if it could not be
      * opened.
+     * @deprecated This method can be replaced by using {@link MenuType#MERCHANT}
+     * in conjunction with {@link #openInventory(InventoryView)}.
      */
+    @Deprecated(since = "1.21.4")
     @Nullable
     public InventoryView openMerchant(@NotNull Villager trader, boolean force);
 
@@ -173,7 +183,10 @@ public interface HumanEntity extends LivingEntity, AnimalTamer, InventoryHolder
      * @param force whether to force the trade even if another player is trading
      * @return The newly opened inventory view, or null if it could not be
      * opened.
+     * @deprecated This method can be replaced by using {@link MenuType#MERCHANT}
+     * in conjunction with {@link #openInventory(InventoryView)}.
      */
+    @Deprecated(since = "1.21.4")
     @Nullable
     public InventoryView openMerchant(@NotNull Merchant merchant, boolean force);