API данных
Единый API данных стремится обеспечить последовательный способ доступа и изменения данных. «Данные» в этом контексте означает любые данные, последовательно синхронизированные между клиентом и сервером. Они могут быть изменены на стороне сервера, и после этого будут синхронизированы с клиентами. Понятие «Данные» включает в себя, среди многих других, текст на табличке, внешний вид лошади лошади или здоровье любого живого существа.
Там, где другие подходы определения имеющихся данных, используют интерфейсы и наследование (например, интерфейс „“ LivingEntity““ предоставляет функции get и Set для получения текущего и максимального здоровья), в Sponge каждое существо, блок и т.д. совсем не знает, какие данные оно держит. Хотя это может показаться не таким очевидным, как методы прямого доступа, это делает всё гораздо более расширяемым. И благодаря добавлению ключей(:javadoc: „Key“), простой доступ к конкретным значениям не менее очевиден.
Предупреждение
На момент написания, Data API ещё не полностью реализован. Обратитесь к Трекеру реализации, спросите в IRC-канале #spongedev или на форумах, чтобы узнать, доступны ли данные, с которыми Вам необходимо работать.
Концепты
На первый взгляд в документацию, API данных угрожает ошеломить вас с большим количеством интерфейсов и пакетов. Но просто используя API данных, вам не придется иметь дело со многими из них, ведь большинство интерфейсов - это только определенные манипуляторы данных.
Хранитель данных
Хранитель данных - это что - то, хранящее данные. Он предоставляет методы для извлечения и возврата данных. Сам интерфейс полностью не обращает внимания на тип данных. Поскольку этим знанием будет обладать только реализация, можно просить :javadoc: «DataHolder» предоставить данные, которых он не имеет или принимать данные, которые он не может использовать. В этих случаях возвращаемые значения методов будет предоставлять информацию, что данные не доступны (через „“ Optional.empty()““) или не приняты (через :doc: «DataTransactionResult <transactions>»).
Параметр
Свойства также данные, но не синхронизированные между сервером и клиентами. Таким образом они могут быть изменены только модами, которые есть и на клиентах, и на сервере. Так как Sponge не предназначен для наличия клиентской части, свойства не являются изменяемыми. Примерами свойств являются возможности сбора на инструментах (в виде :javadoc: «HarvestingProperty») или поглощение урона бронёй (в виде :javadoc: «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.
