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.
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é
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).
Manipulateur de données
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.
Clé
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.
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.
