La API de Datos
La API unificada de datos tiene como objetivo proporcionar una forma consistente de acceso y modificación de datos. “Datos”, en este contexto significa cualquier dato que sea constantemente sincronizado entre el cliente y el servidor. Puede ser cambiado desde el lado del servidor y luego esos cambios serán sincronizados a los clientes conectados. Esto incluye, entre muchos otros, el texto de un signo, el aspecto de un caballo o la salud de cualquier entidad viva.
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.
Truco
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.
Conceptos
A primera vista en la documentación de la API, la API de datos amenaza con abrumar con un montón de paquetes e interfaces. Pero para usar simplemente los datos API, no tendrás que lidiar con mucho eso, ya que la mayoría de las interfaces allí encontradas son solo manipuladores de datos específicos.
CatalogTypes
Catalog Types are groups of values that can be used in certain context. Famous examples of these types are BlockTypes, EntityTypes and ItemTypes.
DataHolder
Un contenedor de datos es justamente eso - algo que contiene datos. Provee métodos para buscar y recobrar información. La interfaz misma es completamente independiente de los datos almacenados. Ya que sólo las implementaciones tendrán este conocimiento, es posible pedirle a un DataHolder que provea información que no posee o que acepte información que no puede usar. En esos casos, los valores de retorno de los métodos, informarán que esos datos no están disponibles (a través de Optional.empty()) o que no fueron aceptados (a través de DataTransactionResult).
Propiedad
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).
Manipulador de Datos
Un manipulador de datos representa los puntos cohesivos de datos que describen un cierto componente de su titular. Por ejemplo :javadoc: “HealthData”, que contiene la salud actual y máxima. Si un titular de los datos tiene HealthData, tiene salud que de alguna manera puede ser agotada y recargada y puede morir si la salud se agota. Esto permite la reutilización de estos componentes sobre la API y evita la duplicación de los métodos de descriptor de acceso. Por ejemplo, ovejas, bloques de vidrio y armaduras de cuero pueden compartir el :javadoc: “DyeableData” que posee el color con el que están teñidos.
Clave
Una Key es un identificador único para un único punto de datos y puede utilizarse directamente o establecer ese punto de datos sin preocuparse por manipuladores de datos. Fue diseñado para proporcionar una manera conveniente de acceder a datos similares a los métodos getter/setter directos. Todas las claves usadas en Sponge aparecen como constantes en la clase de utilidad de :javadoc: “Keys”.
Valor
Dentro de la API de Datos, un valor referido por una Key esta codificado por un objeto contenedor. Para esta documentación, se le refiere como “keyed value” para evitar confusiones con el valor actual. Un valor encriptado encapsula el valor real de los datos (si está presente), un valor por defecto (a ser usado si no hay ningún valor directo presente) y la Clave por la que el valor es identificado.
