Upstream/Paper
1
0
Fork 0
mirror of https://github.com/PaperMC/Paper.git synced 2025-04-09 13:35:49 +02:00
Code Issues Projects Releases Wiki Activity

#936: Add new PersistentDataContainer methods and clean up docs

Browse Source 
By: Jishuna <joshl5324@gmail.com>
This commit is contained in:
Bukkit/Spigot 2023-12-08 19:29:36 +11:00
parent 460ea2aff9
commit 0a2fdbe9ff
1 changed files with 58 additions and 25 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

83
paper-api/src/main/java/org/bukkit/persistence/PersistentDataContainer.java
View File

@ -21,15 +21,15 @@ public interface PersistentDataContainer {
* *
* @param key the key this value will be stored under * @param key the key this value will be stored under
* @param type the type this tag uses * @param type the type this tag uses
* @param value the value stored in the tag * @param value the value to store in the tag
* @param <T> the generic java type of the tag value * @param <T> the generic java type of the tag value
* @param <Z> the generic type of the object to store * @param <Z> the generic type of the object to store
* *
* @throws NullPointerException if the key is null * @throws IllegalArgumentException if the key is null
* @throws NullPointerException if the type is null * @throws IllegalArgumentException if the type is null
* @throws NullPointerException if the value is null. Removing a tag should * @throws IllegalArgumentException if the value is null. Removing a tag should
* be done using {@link #remove(NamespacedKey)} * be done using {@link #remove(NamespacedKey)}
* @throws IllegalArgumentException if no suitable adapter will be found for * @throws IllegalArgumentException if no suitable adapter was found for
* the {@link PersistentDataType#getPrimitiveType()} * the {@link PersistentDataType#getPrimitiveType()}
*/ */
<T, Z> void set(@NotNull NamespacedKey key, @NotNull PersistentDataType<T, Z> type, @NotNull Z value); <T, Z> void set(@NotNull NamespacedKey key, @NotNull PersistentDataType<T, Z> type, @NotNull Z value);
@ -38,7 +38,7 @@ public interface PersistentDataContainer {
* Returns if the persistent metadata provider has metadata registered * Returns if the persistent metadata provider has metadata registered
* matching the provided parameters. * matching the provided parameters.
* <p> * <p>
* This method will only return if the found value has the same primitive * This method will only return true if the found value has the same primitive
* data type as the provided key. * data type as the provided key.
* <p> * <p>
* Storing a value using a custom {@link PersistentDataType} implementation * Storing a value using a custom {@link PersistentDataType} implementation
@ -49,22 +49,41 @@ public interface PersistentDataContainer {
* bytes long. * bytes long.
* <p> * <p>
* This method is only usable for custom object keys. Overwriting existing * This method is only usable for custom object keys. Overwriting existing
* tags, like the the display name, will not work as the values are stored * tags, like the display name, will not work as the values are stored
* using your namespace. * using your namespace.
* *
* @param key the key the value is stored under * @param key the key the value is stored under
* @param type the type which primitive storage type has to match the value * @param type the type the primative stored value has to match
* @param <T> the generic type of the stored primitive * @param <T> the generic type of the stored primitive
* @param <Z> the generic type of the eventually created complex object * @param <Z> the generic type of the eventually created complex object
* *
* @return if a value * @return if a value with the provided key and type exists
* *
* @throws NullPointerException if the key to look up is null * @throws IllegalArgumentException if the key to look up is null
* @throws NullPointerException if the type to cast the found object to is * @throws IllegalArgumentException if the type to cast the found object to is
* null * null
*/ */
<T, Z> boolean has(@NotNull NamespacedKey key, @NotNull PersistentDataType<T, Z> type); <T, Z> boolean has(@NotNull NamespacedKey key, @NotNull PersistentDataType<T, Z> type);
/**
* Returns if the persistent metadata provider has metadata registered matching
* the provided parameters.
* <p>
* This method will return true as long as a value with the given key exists,
* regardless of its type.
* <p>
* 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.
*
* @param key the key the value is stored under
*
* @return if a value with the provided key exists
*
* @throws IllegalArgumentException if the key to look up is null
*/
boolean has(@NotNull NamespacedKey key);
/** /**
* Returns the metadata value that is stored on the * Returns the metadata value that is stored on the
* {@link PersistentDataHolder} instance. * {@link PersistentDataHolder} instance.
@ -77,12 +96,12 @@ public interface PersistentDataContainer {
* @return the value or {@code null} if no value was mapped under the given * @return the value or {@code null} if no value was mapped under the given
* value * value
* *
* @throws NullPointerException if the key to look up is null * @throws IllegalArgumentException if the key to look up is null
* @throws NullPointerException if the type to cast the found object to is * @throws IllegalArgumentException if the type to cast the found object to is
* null * null
* @throws IllegalArgumentException if the value exists under the given key, * @throws IllegalArgumentException if a value exists under the given key,
* but cannot be access using the given type * but cannot be accessed using the given type
* @throws IllegalArgumentException if no suitable adapter will be found for * @throws IllegalArgumentException if no suitable adapter was found for
* the {@link * the {@link
* PersistentDataType#getPrimitiveType()} * PersistentDataType#getPrimitiveType()}
*/ */
@ -102,21 +121,21 @@ public interface PersistentDataContainer {
* @param <Z> the generic type of the eventually created complex object * @param <Z> the generic type of the eventually created complex object
* *
* @return the value or the default value if no value was mapped under the * @return the value or the default value if no value was mapped under the
* given value * given key
* *
* @throws NullPointerException if the key to look up is null * @throws IllegalArgumentException if the key to look up is null
* @throws NullPointerException if the type to cast the found object to is * @throws IllegalArgumentException if the type to cast the found object to is
* null * null
* @throws IllegalArgumentException if the value exists under the given key, * @throws IllegalArgumentException if a value exists under the given key,
* but cannot be access using the given type * but cannot be accessed using the given type
* @throws IllegalArgumentException if no suitable adapter will be found for * @throws IllegalArgumentException if no suitable adapter was found for
* the {@link PersistentDataType#getPrimitiveType()} * the {@link PersistentDataType#getPrimitiveType()}
*/ */
@NotNull @NotNull
<T, Z> Z getOrDefault(@NotNull NamespacedKey key, @NotNull PersistentDataType<T, Z> type, @NotNull Z defaultValue); <T, Z> Z getOrDefault(@NotNull NamespacedKey key, @NotNull PersistentDataType<T, Z> type, @NotNull Z defaultValue);
/** /**
* Get a set of keys present on this {@link PersistentDataContainer} * Get the set of keys present on this {@link PersistentDataContainer}
* instance. * instance.
* *
* Any changes made to the returned set will not be reflected on the * Any changes made to the returned set will not be reflected on the
@ -130,9 +149,9 @@ public interface PersistentDataContainer {
/** /**
* Removes a custom key from the {@link PersistentDataHolder} instance. * Removes a custom key from the {@link PersistentDataHolder} instance.
* *
* @param key the key * @param key the key to remove
* *
* @throws NullPointerException if the provided key is null * @throws IllegalArgumentException if the provided key is null
*/ */
void remove(@NotNull NamespacedKey key); void remove(@NotNull NamespacedKey key);
@ -144,6 +163,20 @@ public interface PersistentDataContainer {
*/ */
boolean isEmpty(); boolean isEmpty();
/**
* Copies all values from this {@link PersistentDataContainer} to the provided
* container.
* <p>
* 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.
*
* @param other the container to copy to
* @param replace whether to replace any matching values in the target container
*
* @throws IllegalArgumentException if the other container is null
*/
void copyTo(@NotNull PersistentDataContainer other, boolean replace);
/** /**
* Returns the adapter context this tag container uses. * Returns the adapter context this tag container uses.
* *