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.
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 applicable potion effects on tools (represented as Keys#APPLICABLE_POTION_EFFECTS or the damage absorption of an equipable armor item (represented as Keys#ABSORPTION).
Manipulador de Datos
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.
Clave
A Key is a unique identifier for a single point of data and can be used to directly read or set that point of
data without worrying about data manipulators. It was designed to provide a way of accessing data
similar to direct getter/setter methods. All keys used within Sponge are listed as constants in the
Keys utility class.
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.
