La Data API
La Data API cherche à offrir une façon efficace d’avoir accès à des données et à les modifier. Celles-ci, dans ce contexte, peuvent représenter toute information synchronisée entre le client et le serveur. Elle peut être modifiée côté serveur de manière à ce que les changements effectués soient également pris en compte côté client. Cela inclut, parmi d’autres choses, le texte d’un panneau, l’apparence d’un cheval ou la vie d’une entité.
Là où les autres approchent définissent les données disponibles en utilisant les interfaces et l’héritage (comme une interface LivingEntity fournissant des méthodes getter et setter pour la santé actuelle et maximale), dans Sponge toutes les entités, blocs, etc… sont complètement inconscients de quelles données ils détiennent. Bien que cela puisse sembler moins aisé que les méthodes d’accesseurs directs, c’est avant tout beaucoup plus extensible. Et grâce à l’ajout de Keys, accéder simplement à des valeurs spécifiques n’est pas moins simple.
Astuce
Si la Data API se comporte différemment de ce à quoi vous vous attendez (ex : elle retourne un Optional vide alors que les données sont censées être présentes), ou qu’il y a une fonctionnalité/valeur manquante dont vous avez besoin, vérifiez l”Implementation Tracker, demandez dans le canal IRC #spongedev, le canal Discord #dev ou sur les Forums.
Concepts
Au premier coup d’oeil à la documentation de l’API, la Data API risque de vous accabler avec beaucoup d’interfaces et de packages. Mais pour utiliser la Data API simplement, vous n’aurez pas à faire face à bon nombre d’entre eux, puisque la plupart des interfaces sont juste des data manipulators spécifiques.
CatalogTypes
Les Catalog Types sont des groupes de valeurs qui peuvent être utilisés dans certains contextes. De célèbres exemples de ces types sont BlockTypes, EntityTypes et ItemTypes.
DataHolder
Un data holder est simplement quelque chose qui contient des données. Il fournit des méthodes permettant de récupérer et de retourner ces données. L’interface, en soi, est complètement indépendante du type des données enregistrées. Puisque seules les implémentations auront cette information, il est possible de demander à un DataHolder de fournir des données qu’il ne possède pas, ou d’accepter des données qu’il ne peut pas utiliser. Dans ces cas, la valeur retournée par ces méthodes fournira l’information Optional.empty() (information non disponible), ou information non acceptée (DataTransactionResult).
Propriété
Une propriété est aussi une donnée, mais pas synchronisée entre le serveur et les clients. Par conséquent, elle peut seulement être changée par des modifications présentes sur le client et le serveur. Puisque Sponge n’est pas destiné à exiger un équivalent du côté client, les propriétés ne sont pas modifiables. Des exemples de propriétés sont les capacités de récolte sur les outils (représenté par HarvestingProperty) ou l’absorption de dégâts d’un élément d’armure équipable (représenté par DamageAbsorptionProperty).
Manipulateur de données
Un data manipulator représente des points de données cohérentes qui décrit un certain composant de son holder. Par exemple HealthData, qui contient la vie actuelle et maximum. Si un data holder a un HealthData, il a la santé qu’on peut en quelques sortes épuiser et réapprovisionner, et peut mourir si cette santé est épuisée. Cela permet la réutilisation de ces composants à travers l’API et évite la duplication des méthodes d’accesseurs. Par exemple, les moutons, les blocs de verres teints et les armures en cuir peuvent tous partager le DyeableData détenant la couleur dans laquelle ils sont teints.
Clé
Une Key est un identifieur unique pour un unique point de données et peut être utilisée pour lire directement ou définir ce point de données sans se soucier des data manipulators. Il a été conçu pour fournir un moyen pratique d’accéder à des données similaires au méthode directes getter/setter. Toutes les keys utilisées à l’intérieur de Sponge sont listées en tant que constantes dans la classe utilitaire Keys.
Valeur
Au sein de la Data API, une valeur référée par une Key est encodée dans un objet contenur. Pour cette documentation, il est dénommé keyed value (valeur clé) pour éviter toute confusion avec la valeur réelle. Une valeur clé encapsule la valeur de données réelles (si elle est présente), une valeur par défaut (à utiliser si aucune valeure directe n’est présente) et la Key par laquelle la valeur est identifiée.
