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 Summary

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(InputStream stream)	Parses a JSON payload into a DataObject instance.
static DataObject	fromJson(Reader stream)	Parses a JSON payload into a DataObject instance.
static DataObject	fromJson(String json)	Parses a JSON payload into a DataObject instance.
Object	get(String key)	Resolves any type to the provided key.
DataArray	getArray(String key)	Resolves a DataArray to a key.
boolean	getBoolean(String key)	Resolves a Boolean to a key.
boolean	getBoolean(String key, boolean defaultValue)	Resolves a Boolean to a key.
double	getDouble(String key)	Resolves a double to a key.
double	getDouble(String key, double defaultValue)	Resolves a double to a key.
int	getInt(String key)	Resolves an int to a key.
int	getInt(String key, int defaultValue)	Resolves an int to a key.
long	getLong(String key)	Resolves a long to a key.
long	getLong(String key, long defaultValue)	Resolves a long to a key.
DataObject	getObject(String key)	Resolves a DataObject to a key.
String	getString(String key)	Resolves a String to a key.
String	getString(String key, String defaultValue)	Resolves a String to a key.
int	getUnsignedInt(String key)	Resolves an unsigned int to a key.
int	getUnsignedInt(String key, int defaultValue)	Resolves an unsigned int to a key.
long	getUnsignedLong(String key)	Resolves an unsigned long to a key.
long	getUnsignedLong(String key, long defaultValue)	Resolves an unsigned long to a key.
boolean	hasKey(String key)	Whether the specified key is present.
boolean	isNull(String key)	Whether the specified key is missing or null
boolean	isType(String key, DataType type)	Whether the specified key is of the specified type.
Set<String>	keys()	Set of all keys in this DataObject.
Optional<Object>	opt(String key)	Resolves any type to the provided key.
Optional<DataArray>	optArray(String key)	Resolves a DataArray to a key.
Optional<DataObject>	optObject(String key)	Resolves a DataObject to a key.
DataObject	put(String key, Object value)	Upserts a new value for the provided key.
DataObject	putNull(String key)	Upserts a null value for the provided key.
DataObject	remove(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.
Map<String,Object>	toMap()	Converts this DataObject to a Map
String	toPrettyString()
String	toString()
Collection<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
                                  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:

DataType.isType(Object)

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:

opt(String)

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

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

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