Package net.dv8tion.jda.api.utils.data

Class DataObject

  • All Implemented Interfaces:
    SerializableData
    public class DataObject
extends java.lang.Object
implements SerializableData
    Represents a map of values used in communication with the Discord API.

    Throws NullPointerException, if a parameter annotated with Nonnull is provided with null.

    This class is not Thread-Safe.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      static DataObject empty()
      Creates a new empty DataObject, ready to be populated with values.
      static DataObject fromETF​(byte[] data)
      Parses using ExTermDecoder.
      static DataObject fromJson​(byte[] data)
      Parses a JSON payload into a DataObject instance.
      static DataObject fromJson​(java.io.InputStream stream)
      Parses a JSON payload into a DataObject instance.
      static DataObject fromJson​(java.io.Reader stream)
      Parses a JSON payload into a DataObject instance.
      static DataObject fromJson​(java.lang.String json)
      Parses a JSON payload into a DataObject instance.
      java.lang.Object get​(java.lang.String key)
      Resolves any type to the provided key.
      DataArray getArray​(java.lang.String key)
      Resolves a DataArray to a key.
      boolean getBoolean​(java.lang.String key)
      Resolves a Boolean to a key.
      boolean getBoolean​(java.lang.String key, boolean defaultValue)
      Resolves a Boolean to a key.
      double getDouble​(java.lang.String key)
      Resolves a double to a key.
      double getDouble​(java.lang.String key, double defaultValue)
      Resolves a double to a key.
      int getInt​(java.lang.String key)
      Resolves an int to a key.
      int getInt​(java.lang.String key, int defaultValue)
      Resolves an int to a key.
      long getLong​(java.lang.String key)
      Resolves a long to a key.
      long getLong​(java.lang.String key, long defaultValue)
      Resolves a long to a key.
      DataObject getObject​(java.lang.String key)
      Resolves a DataObject to a key.
      java.lang.String getString​(java.lang.String key)
      Resolves a String to a key.
      java.lang.String getString​(java.lang.String key, java.lang.String defaultValue)
      Resolves a String to a key.
      int getUnsignedInt​(java.lang.String key)
      Resolves an unsigned int to a key.
      int getUnsignedInt​(java.lang.String key, int defaultValue)
      Resolves an unsigned int to a key.
      long getUnsignedLong​(java.lang.String key)
      Resolves an unsigned long to a key.
      long getUnsignedLong​(java.lang.String key, long defaultValue)
      Resolves an unsigned long to a key.
      boolean hasKey​(java.lang.String key)
      Whether the specified key is present.
      boolean isNull​(java.lang.String key)
      Whether the specified key is missing or null
      boolean isType​(java.lang.String key, DataType type)
      Whether the specified key is of the specified type.
      java.util.Set<java.lang.String> keys()
      Set of all keys in this DataObject.
      java.util.Optional<java.lang.Object> opt​(java.lang.String key)
      Resolves any type to the provided key.
      java.util.Optional<DataArray> optArray​(java.lang.String key)
      Resolves a DataArray to a key.
      java.util.Optional<DataObject> optObject​(java.lang.String key)
      Resolves a DataObject to a key.
      DataObject put​(java.lang.String key, java.lang.Object value)
      Upserts a new value for the provided key.
      DataObject putNull​(java.lang.String key)
      Upserts a null value for the provided key.
      DataObject remove​(java.lang.String key)
      Removes the value associated with the specified key.
      DataObject toData()
      Serialized DataObject for this object.
      byte[] toETF()
      Serializes this object as ETF MAP term.
      byte[] toJson()
      Serialize this object as JSON.
      java.util.Map<java.lang.String,​java.lang.Object> toMap()
      Converts this DataObject to a Map
      java.lang.String toPrettyString()  
      java.lang.String toString()  
      java.util.Collection<java.lang.Object> values()
      Collection of all values in this DataObject.

      • Methods inherited from class java.lang.Object

        equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

    • Method Detail

      • empty

        @Nonnull
public static DataObject empty()
        Creates a new empty DataObject, ready to be populated with values.
        Returns:
        An empty DataObject instance
        See Also:
        put(String, Object)

      • fromJson

        @Nonnull
public static DataObject fromJson​(@Nonnull
                                  byte[] data)
        Parses a JSON payload into a DataObject instance.
        Parameters:
        data - The correctly formatted JSON payload to parse
        Returns:
        A DataObject instance for the provided payload
        Throws:
        ParsingException - If the provided json is incorrectly formatted

      • fromJson

        @Nonnull
public static DataObject fromJson​(@Nonnull
                                  java.lang.String json)
        Parses a JSON payload into a DataObject instance.
        Parameters:
        json - The correctly formatted JSON payload to parse
        Returns:
        A DataObject instance for the provided payload
        Throws:
        ParsingException - If the provided json is incorrectly formatted

      • fromJson

        @Nonnull
public static DataObject fromJson​(@Nonnull
                                  java.io.InputStream stream)
        Parses a JSON payload into a DataObject instance.
        Parameters:
        stream - The correctly formatted JSON payload to parse
        Returns:
        A DataObject instance for the provided payload
        Throws:
        ParsingException - If the provided json is incorrectly formatted or an I/O error occurred

      • fromJson

        @Nonnull
public static DataObject fromJson​(@Nonnull
                                  java.io.Reader stream)
        Parses a JSON payload into a DataObject instance.
        Parameters:
        stream - The correctly formatted JSON payload to parse
        Returns:
        A DataObject instance for the provided payload
        Throws:
        ParsingException - If the provided json is incorrectly formatted or an I/O error occurred

      • fromETF

        @Nonnull
public static DataObject fromETF​(@Nonnull
                                 byte[] data)
        Parses using ExTermDecoder. The provided data must start with the correct version header (131).
        Parameters:
        data - The data to decode
        Returns:
        A DataObject instance for the provided payload
        Throws:
        java.lang.IllegalArgumentException - If the provided data is null
        ParsingException - If the provided ETF payload is incorrectly formatted or an I/O error occurred
        Since:
        4.2.1

      • hasKey

        public boolean hasKey​(@Nonnull
                      java.lang.String key)
        Whether the specified key is present.
        Parameters:
        key - The key to check
        Returns:
        True, if the specified key is present

      • isNull

        public boolean isNull​(@Nonnull
                      java.lang.String key)
        Whether the specified key is missing or null
        Parameters:
        key - The key to check
        Returns:
        True, if the specified key is null or missing

      • isType

        public boolean isType​(@Nonnull
                      java.lang.String key,
                      @Nonnull
                      DataType type)
        Whether the specified key is of the specified type.
        Parameters:
        key - The key to check
        type - The type to check
        Returns:
        True, if the type check is successful
        See Also:
        DataType.isType(Object)

      • getObject

        @Nonnull
public DataObject getObject​(@Nonnull
                            java.lang.String key)
        Resolves a DataObject to a key.
        Parameters:
        key - The key to check for a value
        Returns:
        The resolved instance of DataObject for the key
        Throws:
        ParsingException - If the type is incorrect or no value is present for the specified key

      • optObject

        @Nonnull
public java.util.Optional<DataObject> optObject​(@Nonnull
                                                java.lang.String key)
        Resolves a DataObject to a key.
        Parameters:
        key - The key to check for a value
        Returns:
        The resolved instance of DataObject for the key, wrapped in Optional
        Throws:
        ParsingException - If the type is incorrect

      • getArray

        @Nonnull
public DataArray getArray​(@Nonnull
                          java.lang.String key)
        Resolves a DataArray to a key.
        Parameters:
        key - The key to check for a value
        Returns:
        The resolved instance of DataArray for the key
        Throws:
        ParsingException - If the type is incorrect or no value is present for the specified key

      • optArray

        @Nonnull
public java.util.Optional<DataArray> optArray​(@Nonnull
                                              java.lang.String key)
        Resolves a DataArray to a key.
        Parameters:
        key - The key to check for a value
        Returns:
        The resolved instance of DataArray for the key, wrapped in Optional
        Throws:
        ParsingException - If the type is incorrect

      • opt

        @Nonnull
public java.util.Optional<java.lang.Object> opt​(@Nonnull
                                                java.lang.String key)
        Resolves any type to the provided key.
        Parameters:
        key - The key to check for a value
        Returns:
        Optional with a possible value

      • get

        @Nonnull
public java.lang.Object get​(@Nonnull
                            java.lang.String key)
        Resolves any type to the provided key.
        Parameters:
        key - The key to check for a value
        Returns:
        The value of any type
        Throws:
        ParsingException - If the value is missing or null
        See Also:
        opt(String)

      • getString

        @Nonnull
public java.lang.String getString​(@Nonnull
                                  java.lang.String key)
        Resolves a String to a key.
        Parameters:
        key - The key to check for a value
        Returns:
        The String value
        Throws:
        ParsingException - If the value is missing or null

      • getString

        @Contract("_, !null -> !null")
public java.lang.String getString​(@Nonnull
                                  java.lang.String key,
                                  @Nullable
                                  java.lang.String defaultValue)
        Resolves a String to a key.
        Parameters:
        key - The key to check for a value
        defaultValue - Alternative value to use when no value or null value is associated with the key
        Returns:
        The String value, or null if provided with null defaultValue

      • getBoolean

        public boolean getBoolean​(@Nonnull
                          java.lang.String key)
        Resolves a Boolean to a key.
        Parameters:
        key - The key to check for a value
        Returns:
        True, if the value is present and set to true. False if the value is missing or set to false.
        Throws:
        ParsingException - If the value is of the wrong type

      • getBoolean

        public boolean getBoolean​(@Nonnull
                          java.lang.String key,
                          boolean defaultValue)
        Resolves a Boolean to a key.
        Parameters:
        key - The key to check for a value
        defaultValue - Alternative value to use when no value or null value is associated with the key
        Returns:
        True, if the value is present and set to true. False if the value is set to false. defaultValue if it is missing.
        Throws:
        ParsingException - If the value is of the wrong type

      • getLong

        public long getLong​(@Nonnull
                    java.lang.String key)
        Resolves a long to a key.
        Parameters:
        key - The key to check for a value
        Returns:
        The long value for the key
        Throws:
        ParsingException - If the value is missing, null, or of the wrong type

      • getLong

        public long getLong​(@Nonnull
                    java.lang.String key,
                    long defaultValue)
        Resolves a long to a key.
        Parameters:
        key - The key to check for a value
        defaultValue - Alternative value to use when no value or null value is associated with the key
        Returns:
        The long value for the key
        Throws:
        ParsingException - If the value is of the wrong type

      • getUnsignedLong

        public long getUnsignedLong​(@Nonnull
                            java.lang.String key)
        Resolves an unsigned long to a key.
        Parameters:
        key - The key to check for a value
        Returns:
        The unsigned long value for the key
        Throws:
        ParsingException - If the value is missing, null, or of the wrong type

      • getUnsignedLong

        public long getUnsignedLong​(@Nonnull
                            java.lang.String key,
                            long defaultValue)
        Resolves an unsigned long to a key.
        Parameters:
        key - The key to check for a value
        defaultValue - Alternative value to use when no value or null value is associated with the key
        Returns:
        The unsigned long value for the key
        Throws:
        ParsingException - If the value is of the wrong type

      • getInt

        public int getInt​(@Nonnull
                  java.lang.String key)
        Resolves an int to a key.
        Parameters:
        key - The key to check for a value
        Returns:
        The int value for the key
        Throws:
        ParsingException - If the value is missing, null, or of the wrong type

      • getInt

        public int getInt​(@Nonnull
                  java.lang.String key,
                  int defaultValue)
        Resolves an int to a key.
        Parameters:
        key - The key to check for a value
        defaultValue - Alternative value to use when no value or null value is associated with the key
        Returns:
        The int value for the key
        Throws:
        ParsingException - If the value is of the wrong type

      • getUnsignedInt

        public int getUnsignedInt​(@Nonnull
                          java.lang.String key)
        Resolves an unsigned int to a key.
        Parameters:
        key - The key to check for a value
        Returns:
        The unsigned int value for the key
        Throws:
        ParsingException - If the value is missing, null, or of the wrong type

      • getUnsignedInt

        public int getUnsignedInt​(@Nonnull
                          java.lang.String key,
                          int defaultValue)
        Resolves an unsigned int to a key.
        Parameters:
        key - The key to check for a value
        defaultValue - Alternative value to use when no value or null value is associated with the key
        Returns:
        The unsigned int value for the key
        Throws:
        ParsingException - If the value is of the wrong type

      • getDouble

        public double getDouble​(@Nonnull
                        java.lang.String key)
        Resolves a double to a key.
        Parameters:
        key - The key to check for a value
        Returns:
        The double value for the key
        Throws:
        ParsingException - If the value is missing, null, or of the wrong type

      • getDouble

        public double getDouble​(@Nonnull
                        java.lang.String key,
                        double defaultValue)
        Resolves a double to a key.
        Parameters:
        key - The key to check for a value
        defaultValue - Alternative value to use when no value or null value is associated with the key
        Returns:
        The double value for the key
        Throws:
        ParsingException - If the value is of the wrong type

      • remove

        @Nonnull
public DataObject remove​(@Nonnull
                         java.lang.String key)
        Removes the value associated with the specified key. If no value is associated with the key, this does nothing.
        Parameters:
        key - The key to unlink
        Returns:
        A DataObject with the removed key

      • putNull

        @Nonnull
public DataObject putNull​(@Nonnull
                          java.lang.String key)
        Upserts a null value for the provided key.
        Parameters:
        key - The key to upsert
        Returns:
        A DataObject with the updated value

      • put

        @Nonnull
public DataObject put​(@Nonnull
                      java.lang.String key,
                      @Nullable
                      java.lang.Object value)
        Upserts a new value for the provided key.
        Parameters:
        key - The key to upsert
        value - The new value
        Returns:
        A DataObject with the updated value

      • values

        @Nonnull
public java.util.Collection<java.lang.Object> values()
        Collection of all values in this DataObject.
        Returns:
        Collection for all values

      • keys

        @Nonnull
public java.util.Set<java.lang.String> keys()
        Set of all keys in this DataObject.
        Returns:
        Set of keys

      • toJson

        @Nonnull
public byte[] toJson()
        Serialize this object as JSON.
        Returns:
        byte array containing the JSON representation of this object

      • toETF

        @Nonnull
public byte[] toETF()
        Serializes this object as ETF MAP term.
        Returns:
        byte array containing the encoded ETF term
        Since:
        4.2.1

      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object

      • toPrettyString

        @Nonnull
public java.lang.String toPrettyString()

      • toMap

        @Nonnull
public java.util.Map<java.lang.String,​java.lang.Object> toMap()
        Converts this DataObject to a Map
        Returns:
        The resulting map