API Danych
The unified Data API aims to provide a consistent way of accessing and modifying data. «Data», in this context means any data that is consistently synchronized between client and server. It can be changed server-side and then those changes will be synchronized to the connected clients. This includes, among many others, the text on a sign, the looks of a horse or the health of any living entity.
Where other approaches define the available data using interfaces and inheritance (like a LivingEntity
interface providing getter and setter functions for current and maximum health), in Sponge every entity, block
etc. is completely oblivious to what data it holds. While this may appear less straightforward than direct
accessor methods, it is foremost far more extensible. And thanks to the addition of Keys, simply accessing
specific values is no less straightforward.
Ostrzeżenie
As of writing, a few parts of the Data API are not implemented. If you are trying to access an API and are receiving
an empty Optional when one is not expected, refer to the Implementation Tracker, ask in the #spongedev IRC channel or on the
Forums to find out if the data you need to work with is available yet.
Koncepcje
Na pierwszy rzut oka w dokumentach API, dane API grożą przytłoczeniem cię mnóstwem interfejsów i pakietów. Jednak, aby po prostu użyć danych API, nie będziesz musiał przejmować się wieloma z nich, gdyż większość interfejsów znajduje się tylko w określonych manipulatorach danych.
DataHolder
A data holder is just that - something that holds data. It provides methods to retrieve and offer back data. The
interface itself is completely oblivious to the type of data held. Since only the implementations will possess
this knowledge, it is possible to ask a DataHolder to provide data it does not have or to accept data it
cannot use. In those cases, the return values of the methods will provide the information that data is not available
(via Optional.empty()) or not accepted (via the DataTransactionResult).
Własność
A property too is data, but not synchronized between server and clients. Therefore, it can only be changed by modifications present on both client and server. Since Sponge is not intended to require a client-side counterpart, properties are not modifiable. Examples of properties are the harvesting ablities on tools (represented as HarvestingProperty or the damage absorption of an equippable armor item (represented as DamageAbsorptionProperty).
DataManipulator
A data manipulator represents points of cohesive data that describes a certain component of its holder. For
example HealthData, which contains both current and maximum health. If a data holder has HealthData, it
has health that can somehow be depleted and replenished and can die if that health is depleted. This allows for the
re-use of such components over the API and prevents duplication of accessor methods. For example, sheep, stained glass
blocks and leather armor all can share the DyeableData holding the color they are dyed in.
Klucz
Klucz jest unikalnym identyfikatorem dla pojedyńczego punktu danych i może zostać użyty do bezpośredniego odczytania lub może ustawić ten punkt danych bez zmartwień o manipulatorów danych. Został stworzony aby zapewnić wygodny dostęp do danych podobny do bezpośrednich metod getter/setter. Wszystkie klucze używane w Sponge są katalogwane jako stałe w klasie Keys :javadoc.
Wartość
Within the Data API, a value referred to by a Key is encoded in a container object. For this documentation,
it is referred to as «keyed value» to avoid confusion with the actual value. A keyed value encapsulates the
actual data value (if it is present), a default value (to be used if no direct value is present) and the Key by
which the value is identified.
