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.
Donde otros enfoques definen los datos mediante interfaces y herencia (como una LivingEntity la interfaz proporciona funciones getter y setter para la salud actual y máxima), en Sponge cada entidad, bloque etc. es completamente ajeno a que datos posee. Si bien esto puede parecer menos sencillo que los métodos de acceso directo, es mucho más extensible. Y gracias a la adición de :javadoc: “Key” s, el simple acceso a valores específicos no es menos directo.
Advertencia
En cuanto a la escritura, algunas partes de la API de datos no son implementadas. Si estás intentando acceder a una API y recibes un Optional vació inesperado, dirígete a Implementation Tracker, pregunta en el canal IRC #spongedev o en los Forums para saber si los datos con los que necesitas trabajar están disponibles todavía.
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
Una propiedad también es data, pero no sincronizada entre el servidor y los clientes. Por lo tanto, sólo puede ser cambiada por modificaciones presentes en ambos, cliente y servidor. Ya que Sponge no pretende exigir a una contraparte del lado del cliente, las propiedades no son modificables. Algunos ejemplos de propiedades son las recolecciones de habilidades en las herramientas (representadas como :javadoc: “HarvestingProperty” o la absorción de daño de un artículo de armadura equipable (representado como :javadoc: “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.
