From 2cf008bf3df8abab6ab431bc8fb37070cc84ce2c Mon Sep 17 00:00:00 2001 From: Lignium Date: Tue, 5 Sep 2023 19:20:20 +0300 Subject: [PATCH] Add SerializableDataHolder#rawData() method --- .../block/entity/BlockEntityArchetype.java | 6 ++- .../api/data/SerializableDataHolder.java | 43 +++++++++++++------ .../api/entity/EntityArchetype.java | 6 ++- 3 files changed, 41 insertions(+), 14 deletions(-) diff --git a/src/main/java/org/spongepowered/api/block/entity/BlockEntityArchetype.java b/src/main/java/org/spongepowered/api/block/entity/BlockEntityArchetype.java index 4f758c46a5..00e3844fd3 100644 --- a/src/main/java/org/spongepowered/api/block/entity/BlockEntityArchetype.java +++ b/src/main/java/org/spongepowered/api/block/entity/BlockEntityArchetype.java @@ -84,8 +84,12 @@ static Builder builder() { * * * @return The copied container of the block entity + * @deprecated Use unified {@link BlockEntityArchetype#rawData()} */ - DataContainer blockEntityData(); + @Deprecated + default DataContainer blockEntityData() { + return rawData(); + } /** * Sets the raw data for the desired {@link BlockEntity}. Note that position diff --git a/src/main/java/org/spongepowered/api/data/SerializableDataHolder.java b/src/main/java/org/spongepowered/api/data/SerializableDataHolder.java index 8279542058..8391700948 100644 --- a/src/main/java/org/spongepowered/api/data/SerializableDataHolder.java +++ b/src/main/java/org/spongepowered/api/data/SerializableDataHolder.java @@ -36,6 +36,25 @@ */ public interface SerializableDataHolder extends DataSerializable, CopyableDataHolder { + /** + * Returns the raw extra data of this {@link SerializableDataHolder}. + * + *

The format of the {@link DataView}'s contained data is dependent on the type + * of {@link DataHolder.Mutable} this is. In some cases, the format is specified + * based on a more specific type, such as for {@link EntityType}s, or + * {@link ItemType}s.

+ *

The data can be modified and set back using + * {@link Mutable#setRawData(DataView)} or {@link Immutable#withRawData(DataView)} + * methods.

+ *

Warning: Be aware of the safety mode of the returned container. + * The container may contain mutable values, such as arrays, that may not be + * cloned, and thus changing them may inadvertently change the internal state + * of the {@link DataHolder}.

+ * + * @return The raw data + */ + DataContainer rawData(); + /** * Validates the container with known data required to set the raw data to * this {@link SerializableDataHolder}. If the container is incomplete or contains @@ -58,12 +77,11 @@ interface Mutable extends SerializableDataHolder, DataHolder.Mutable { /** * Attempts to set all data of this {@link DataHolder} according to the - * {@link DataView}'s held information. Using this to modify known to be - * {@link Key}s provided dynamically through {@link DataProvider}s is - * unsupported. The format of the {@link DataView}'s contained data is - * dependent on the type of {@link DataHolder.Mutable} this is. In some cases, the - * format is specified based on a more specific type, such as for - * {@link EntityType}s, or {@link ItemType}s. + * {@link DataView}'s held information. Using this to modify unknown data + * that is not supported by Data API. The format of the {@link DataView}'s + * contained data is dependent on the type of {@link DataHolder.Mutable} + * this is. In some cases, the format is specified based on a more specific + * type, such as for {@link EntityType}s, or {@link ItemType}s. * *

This setter is used to provide setting custom data that is not * represented by the Data API, including forge mods and other @@ -77,6 +95,7 @@ interface Mutable extends SerializableDataHolder, DataHolder.Mutable { * data holder * @throws InvalidDataException If the container is missing or has invalid * data that this holder will refuse + * @see SerializableDataHolder#rawData() */ void setRawData(DataView container) throws InvalidDataException; @@ -88,12 +107,11 @@ interface Immutable> extends SerializableDataHolder, Data /** * Attempts to set all data of this {@link DataHolder} according to the - * {@link DataView}'s held information. Using this to modify known to be - * {@link Key}s provided dynamically through {@link DataProvider}s is - * unsupported. The format of the {@link DataView}'s contained data is - * dependent on the type of {@link DataHolder.Mutable} this is. In some cases, the - * format is specified based on a more specific type, such as for - * {@link EntityType}s, or {@link ItemType}s. + * {@link DataView}'s held information. Using this to modify unknown data + * that is not supported by Data API. The format of the {@link DataView}'s + * contained data is dependent on the type of {@link DataHolder.Immutable} + * this is. In some cases, the format is specified based on a more specific + * type, such as for {@link EntityType}s, or {@link ItemType}s. * *

This setter is used to provide setting custom data that is not * represented by the Data API, including forge mods and other @@ -108,6 +126,7 @@ interface Immutable> extends SerializableDataHolder, Data * @return The new immutable data holder containing the raw data * @throws InvalidDataException If the container is missing or has invalid * data that this holder will refuse + * @see SerializableDataHolder#rawData() */ I withRawData(DataView container) throws InvalidDataException; diff --git a/src/main/java/org/spongepowered/api/entity/EntityArchetype.java b/src/main/java/org/spongepowered/api/entity/EntityArchetype.java index a3885f739f..fdfb485430 100644 --- a/src/main/java/org/spongepowered/api/entity/EntityArchetype.java +++ b/src/main/java/org/spongepowered/api/entity/EntityArchetype.java @@ -71,8 +71,12 @@ static EntityArchetype of(EntityType type) { *

* * @return The copied container of the entity + * @deprecated Use unified {@link EntityArchetype#rawData()} */ - DataContainer entityData(); + @Deprecated + default DataContainer entityData() { + return rawData(); + } @Override void setRawData(DataView container) throws InvalidDataException;