Package org.bukkit.persistence

Interface PersistentDataContainer

public interface PersistentDataContainer

This interface represents a map like object, capable of storing custom tags in it.

Method Summary

Modifier and Type	Method	Description
void	copyTo(@NotNull PersistentDataContainer other, boolean replace)	Copies all values from this PersistentDataContainer to the provided container.
<P, C> C	get(@NotNull NamespacedKey key, @NotNull PersistentDataType<P,C> type)	Returns the metadata value that is stored on the PersistentDataHolder instance.
@NotNull PersistentDataAdapterContext	getAdapterContext()	Returns the adapter context this tag container uses.
@NotNull Set<NamespacedKey>	getKeys()	Get the set of keys present on this PersistentDataContainer instance.
<P, C> C	getOrDefault(@NotNull NamespacedKey key, @NotNull PersistentDataType<P,C> type, C defaultValue)	Returns the metadata value that is stored on the PersistentDataHolder instance.
boolean	has(@NotNull NamespacedKey key)	Returns if the persistent metadata provider has metadata registered matching the provided parameters.
<P, C> boolean	has(@NotNull NamespacedKey key, @NotNull PersistentDataType<P,C> type)	Returns if the persistent metadata provider has metadata registered matching the provided parameters.
boolean	isEmpty()	Returns if the container instance is empty, therefore has no entries inside it.
default void	readFromBytes(byte @NotNull [] bytes)	Read values from a serialised byte array into this PersistentDataContainer instance.
void	readFromBytes(byte @NotNull [] bytes, boolean clear)	Read values from a serialised byte array into this PersistentDataContainer instance.
void	remove(@NotNull NamespacedKey key)	Removes a custom key from the PersistentDataHolder instance.
byte @NotNull []	serializeToBytes()	Serialize this PersistentDataContainer instance to a byte array.
<P, C> void	set(@NotNull NamespacedKey key, @NotNull PersistentDataType<P,C> type, C value)	Stores a metadata value on the PersistentDataHolder instance.

Method Details

set

<P,
C> void set(@NotNull
 @NotNull NamespacedKey key,
 @NotNull
 @NotNull PersistentDataType<P,C> type,
 @NotNull
 C value)

Stores a metadata value on the PersistentDataHolder instance.

This API cannot be used to manipulate minecraft data, as the values will be stored using your namespace. This method will override any existing value the PersistentDataHolder may have stored under the provided key.

Type Parameters:

P - the generic java type of the tag value

C - the generic type of the object to store

Parameters:

key - the key this value will be stored under

type - the type this tag uses

value - the value to store in the tag

Throws:

IllegalArgumentException - if the key is null

IllegalArgumentException - if the type is null

IllegalArgumentException - if the value is null. Removing a tag should be done using remove(NamespacedKey)

IllegalArgumentException - if no suitable adapter was found for the PersistentDataType.getPrimitiveType()

has

<P,
C> boolean has(@NotNull
 @NotNull NamespacedKey key,
 @NotNull
 @NotNull PersistentDataType<P,C> type)

Returns if the persistent metadata provider has metadata registered matching the provided parameters.

This method will only return true if the found value has the same primitive data type as the provided key.

Storing a value using a custom PersistentDataType implementation will not store the complex data type. Therefore storing a UUID (by storing a byte[]) will match has("key" , PersistentDataType.BYTE_ARRAY). Likewise a stored byte[] will always match your UUID PersistentDataType even if it is not 16 bytes long.

This method is only usable for custom object keys. Overwriting existing tags, like the display name, will not work as the values are stored using your namespace.

Type Parameters:

P - the generic type of the stored primitive

C - the generic type of the eventually created complex object

Parameters:

key - the key the value is stored under

type - the type the primative stored value has to match

Returns:

if a value with the provided key and type exists

Throws:

IllegalArgumentException - if the key to look up is null

IllegalArgumentException - if the type to cast the found object to is null

has

boolean has(@NotNull
 @NotNull NamespacedKey key)

Returns if the persistent metadata provider has metadata registered matching the provided parameters.

This method will return true as long as a value with the given key exists, regardless of its type.

This method is only usable for custom object keys. Overwriting existing tags, like the display name, will not work as the values are stored using your namespace.

Parameters:

key - the key the value is stored under

Returns:

if a value with the provided key exists

Throws:

IllegalArgumentException - if the key to look up is null

get

@Nullable
<P,
C> C get(@NotNull
 @NotNull NamespacedKey key,
 @NotNull
 @NotNull PersistentDataType<P,C> type)

Returns the metadata value that is stored on the PersistentDataHolder instance.

Type Parameters:

P - the generic type of the stored primitive

C - the generic type of the eventually created complex object

Parameters:

key - the key to look up in the custom tag map

type - the type the value must have and will be casted to

Returns:

the value or null if no value was mapped under the given value

Throws:

IllegalArgumentException - if the key to look up is null

IllegalArgumentException - if the type to cast the found object to is null

IllegalArgumentException - if a value exists under the given key, but cannot be accessed using the given type

IllegalArgumentException - if no suitable adapter was found for the PersistentDataType.getPrimitiveType()

getOrDefault

@NotNull
<P,
C> C getOrDefault(@NotNull
 @NotNull NamespacedKey key,
 @NotNull
 @NotNull PersistentDataType<P,C> type,
 @NotNull
 C defaultValue)

Returns the metadata value that is stored on the PersistentDataHolder instance. If the value does not exist in the container, the default value provided is returned.

Type Parameters:

P - the generic type of the stored primitive

C - the generic type of the eventually created complex object

Parameters:

key - the key to look up in the custom tag map

type - the type the value must have and will be casted to

defaultValue - the default value to return if no value was found for the provided key

Returns:

the value or the default value if no value was mapped under the given key

Throws:

IllegalArgumentException - if the key to look up is null

IllegalArgumentException - if the type to cast the found object to is null

IllegalArgumentException - if a value exists under the given key, but cannot be accessed using the given type

IllegalArgumentException - if no suitable adapter was found for the PersistentDataType.getPrimitiveType()

getKeys

@NotNull
@NotNull Set<NamespacedKey> getKeys()

Get the set of keys present on this PersistentDataContainer instance. Any changes made to the returned set will not be reflected on the instance.

Returns:

the key set

remove

void remove(@NotNull
 @NotNull NamespacedKey key)

Removes a custom key from the PersistentDataHolder instance.

Parameters:

key - the key to remove

Throws:

IllegalArgumentException - if the provided key is null

isEmpty

boolean isEmpty()

Returns if the container instance is empty, therefore has no entries inside it.

Returns:

the boolean

copyTo

void copyTo(@NotNull
 @NotNull PersistentDataContainer other,
 boolean replace)

Copies all values from this PersistentDataContainer to the provided container.

This method only copies custom object keys. Existing tags, like the display name, will not be copied as the values are stored using your namespace.

Parameters:

other - the container to copy to

replace - whether to replace any matching values in the target container

Throws:

IllegalArgumentException - if the other container is null

getAdapterContext

@NotNull
@NotNull PersistentDataAdapterContext getAdapterContext()

Returns the adapter context this tag container uses.

Returns:

the tag context

serializeToBytes

byte @NotNull [] serializeToBytes()
                           throws IOException

Serialize this PersistentDataContainer instance to a byte array.

Returns:

a binary representation of this container

Throws:

IOException - if we fail to write this container to a byte array

readFromBytes

void readFromBytes(byte @NotNull [] bytes,
 boolean clear)
            throws IOException

Read values from a serialised byte array into this PersistentDataContainer instance.

Parameters:

bytes - the byte array to read from

clear - if true, this PersistentDataContainer instance will be cleared before reading

Throws:

IOException - if the byte array has an invalid format

readFromBytes

default void readFromBytes(byte @NotNull [] bytes)
                    throws IOException

Read values from a serialised byte array into this PersistentDataContainer instance. This method has the same effect as PersistentDataContainer#readFromBytes(bytes, true)

Parameters:

bytes - the byte array to read from

Throws:

IOException - if the byte array has an invalid format