API данных
Предупреждение
Эти документы были написаны для SpongeAPI 7 и, вероятно, устаревшие. Если вы чувствуете, что вы можете помочь обновить их, пожалуйста, отправьте PR!
Единый API данных стремится обеспечить последовательный способ доступа и изменения данных. «Данные» в этом контексте означает любые данные, последовательно синхронизированные между клиентом и сервером. Они могут быть изменены на стороне сервера, и после этого будут синхронизированы с клиентами. Понятие «Данные» включает в себя, среди многих других, текст на табличке, внешний вид лошади лошади или здоровье любого живого существа.
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.
Совет
If the data API behaves differently from what you expect (e.g. returns an empty Optional even if the data are
supposed to be present), or there is a feature/value missing that you need, check the Implementation Tracker, ask in the #spongedev IRC channel,
in the #dev Discord channel, or on the Forums.
Концепты
На первый взгляд в документацию, API данных угрожает ошеломить вас с большим количеством интерфейсов и пакетов. Но просто используя API данных, вам не придется иметь дело со многими из них, ведь большинство интерфейсов - это только определенные манипуляторы данных.
Хранитель данных
Хранитель данных - это что - то, хранящее данные. Он предоставляет методы для извлечения и возврата данных. Сам интерфейс полностью не обращает внимания на тип данных. Поскольку этим знанием будет обладать только реализация, можно просить :javadoc: «DataHolder» предоставить данные, которых он не имеет или принимать данные, которые он не может использовать. В этих случаях возвращаемые значения методов будет предоставлять информацию, что данные не доступны (через „“ Optional.empty()““) или не приняты (через :doc: «DataTransactionResult <transactions>»).
Параметр
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 abilities on tools (represented as HarvestingProperty or the damage absorption of an equipable armor item (represented as DamageAbsorptionProperty).
Манипулятор данными
Манипулятор данных представляет точки данных, описывающих определенный компонент его обладателя. Например :javadoc: «HealthData», который содержит текущее и максимальное здоровье. Если владелец данных имеет „“ HealthData““, он имеет здоровье, которое может как-то уменьшаться, и умрёт, если здоровье полностью исчерпается. Это позволяет повторно использовать такие компоненты через API и предотвращает дублирование методов доступа. Например овца, блоки стекла и кожаные доспехи могут обмениваться :javadoc: «DyeableData», имеющими цвет, в который они окрашены.
Ключ
„“ Ключ „“ — это уникальный идентификатор для одной точки данных и может использоваться чтобы напрямую считывать или устанавливать точку данных, не беспокоясь о данных манипуляторов. Он был разработан для предоставления удобного доступа к данным и похож на методы getter/setter. Все ключи, используемые в Sponge, перечислены как константы в классе Keys.
Значение
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.
