[B+C] Add API to use 1.7 chat features. Adds BUKKIT-5245

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

@@ -11,6 +11,7 @@
 import java.util.logging.Logger;
 
 import org.bukkit.Warning.WarningState;
+import org.bukkit.chat.Message;
 import org.bukkit.command.CommandException;
 import org.bukkit.command.CommandSender;
 import org.bukkit.command.ConsoleCommandSender;
@@ -187,6 +188,13 @@ public static int broadcastMessage(String message) {
         return server.broadcastMessage(message);
     }
 
+    /**
+     * @see Server#broadcastMessage(org.bukkit.chat.Message message)
+     */
+    public static int broadcastMessage(Message message) {
+        return server.broadcastMessage(message);
+    }
+
     /**
      * @see Server#getUpdateFolder()
      */
@@ -429,6 +437,13 @@ public static int broadcast(String message, String permission) {
         return server.broadcast(message, permission);
     }
 
+    /**
+     * @see Server#broadcast(Message message, String permission)
+     */
+    public static int broadcast(Message message, String permission) {
+        return server.broadcast(message, permission);
+    }
+
     /**
      * @see Server#getOfflinePlayer(String name)
      */
@@ -609,10 +624,18 @@ public static Inventory createInventory(InventoryHolder owner, InventoryType typ
     /**
      * @see Server#createInventory(InventoryHolder owner, InventoryType type, String title)
      */
+    @Deprecated
     public static Inventory createInventory(InventoryHolder owner, InventoryType type, String title) {
         return server.createInventory(owner, type, title);
     }
 
+    /**
+     * @see Server#createInventory(InventoryHolder, InventoryType, Message)
+     */
+    public static Inventory createInventory(InventoryHolder owner, InventoryType type, Message title) {
+        return server.createInventory(owner, type, title);
+    }
+
     /**
      * @see Server#createInventory(InventoryHolder owner, int size)
      */
@@ -624,10 +647,18 @@ public static Inventory createInventory(InventoryHolder owner, int size) throws
      * @see Server#createInventory(InventoryHolder owner, int size, String
      *     title)
      */
+    @Deprecated
     public static Inventory createInventory(InventoryHolder owner, int size, String title) throws IllegalArgumentException {
         return server.createInventory(owner, size, title);
     }
 
+    /**
+     * @see Server#createInventory(InventoryHolder, int, Message)
+     */
+    public static Inventory createInventory(InventoryHolder owner, int size, Message title) throws IllegalArgumentException {
+        return server.createInventory(owner, size, title);
+    }
+
     /**
      * @see Server#getHelpMap()
      */

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

@@ -13,6 +13,7 @@
 import java.util.logging.Logger;
 
 import org.bukkit.Warning.WarningState;
+import org.bukkit.chat.Message;
 import org.bukkit.command.CommandException;
 import org.bukkit.command.CommandSender;
 import org.bukkit.command.ConsoleCommandSender;
@@ -236,6 +237,17 @@ public interface Server extends PluginMessageRecipient {
      */
     public int broadcastMessage(String message);
 
+    /**
+     * Broadcast a rich message to all players.
+     * <p>
+     * This is the same as calling {@link #broadcast(Message, String)}
+     * to {@link #BROADCAST_CHANNEL_USERS}
+     *
+     * @param message the rich message
+     * @return the number of players
+     */
+    public int broadcastMessage(Message message);
+
     /**
      * Gets the name of the update folder. The update folder is used to safely
      * update plugins at the right moment on a plugin load.
@@ -594,6 +606,17 @@ public interface Server extends PluginMessageRecipient {
      */
     public int broadcast(String message, String permission);
 
+    /**
+     * Broadcasts the specified rich message to every user with the given
+     * permission name.
+     *
+     * @param message rich message to broadcast
+     * @param permission the required permission {@link Permissible
+     *     permissibles} must have to receive the broadcast
+     * @return number of message recipients
+     */
+    public int broadcast(Message message, String permission);
+
     /**
      * Gets the player by the given name, regardless if they are offline or
      * online.
@@ -743,9 +766,27 @@ public interface Server extends PluginMessageRecipient {
      * @param type The type of inventory to create.
      * @param title The title of the inventory, to be displayed when it is viewed.
      * @return The new inventory.
+     * @deprecated This method now uses {@link Message} to set the title. Use
+     *     {@link #createInventory(InventoryHolder, InventoryType, Message)}
+     *     instead.
      */
+    @Deprecated
     Inventory createInventory(InventoryHolder owner, InventoryType type, String title);
 
+    /**
+     * Creates an empty inventory with the specified type and title. If the type
+     * is {@link InventoryType#CHEST}, the new inventory has a size of 27;
+     * otherwise the new inventory has the normal size for its type.<br />
+     * It should be noted that some inventory types do not support titles and
+     * may not render with said titles on the Minecraft client.
+     *
+     * @param owner The holder of the inventory; can be null if there's no holder.
+     * @param type The type of inventory to create.
+     * @param title The title of the inventory, to be displayed when it is viewed.
+     * @return The new inventory.
+     */
+    Inventory createInventory(InventoryHolder owner, InventoryType type, Message title);
+
     /**
      * Creates an empty inventory of type {@link InventoryType#CHEST} with the
      * specified size.
@@ -767,9 +808,25 @@ public interface Server extends PluginMessageRecipient {
      *     viewed
      * @return a new inventory
      * @throws IllegalArgumentException if the size is not a multiple of 9
+     * @deprecated This method now uses {@link Message} to set the title. Use
+     *     {@link #createInventory(InventoryHolder, int, Message)} instead.
      */
+    @Deprecated
     Inventory createInventory(InventoryHolder owner, int size, String title) throws IllegalArgumentException;
 
+    /**
+     * Creates an empty inventory of type {@link InventoryType#CHEST} with the
+     * specified size and title.
+     *
+     * @param owner the holder of the inventory, or null to indicate no holder
+     * @param size a multiple of 9 as the size of inventory to create
+     * @param title the title of the inventory, displayed when inventory is
+     *     viewed
+     * @return a new inventory
+     * @throws IllegalArgumentException if the size is not a multiple of 9
+     */
+    Inventory createInventory(InventoryHolder owner, int size, Message title) throws IllegalArgumentException;
+
     /**
      * Gets user-specified limit for number of monsters that can spawn in a
      * chunk.

src/main/java/org/bukkit/block/Sign.java

@@ -1,5 +1,7 @@
 package org.bukkit.block;
 
+import org.bukkit.chat.Message;
+
 /**
  * Represents either a SignPost or a WallSign
  */
@@ -9,9 +11,19 @@ public interface Sign extends BlockState {
      * Gets all the lines of text currently on this sign.
      *
      * @return Array of Strings containing each line of text
+     * @deprecated This method now uses {@link Message} to return the lines. Use
+     *     {@link #getLineMessages()} instead.
      */
+    @Deprecated
     public String[] getLines();
 
+    /**
+     * Gets all the lines of text currently on this sign.
+     *
+     * @return Array of Message containing each line of text
+     */
+    public Message[] getLineMessages();
+
     /**
      * Gets the line of text at the specified index.
      * <p>
@@ -20,9 +32,23 @@ public interface Sign extends BlockState {
      * @param index Line number to get the text from, starting at 0
      * @throws IndexOutOfBoundsException Thrown when the line does not exist
      * @return Text on the given line
+     * @deprecated This method now uses {@link Message} to return the line. Use
+     *     {@link #getLineMessage(int)} instead.
      */
+    @Deprecated
     public String getLine(int index) throws IndexOutOfBoundsException;
 
+    /**
+     * Gets the line of text at the specified index.
+     * <p>
+     * For example, getLine(0) will return the first line of text.
+     *
+     * @param index Line number to get the text from, starting at 0
+     * @throws IndexOutOfBoundsException Thrown when the line does not exist
+     * @return Message on the given line
+     */
+    public Message getLineMessage(int index) throws IndexOutOfBoundsException;
+
     /**
      * Sets the line of text at the specified index.
      * <p>
@@ -32,6 +58,21 @@ public interface Sign extends BlockState {
      * @param index Line number to set the text at, starting from 0
      * @param line New text to set at the specified index
      * @throws IndexOutOfBoundsException If the index is out of the range 0..3
+     * @deprecated This method now uses {@link Message} to set the lines. Use
+     *     {@link #setLine(int,Message)} instead.
      */
+    @Deprecated
     public void setLine(int index, String line) throws IndexOutOfBoundsException;
+
+    /**
+     * Sets the line of text at the specified index.
+     * <p>
+     * For example, setLine(0, "Line One") will set the first line of text to
+     * "Line One".
+     *
+     * @param index Line number to set the text at, starting from 0
+     * @param line New text to set at the specified index
+     * @throws IndexOutOfBoundsException If the index is out of the range 0..3
+     */
+    public void setLine(int index, Message line) throws IndexOutOfBoundsException;
 }