#3490: Add ComponentBuilder#build() and ComponentSerializer#deserialize()

Components traditionally use the extra data to represent components as a single BaseComponent object. While BaseComponent typically mirrors this behaviour, somewhere along the development of BungeeChat this practice was made unclear. Because ComponentBuilder#create() returns an array of BaseComponents, it has sort of been silently accepted that all components should be represented as arrays, which is incorrect. This heavily influenced the direction of Spigot's component API (with additions such as CommandSender#sendMessage(BaseComponent[])) which emphasizes this misconception of "all components are arrays".

Adding new methods to ComponentBuilder and ComponentSerializer should steer use of the BungeeChat API to be more oriented towards single component instances, not arrays.

chat/src/main/java/net/md_5/bungee/api/chat/ComponentBuilder.java

@@ -454,9 +454,32 @@ public final class ComponentBuilder
         return this;
     }
 
+    /**
+     * Returns the component built by this builder. If this builder is
+     * empty, an empty text component will be returned.
+     *
+     * @return the component
+     */
+    public BaseComponent build()
+    {
+        TextComponent base = new TextComponent();
+        if ( !parts.isEmpty() )
+        {
+            List<BaseComponent> cloned = new ArrayList<>( parts );
+            cloned.replaceAll( BaseComponent::duplicate );
+            base.setExtra( cloned );
+        }
+        return base;
+    }
+
     /**
      * Returns the components needed to display the message created by this
      * builder.git
+     * <p>
+     * <strong>NOTE:</strong> {@link #build()} is preferred as it will
+     * consolidate all components into a single BaseComponent with extra
+     * contents as opposed to an array of components which is non-standard
+     * and may result in unexpected behavior.
      *
      * @return the created components
      */

chat/src/main/java/net/md_5/bungee/api/chat/hover/content/Text.java

@@ -23,6 +23,12 @@ public class Text extends Content
         this.value = value;
     }
 
+    public Text(BaseComponent value)
+    {
+        // For legacy serialization reasons, this has to be an array of components
+        this( new BaseComponent[]{value} );
+    }
+
     public Text(String value)
     {
         this.value = value;

chat/src/main/java/net/md_5/bungee/chat/ComponentSerializer.java

@@ -27,7 +27,6 @@ import net.md_5.bungee.api.chat.hover.content.TextSerializer;
 public class ComponentSerializer implements JsonDeserializer<BaseComponent>
 {
 
-    private static final JsonParser JSON_PARSER = new JsonParser();
     private static final Gson gson = new GsonBuilder().
             registerTypeAdapter( BaseComponent.class, new ComponentSerializer() ).
             registerTypeAdapter( TextComponent.class, new TextComponentSerializer() ).
@@ -43,9 +42,25 @@ public class ComponentSerializer implements JsonDeserializer<BaseComponent>
 
     public static final ThreadLocal<Set<BaseComponent>> serializedComponents = new ThreadLocal<Set<BaseComponent>>();
 
+    /**
+     * Parse a JSON-compliant String as an array of base components. The input
+     * can be one of either an array of components, or a single component object.
+     * If the input is an array, each component will be parsed individually and
+     * returned in the order that they were parsed. If the input is a single
+     * component object, a single-valued array with the component will be returned.
+     * <p>
+     * <strong>NOTE:</strong> {@link #deserialize(String)} is preferred as it will
+     * parse only one component as opposed to an array of components which is non-
+     * standard behavior. This method is still appropriate for parsing multiple
+     * components at once, although such use case is rarely (if at all) exhibited
+     * in vanilla Minecraft.
+     *
+     * @param json the component json to parse
+     * @return an array of all parsed components
+     */
     public static BaseComponent[] parse(String json)
     {
-        JsonElement jsonElement = JSON_PARSER.parse( json );
+        JsonElement jsonElement = JsonParser.parseString( json );
 
         if ( jsonElement.isJsonArray() )
         {
@@ -59,6 +74,26 @@ public class ComponentSerializer implements JsonDeserializer<BaseComponent>
         }
     }
 
+    /**
+     * Deserialize a JSON-compliant String as a single component. The input is
+     * expected to be a JSON object that represents only one component.
+     *
+     * @param json the component json to parse
+     * @return the deserialized component
+     * @throws IllegalArgumentException if anything other than a JSON object is
+     * passed as input
+     */
+    public static BaseComponent deserialize(String json)
+    {
+        JsonElement jsonElement = JsonParser.parseString( json );
+        if ( !jsonElement.isJsonObject() )
+        {
+            throw new IllegalArgumentException( "Malformatted JSON. Expected object, got array for input \"" + json + "\"." );
+        }
+
+        return gson.fromJson( jsonElement, BaseComponent.class );
+    }
+
     public static String toString(Object object)
     {
         return gson.toJson( object );