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

Class DataObject

java.lang.Object
net.dv8tion.jda.api.utils.data.DataObject
All Implemented Interfaces:
SerializableData
public class DataObject extends 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 Details

    • empty

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

    • 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 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 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 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:
      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 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 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 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:

    • getObject

      @Nonnull public DataObject getObject(@Nonnull 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 Optional<DataObject> optObject(@Nonnull 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 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 Optional<DataArray> optArray(@Nonnull 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 Optional<Object> opt(@Nonnull 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 Object get(@Nonnull 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:

    • getString

      @Nonnull public String getString(@Nonnull 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 String getString(@Nonnull String key, @Nullable 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 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 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 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 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 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 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 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 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 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 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 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 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

    • getOffsetDateTime

      @Nonnull public OffsetDateTime getOffsetDateTime(@Nonnull String key)
      Resolves an OffsetDateTime to a key.
      Note: This method should be used on ISO8601 timestamps
      Parameters:
      key - The key to check for a value
      Returns:
      Possibly-null OffsetDateTime object representing the timestamp
      Throws:
      ParsingException - If the value is missing, null, or not a valid ISO8601 timestamp

    • getOffsetDateTime

      @Contract("_, !null -> !null") public OffsetDateTime getOffsetDateTime(@Nonnull String key, @Nullable OffsetDateTime defaultValue)
      Resolves an OffsetDateTime to a key.
      Note: This method should only be used on ISO8601 timestamps
      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:
      Possibly-null OffsetDateTime object representing the timestamp
      Throws:
      ParsingException - If the value is not a valid ISO8601 timestamp

    • remove

      @Nonnull public DataObject remove(@Nonnull 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 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 String key, @Nullable 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

    • rename

      @Nonnull public DataObject rename(@Nonnull String key, @Nonnull String newKey)
      Renames an existing field to the new name.
      This is a shorthand to remove under the old key and then put under the new key.

      If there is nothing mapped to the old key, this does nothing.

      Parameters:
      key - The old key
      newKey - The new key
      Returns:
      A DataObject with the updated value
      Throws:
      IllegalArgumentException - If null is provided

    • values

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

    • keys

      @Nonnull public Set<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 String toString()
      Overrides:
      toString in class Object

    • toPrettyString

      @Nonnull public String toPrettyString()

    • toMap

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

    • toData

      @Nonnull public DataObject toData()
      Description copied from interface: SerializableData
      Serialized DataObject for this object.
      Specified by:
      toData in interface SerializableData
      Returns:
      DataObject

    • equals

      public boolean equals(Object obj)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object