SPIGOT-4608: Improve quality of MapMeta APIs

By: md_5 <git@md-5.net>

paper-api/src/main/java/org/bukkit/Bukkit.java

@@ -521,7 +521,7 @@ public final class Bukkit {
      * @deprecated Magic value
      */
     @Deprecated
-    public static MapView getMap(short id) {
+    public static MapView getMap(int id) {
         return server.getMap(id);
     }
 

paper-api/src/main/java/org/bukkit/Server.java

@@ -433,7 +433,7 @@ public interface Server extends PluginMessageRecipient {
      * @deprecated Magic value
      */
     @Deprecated
-    public MapView getMap(short id);
+    public MapView getMap(int id);
 
     /**
      * Create a new map with an automatically assigned ID.

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

@@ -1,6 +1,7 @@
 package org.bukkit.inventory.meta;
 
 import org.bukkit.Color;
+import org.bukkit.map.MapView;
 
 /**
  * Represents a map that can be scalable.
@@ -11,7 +12,14 @@ public interface MapMeta extends ItemMeta {
      * Checks for existence of a map ID number.
      *
      * @return true if this has a map ID number.
+     * @deprecated These methods are poor API: They rely on the caller to pass
+     * in an only an integer property, and have poorly defined implementation
+     * behavior if that integer is not a valid map (the current implementation
+     * for example will generate a new map with a different ID). The xxxMapView
+     * family of methods should be used instead.
+     * @see #hasMapView()
      */
+    @Deprecated
     boolean hasMapId();
 
     /**
@@ -22,16 +30,61 @@ public interface MapMeta extends ItemMeta {
      * calling this method.
      *
      * @return the map ID that is set
+     * @deprecated These methods are poor API: They rely on the caller to pass
+     * in an only an integer property, and have poorly defined implementation
+     * behavior if that integer is not a valid map (the current implementation
+     * for example will generate a new map with a different ID). The xxxMapView
+     * family of methods should be used instead.
+     * @see #getMapView()
      */
+    @Deprecated
     int getMapId();
 
     /**
      * Sets the map ID. This is used to determine what map is displayed.
      *
      * @param id the map id to set
+     * @deprecated These methods are poor API: They rely on the caller to pass
+     * in an only an integer property, and have poorly defined implementation
+     * behavior if that integer is not a valid map (the current implementation
+     * for example will generate a new map with a different ID). The xxxMapView
+     * family of methods should be used instead.
+     * @see #setMapView(org.bukkit.map.MapView)
      */
+    @Deprecated
     void setMapId(int id);
 
+    /**
+     * Checks for existence of an associated map.
+     *
+     * @return true if this item has an associated map
+     */
+    boolean hasMapView();
+
+    /**
+     * Gets the map view that is associated with this map item.
+     *
+     * <p>
+     * Plugins should check that hasMapView() returns <code>true</code> before
+     * calling this method.
+     *
+     * @return the map view, or null if the item hasMapView(), but this map does
+     * not exist on the server
+     */
+    MapView getMapView();
+
+    /**
+     * Sets the associated map. This is used to determine what map is displayed.
+     *
+     * <p>
+     * The implementation <b>may</b> allow null to clear the associated map, but
+     * this is not required and is liable to generate a new (undefined) map when
+     * the item is first used.
+     *
+     * @param map the map to set
+     */
+    void setMapView(MapView map);
+
     /**
      * Checks to see if this map is scaling.
      *