Sérialisation

Comme cela a déjà été dit, une partie de tCHu se joue entre deux personnes utilisant chacune leur propre ordinateur. Sur chacun de ces ordinateurs s'exécute un programme que l'on nomme le client (client), qui gère principalement l'interface graphique. Un troisième programme, nommé le serveur (server), gère quant à lui le déroulement de la partie. En général, ce serveur s'exécute sur le même ordinateur que l'un des deux clients — comme illustré ci-dessous — mais il pourrait également s'exécuter sur un troisième ordinateur distinct des deux autres.

Les flèches de l'image ci-dessus représentent les échanges d'information entre ces trois programmes. Elles illustrent le fait que le serveur communique avec chacun des deux clients, mais les clients ne communiquent jamais entre eux.

La communication client/serveur se fait par échange de messages textuels. Un message est une simple chaîne de caractères ASCII imprimables, terminée par un caractère de retour à la ligne — le caractère dont le code ASCII est 10, et qui s'écrit \n en Java.

La communication est toujours initiée par le serveur, qui envoie un message à un client. Certains des messages envoyés par le serveur demandent une réponse, tandis que d'autre n'en demandent aucune. Lorsqu'une réponse est demandée, le client la retourne au serveur sous la forme d'un message, c-à-d d'une chaîne de caractères ASCII terminée par un retour à la ligne.

Les messages échangés entre le serveur et les clients correspondent directement aux méthodes de l'interface Player. C'est-à-dire qu'à chaque méthode de cette interface correspond un type de message, et inversement. En d'autres termes, chacun des deux clients peut être vu comme une instance d'un objet implémentant l'interface Player. Le serveur, qui gère le déroulement de la partie au moyen d'une instance de Game, appelle « à distance » les méthodes de ces objets, au moyen de messages textuels.

Pour illustrer le fonctionnement de cette communication, voici les cinq premiers messages qui pourraient être envoyés par le serveur à l'un des deux clients au début d'une partie — le second recevant des messages similaires :

INIT_PLAYERS 0 QWRh,Q2hhcmxlcw==
RECEIVE_INFO QWRhIGpvdWVyYSBlbiBwcmVtaWVyLgoK
SET_INITIAL_TICKETS 6,1,44,42,42
UPDATE_STATE 36:6,7,4,7,1;97;0:0:0;4;:0;4;: ;0,1,5,5;
CHOOSE_INITIAL_TICKETS

Le premier de ces messages correspond à un appel à initPlayers, le second à un appel à receiveInfo, etc. Les quatre premiers de ces messages ne demandent aucune réponse du client — étant donné que les méthodes correspondantes ont void comme type de retour — mais le dernier en demande une, puisqu'il correspond à un appel à chooseInitialTickets. En admettant que le joueur utilisant ce client choisisse les trois premiers billets qui lui sont proposés, le client répondrait alors avec le message suivant :

6,1,44

Et ainsi de suite.

La signification des différentes parties des messages deviendra claire à la lecture des section ci-dessous.

Sachant que les messages échangés entre le serveur et les clients correspondent aux méthodes de l'interface Player, il faut que, d'une manière ou d'une autre, ces messages contiennent toute l'information contenue dans les arguments et les valeurs de retour de ces méthodes.

Par exemple, le message INIT_PLAYERS, qui correspond à la méthode initPlayers, doit contenir l'information donnant l'identité du joueur — de type PlayerId — et la table donnant le nom des deux joueurs — de type Map<PlayerId, String>.

Sachant que les messages sont textuels et ne peuvent contenir que des caractères ASCII imprimables, il doit donc être possible de transformer n'importe quelle valeur qu'une méthode de Player peut prendre en argument ou retourner en résultat en une chaîne composée de tels caractères. Cette transformation doit bien entendu être inversible, dans le sens où il doit être possible d'obtenir la valeur Java correspondant à une chaîne donnée.

Nous appellerons sérialisation (serialization) l'opération consistant à transformer une valeur Java en une chaîne de caractères ASCII imprimables, et désérialisation (deserialization) l'opération inverse.

En examinant les méthodes de l'interface Player, on constate que les valeurs Java suivantes doivent pouvoir être (dé)sérialisées :

• des entiers (int),
• des chaînes de caractères (String),
• des valeurs de types énumérés (PlayerId, TurnKind et Card),
• des valeurs de types qui ne sont pas des types énumérés Java mais dont il n'existe néanmoins qu'un nombre fini de valeurs (Ticket et Route),
• des listes (List<…>) et des multiensembles (SortedBag<…>) de valeurs,
• des valeurs de types composites, constitués de plusieurs attributs de types différents (PublicGameState, PublicCardState, PublicPlayerState, PlayerState).

Il convient donc de choisir, pour chacun de ces types, une manière de sérialiser leurs valeurs, ce qui est fait dans les sections suivantes.

Le type énuméré MessageId du paquetage ch.epfl.tchu.net énumère les types de messages que le serveur peut envoyer aux clients. Comme nous l'avons vu plus haut, ces messages correspondent directement aux méthodes de l'interface Player. Les membres de ce type énuméré sont :

• INIT_PLAYERS,
• RECEIVE_INFO,
• UPDATE_STATE,
• SET_INITIAL_TICKETS,
• CHOOSE_INITIAL_TICKETS,
• NEXT_TURN,
• CHOOSE_TICKETS,
• DRAW_SLOT,
• ROUTE,
• CARDS,
• CHOOSE_ADDITIONAL_CARDS.

Notez que même si vous avez le droit d'utiliser d'autres noms, cela est fortement découragé car ces noms seront utilisés pour identifier les différents messages, comme l'exemple de la §2.1 l'illustre.

L'interface Serde du paquetage ch.epfl.tchu.net représente ce que l'on nomme parfois un serde (de serializer-deserializer), à savoir un objet capable de sérialiser et désérialiser des valeurs d'un type donné.

Cette interface est générique, son paramètre de type représentant le type des éléments que le serde est capable de (dé)sérialiser. Elle contient deux méthodes abstraites :

1. une méthode, nommée p.ex. serialize, prenant en argument l'objet à sérialiser et retournant la chaîne correspondante,
2. une méthode, nommée p.ex. deserialize, prenant en argument une chaîne et retournant l'objet correspondant.

Ces deux méthodes doivent bien entendu être inverses l'une de l'autre. L'extrait de test JUnit ci-dessous, qui devrait s'exécuter avec succès, illustre l'utilisation d'un serde sérialisant les entiers au moyen de leur représentation en base 10 :

Serde<Integer> intSerde = /* … */;
assertEquals("2021", intSerde.serialize(2021));
assertEquals(2021, intSerde.deserialize("2021"));

En plus des méthodes abstraites de (dé)sérialisation, l'interface Serde définit quatre méthodes statiques permettant de créer différents types de serdes :

• une méthode générique nommée p.ex. of prenant en arguments une fonction de sérialisation et une fonction de désérialisation, et retournant le serde correspondant ; le type de la fonction de sérialisation qu'on lui passe doit être Function<T, String>, tandis que celui de la fonction de désérialisation doit être Function<String, T>, où T est le paramètre de type de la méthode,
• une méthode générique nommée p.ex. oneOf prenant en argument la liste de toutes les valeurs d'un ensemble de valeurs énuméré et retournant le serde correspondant,
• une méthode générique nommée p.ex. listOf prenant en argument un serde et un caractère de séparation et retournant un serde capable de (dé)sérialiser des listes de valeurs (dé)sérialisées par le serde donné,
• une méthode générique nommée p.ex. bagOf fonctionnant comme listOf mais pour les multiensembles triés (SortedBag).

La méthode of est destinée à être utilisée avec des lambdas car, pour mémoire, l'interface Function est une interface fonctionnelle définie dans le paquetage java.util.function. Elle pourrait par exemple être utilisée ainsi pour définir un serde capable de (dé)sérialiser des entiers au moyen de leur représentation en base 10 :

Serde<Integer> intSerde = Serde.of(
  i -> Integer.toString(i),
  Integer::parseInt);

Les trois autres méthodes devraient pouvoir s'utiliser comme illustré ci-dessous pour obtenir des serdes capables de (dé)sérialiser des couleurs, des listes de couleurs (séparées par des +), et des multiensembles de couleurs (séparées par des +) :

Serde<Color> color = Serde.oneOf(Color.ALL);
Serde<List<Color>> listOfColor = Serde.listOf(color, "+");
Serde<SortedBag<Color>> bagOfColor = Serde.bagOf(color, "+");

La classe Serdes du paquetage ch.epfl.tchu.net, non instanciable, contient la totalité des serdes utiles au projet. Chacun d'entre eux est défini comme un attribut publique, statique et final de la classe. La table ci-dessous liste les types pour lesquels un serde est nécessaire, en rappelant le séparateur à utiliser pour les serdes qui sérialisent des valeurs composites, ainsi que la liste de valeurs à utiliser pour ceux qui sérialisent des valeurs énumérées :

À partir de cette étape, aucun fichier de vérification de signatures ne vous est fourni, étant donné que la signature des différentes méthodes n'est plus spécifiée en détail. Pour la même raison, aucun test unitaire ne sera plus fourni à l'avenir, à vous d'écrire les vôtres. Notez que cela est fortement recommandé en général.