Data API and things arroud it


#1

Hello, Im completly new on Sponge and Im trying to understand the Data API, the docs arent helping me about it :c

Well, how many classes I need to store a MyData class on a Dataholder? three? four?

What does a MyDataImpl.class should do?
What does a MyDataImmutable.class should do?
What does a MyData.class should do?
What does a MyDataBuilder.class should do?

Thanks everyone o/


#2

MyData is your data manipulator.
MyDataImmutable is an immutable data manipulator that gets used when snapshots of entities / tileentities are created.
MyDataImpl sounds like it’s the actual implementation of the data manipulator, but you only need this if the MyData is an API/interface

MyDataBuilder I’m going to refer to the JavaDocs for AbstractDataBuilder because I don’t know off the top of my head.

 An abstract implementation of {@link DataBuilder} that pre-defines all of
 * the necessary "content update" implementation required for content
 * versioning. Note that the builder itself is versioned to ensure that
 * content versioning is appropriately handled. It is highly recommended to
 * extend this class to implement {@link DataManipulatorBuilder} and implement
 * {@link DataContentUpdater}s as necessary for future upgradeability of
 * custom content.

#3

To create custom data for your plugin, you need three classes per data ‘set’. A DataManipulator, which stores data for mutable constructs; an ImmutableDataManipulator, which stores data for immutable constructs, and a DataManipulatorBuilder, which is responsible for creating the DataManipulator from existing raw data. You can also use interfaces for the public API, which extends it out to 5 classes total. For convenience, it is recommended to extend from AbstractData, AbstractImmutableData, and AbstractDataBuilder in your classes. If you are only using a single data type, it becomes easier to use AbstractSingleData, and further easier if you’re using a simple one in which case you could use for example AbstractBooleanData.
All the methods must be implemented, and if you want it to be persisted across saves, you also need to override toContainer() in the manipulators to add your data.