Ensembles de tuiles et coups

Le type énuméré PlayerId du paquetage principal, public, permet d'identifier les joueurs. Il possède quatre valeurs qui sont, dans l'ordre :

P1

qui identifie le joueur 1,

P2

qui identifie le joueur 2,

P3

qui identifie le joueur 3,

P4

qui identifie le joueur 4.

En plus de ces valeurs, PlayerId possède un attribut ALL de type List<PlayerId>, défini de la manière usuelle.

La classe PkMove du sous-paquetage gamestate.packed, publique et finale, contient des méthodes statiques permettant de manipuler des coups empaquetés dans des valeurs de type short selon la manière décrite à la §2.1.2, à savoir :

• l'index de la source est placé dans les 4 bits de poids faible,
• l'index de la couleur est placé dans les 3 bits suivants,
• l'index de la destination est placé dans les 3 bits suivants,

et les 6 bits de poids fort valent toujours 0.

PkMove offre les méthodes publiques et statiques suivantes :

short pack(TileSource source, TileKind.Colored color, TileDestination destination)

qui retourne l'entier short qui est la représentation empaquetée du coup dont la source, la couleur de tuile et la destination sont celles données,

TileSource source(short pkMove)

qui retourne la source du coup empaqueté pkMove,

TileKind.Colored color(short pkMove)

qui retourne la couleur du coup empaqueté pkMove,

TileDestination destination(short pkMove)

qui retourne la destination du coup empaqueté pkMove.

Avant de décrire Move, la prochaine classe à mettre en œuvre pour cette étape, il convient de décrire le concept de classe enregistrement (record class), ou simplement enregistrement (record), introduit dans la version 17 de Java.

Un enregistrement est un type particulier de classe qui peut se définir au moyen d'une syntaxe plus concise qu'une classe normale. Dans cette syntaxe, le mot-clef class est remplacé par record et les attributs de la classe sont donnés entre parenthèses, après son nom.

Par exemple, un enregistrement nommé Complex représentant un nombre complexe dont les attributs sont sa partie réelle re et sa partie imaginaire im — tous deux de type double — peut se définir ainsi :

public record Complex(double re, double im) { }

Cette définition est équivalente à celle d'une classe finale (!) dotée de :

• deux attributs privés et finaux nommés re et im de type double,
• un constructeur prenant en argument la valeur de ces attributs et les initialisant,
• des méthodes d'accès (getters) publics nommés re() et im() pour ces attributs,
• une méthode equals retournant vrai si et seulement si l'objet qu'on lui passe est aussi une instance de Complex et que ses attributs sont égaux à ceux de this,
• une méthode hashCode compatible avec la méthode equals — le but de cette méthode et la signification de sa compatibilité avec equals seront examinés ultérieurement dans le cours,
• une méthode toString retournant une chaîne composée du nom de la classe et du nom et de la valeur des attributs de l'instance, p. ex. Complex[re=1.0, im=2.0].

En d'autres termes, la définition plus haut, qui tient sur une ligne, est équivalente à la définition suivante, qui n'utilise que des concepts que vous connaissez déjà :

public final class Complex {
  private final double re;
  private final double im;

  public Complex(double re, double im) {
    this.re = re;
    this.im = im;
  }

  public double re() { return re; }
  public double im() { return im; }

  @Override
  public boolean equals(Object that) {
    // … vrai ssi that :
    // 1. est aussi une instance de Complex, et
    // 2. ses attributs re et im sont identiques.
  }

  @Override
  public int hashCode() {
    // … code omis car peu important
  }

  @Override
  public String toString() {
    return "Complex[re=" + re + ", im=" + im + "]";
  }
}

Comme cet exemple l'illustre, les enregistrements permettent d'éviter d'écrire beaucoup de code répétitif, ce que les anglophones appellent du boilerplate code. Il faut toutefois bien comprendre qu'en dehors d'une syntaxe très concise, les enregistrements n'apportent — pour l'instant en tout cas — rien de nouveau à Java, dans le sens où il est toujours possible de récrire un enregistrement en une classe Java équivalente, comme ci-dessus. En cela, les enregistrements sont similaires aux types énumérés.

Il est bien entendu possible de définir des méthodes dans un enregistrement, qui viennent s'ajouter à celles définies automatiquement. Par exemple, pour doter l'enregistrement Complex d'une méthode modulus retournant son module, il suffit de l'ajouter entre les accolades, ainsi :

public record Complex(double re, double im) {
  public double modulus() { return Math.hypot(re, im); }
}

(La méthode Math.hypot(x,y) retourne \(\sqrt{x^2 + y^2}\)).

Finalement, il est aussi possible de définir ce que l'on nomme un constructeur compact (compact constructor), qui augmente le constructeur que Java ajoute par défaut aux enregistrements. Un constructeur compact doit son nom au fait qu'il semble ne prendre aucun argument, et n'initialise pas explicitement les attributs. En réalité, il prend des arguments qui sont les mêmes que ceux de l'enregistrement (re et im dans notre exemple), et Java lui ajoute automatiquement des affectations de ces arguments aux attributs correspondants.

Par exemple, on pourrait vouloir ajouter un constructeur compact à la classe Complex pour lever une exception si l'un des arguments passés au constructeur était une valeur NaN (not a number, une valeur invalide). On pourrait le faire ainsi :

public record Complex(double re, double im) {
  public Complex {  // constructeur compact
    if (Double.isNaN(re) || Double.isNaN(im))
      throw new IllegalArgumentException();
  }
  // … méthode modulus
}

Ce constructeur compact serait automatiquement traduit en :

public final class Complex {
  // … attributs re et im

  public Complex(double re, double im) {
    if (Double.isNaN(re) || Double.isNaN(im))
      throw new IllegalArgumentException();
    this.re = re;  // ajouté automatiquement
    this.im = im;  // ajouté automatiquement
  }

  // … méthodes modulus, re, im, hashCode, etc.
}

Les enregistrements ne seront pas décrits en détail dans le cours, mais seront introduits au moyen d'exemples similaires à ceux ci-dessus dans la suite du projet. Les personnes intéressées par les détails de leur fonctionnement pourront se rapporter à la §8.10 (Record Classes) de la spécification du langage.

L'enregistrement Move du sous-paquetage gamestate, public, représente un coup. Il possède trois attributs qui sont, dans l'ordre :

TileSource source

la source de laquelle les tuiles jouées sont obtenues,

TileKind.Colored tileColor

la couleur des tuiles jouées,

TileDestination destination

la destination sur laquelle les tuiles jouées sont placées.

Afin de garantir que ces attributs sont valides, Move possède un constructeur compact qui vérifie, au moyen de la méthode requireNonNull de Objects, qu'aucun d'entre eux ne vaut null.

De plus, Move possède un attribut public, statique et final :

int MAX_MOVES

qui donne le nombre maximum de coups entre lesquels un joueur d'Ajul peut avoir à choisir, calculé comme le produit du nombre de fabriques, du nombre de tuiles par fabrique, et du nombre de destinations.

Move offre également une méthode fabrique pour obtenir une instance à partir d'un coup empaqueté :

Move ofPacked(short pkMove)

qui retourne le coup correspondant au coup empaqueté donné,

et une méthode permettant de faire l'inverse :

short packed()

qui retourne le coup empaqueté correspondant au récepteur — le coup auquel on applique la méthode.

La classe PkTileSet du sous-paquetage gamestate.packed, publique et finale, contient des méthodes statiques permettant de manipuler des ensembles de tuiles empaquetés dans des entiers de type int comme décrit à la §2.2.1, à savoir :

• le nombre de tuiles de couleur A, compris entre 0 et 20 (inclus), est stocké dans les 6 bits de poids faible (index 0 à 5),
• le nombre de tuiles de couleur B est stocké dans les 6 bits suivants (index 6 à 11),
• et ainsi de suite pour les couleurs C, D et E,
• le nombre de marqueurs de premier joueur, compris entre 0 et 1 (inclus), est stocké dans le bit d'index 30,

et le bit de poids le plus fort (index 31) vaut toujours 0.

PkTileSet offre des attributs publics, statiques et finaux qui représentent différents ensembles de tuiles empaquetés constants, à savoir :

int EMPTY

qui représente l'ensemble de tuiles vide,

int FULL

qui représente l'ensemble de tuiles plein, c.-à-d. composé de toutes les tuiles disponibles dans le jeu — 20 tuiles de chacune des couleurs, et le marqueur de premier joueur,

int FULL_COLORED

qui est similaire à FULL mais sans le marqueur de premier joueur.

De plus, PkTileSet offre les méthodes publiques et statiques suivantes qui permettent de manipuler des ensembles de tuiles empaquetés dans des valeurs de type int :

int of(int count, TileKind tileKind)

qui retourne un ensemble de tuiles empaqueté ne contenant que count tuiles de la sorte tileKind,

boolean isEmpty(int pkTileSet)

qui retourne vrai ssi (si et seulement si) l'ensemble de tuiles empaqueté pkTileSet est vide,

int size(int pkTileSet)

qui retourne la taille de l'ensemble de tuiles empaqueté pkTileSet, c.-à-d. le nombre de tuiles qu'il contient,

int countOf(int pkTileSet, TileKind tileKind)

qui retourne le nombre de tuiles de la sorte tileKind que contient l'ensemble de tuiles empaqueté pkTileSet,

int subsetOf(int pkTileSet, TileKind tileKind)

qui retourne le sous-ensemble de l'ensemble de tuiles empaqueté pkTileSet constitué de toutes les tuiles de la sorte tileKind qu'il contient,

int add(int pkTileSet, TileKind tileKind)

qui retourne un ensemble de tuiles empaqueté égal à pkTileSet si ce n'est qu'il contient exactement une tuile de la sorte tileKind en plus,

int remove(int pkTileSet, TileKind tileKind)

qui retourne un ensemble de tuiles empaqueté égal à pkTileSet si ce n'est qu'il contient exactement une tuile de la sorte tileKind en moins,

int union(int pkTileSet1, int pkTileSet2)

qui retourne l'union (empaquetée) des ensembles de tuiles empaquetés pkTileSet1 et pkTileSet2,

int difference(int pkTileSet1, int pkTileSet2)

qui retourne la différence (empaquetée) des ensembles de tuiles empaquetés pkTileSet1 et pkTileSet2, où pkTileSet2 doit être un sous-ensemble de pkTileSet1,

int copyColoredInto(int pkTileSet, TileKind.Colored[] destination)

qui copie, dans le tableau destination, les tuiles colorées de l'ensemble empaqueté pkTileSet et retourne l'index, dans le tableau destination, de l'élément qui suit le dernier qui a été écrit ; les tuiles doivent être placées dans le tableau ordonnées par couleur, c.-à-d. que celles de couleur A doivent apparaître en premier, suivies par celles de couleur B, et ainsi de suite,

int sampleColoredInto(int pkTileSet, TileKind.Colored[] destination, int offset, RandomGenerator randomGenerator)

qui obtient un échantillon aléatoire de l'ensemble pkTileSet et le place dans le tableau destination à partir de l'index offset, en utilisant l'algorithme d'échantillonnage par réservoir et en générant les nombres aléatoires au moyen de randomGenerator ; retourne la somme de offset et de la taille de l'ensemble,

String toString(int pkTileSet)

qui retourne la représentation textuelle de l'ensemble de tuiles, décrite ci-après.

La représentation textuelle d'un ensemble de tuiles est composée d'autant d'éléments qu'il y a de sortes de tuiles dans l'ensemble, chacun d'entre eux étant composé de :

• le nombre d'occurrences de cette sorte de tuile, qui doit être supérieur à 0,
• une astérisque (*),
• le nom de la sorte de tuiles (A à E ou FIRST_PLAYER_MARKER).

Ces éléments sont séparés par des virgules et entourés d'accolades ({}). Par exemple, la représentation textuelle de FULL est :

{20*A,20*B,20*C,20*D,20*E,1*FIRST_PLAYER_MARKER}

Pour faciliter votre travail, nous mettons à votre disposition un fichier de vérification de signatures, nommé SignatureChecks_2.java, à importer dans votre projet dans le même dossier que celui contenant le fichier SignatureChecks_1.java. La classe qu'il contient fait référence à la totalité des classes et méthodes de cette étape, ce qui vous permet de vérifier que leurs noms et types sont corrects. Cela est capital, car la moindre faute à ce niveau empêcherait l'exécution de nos tests unitaires.

Nous vous fournirons de tels fichiers pour toutes les étapes jusqu'à la sixième (incluse), et il vous faudra penser à vérifier systématiquement qu'aucune erreur n'est signalée à leur sujet. Faute de cela, votre rendu pourrait se voir refusé par notre système.

À partir de cette étape, nous ne vous fournissons plus de tests unitaires, et il vous faut donc les écrire vous-même.

Notez que, pour les étapes 2 à 6, nous mettrons à disposition nos tests le lundi suivant le jour de rendu de chaque étape. Vous aurez alors tout intérêt à les incorporer à votre projet, ce qui peut poser un problème de nommage.

En effet, si vous nommez vos tests selon la convention standard, en ajoutant simplement le suffixe Test au nom de la classe testée, vos tests auront le même nom que les nôtres, et il ne vous sera pas possible d'avoir vos tests et les nôtres dans un même projet. Pour cette raison, nous vous recommandons d'adopter une autre convention de nommage pour vos tests, par exemple en entourant le nom de la classe testée au moyen du préfixe My et du suffixe Test. Ainsi, votre test pour la classe Rational pourrait être nommé MyRationalTest.