Lignes de motif et plancher

La classe PkPatterns du sous-paquetage gamestate.packed, publique et finale, contient des méthodes statiques permettant de manipuler le contenu des lignes de motif d'un joueur, empaqueté de la manière décrite à la §2.1.1, à savoir :

• les 3 bits de poids faible contiennent le nombre de tuiles présentes sur la ligne de motif 1,
• les 3 bits suivants contiennent l'index de la couleur des tuiles présentes sur la ligne de motif 1, ou 0 si la ligne de motif est vide,
• et ainsi de suite pour les lignes de motif 2 à 5,

et les 2 bits de poids fort valent toujours 0.

PkPatterns possède un unique attribut public, statique et final :

int EMPTY

qui représente les lignes de motif vides.

Elle offre de plus les méthodes publiques et statiques suivantes pour manipuler des lignes de motif empaquetées :

int size(int pkPatterns, TileDestination.Pattern line)

qui retourne le nombre de tuiles présentes sur la ligne de motif line des lignes de motif empaquetées pkPatterns,

TileKind.Colored color(int pkPatterns, TileDestination.Pattern line)

qui retourne la couleur des tuiles présentes sur la ligne de motif line des lignes de motif empaquetées pkPatterns — voir les conseils de programmation plus bas pour savoir que faire si cette ligne est vide,

boolean isFull(int pkPatterns, TileDestination.Pattern line)

qui retourne vrai ssi la ligne de motif line des lignes de motif empaquetées pkPatterns est pleine, c.-à-d. contient le nombre maximum de tuiles qu'elle peut contenir,

boolean canContain(int pkPatterns, TileDestination.Pattern line, TileKind.Colored color)

qui retourne vrai ssi la ligne de motif line des lignes de motif empaquetées pkPatterns peut contenir des tuiles de couleur color, c.-à-d. si elle est vide ou si elle contient déjà des tuiles de couleur color — indépendemment du fait qu'elle soit pleine ou non,

int withAddedTiles(int pkPatterns, TileDestination.Pattern line, int tileCount, TileKind.Colored color)

qui retourne des lignes de motif empaquetées identiques à pkPatterns mais avec tileCount tuiles de couleur color ajoutées à la ligne line — voir les conseils de programmation plus bas pour savoir que faire si l'ajout est invalide,

int withEmptyLine(int pkPatterns, TileDestination.Pattern line)

qui retourne des lignes de motif empaquetées identiques à pkPatterns mais avec la ligne line vide,

int asPkTileSet(int pkPatterns)

qui retourne l'ensemble de tuiles empaqueté constitué de toutes les tuiles se trouvant sur les lignes de motif empaquetées pkPatterns,

String toString(int pkPatterns)

qui retourne la représentation textuelle des lignes de motif empaquetées pkPatterns, décrite ci-après.

La représentation textuelle des lignes de motif est constituée de cinq éléments — un par ligne — séparés par des virgules suivies d'espaces, et entourés de crochets. L'élément représentant une ligne commence par la lettre correspondant à la couleur des tuiles qu'elle contient, répétée autant de fois qu'il y a de tuiles sur la ligne, et se termine par une suite de points (.) assez longue pour que l'élément ait une longueur égale à la capacité de la ligne. Ainsi, la représentation textuelle des lignes de motif de la figure 1 est :

[C, AA, AAA, EEE., .....]

La classe PkFloor du sous-paquetage gamestate.packed, publique et finale, contient des méthodes statiques permettant de manipuler le contenu d'une ligne plancher empaqueté de la manière décrite à la §2.2.1, à savoir :

• les 3 bits de poids faible contiennent le nombre de tuiles que contient la ligne plancher,
• les 3 bits suivants contiennent l'index de la première tuile se trouvant sur la ligne plancher, ou 0 s'il n'y en a aucune,
• et ainsi de suite pour les 6 autres tuiles qui peuvent se trouver sur la ligne plancher,

et les 8 bits de poids fort valent toujours 0.

PkFloor possède un attribut public, statique et final :

int EMPTY

qui représente la ligne plancher vide.

Elle offre de plus les méthodes publiques et statiques suivantes pour manipuler une ligne plancher empaquetée :

int size(int pkFloor)

qui retourne la taille de la ligne plancher empaquetée pkFloor, c.-à-d. le nombre de tuiles qu'elle contient,

TileKind tileAt(int pkFloor, int i)

qui retourne la sorte de tuile se trouvant à l'index i de la ligne plancher empaquetée pkFloor,

int withAddedTiles(int pkFloor, int pkTileSet)

qui retourne une ligne plancher empaquetée identique à pkFloor mais avec les tuiles de l'ensemble empaqueté pkTileSet ajoutées par ordre de sorte (A, B, C, D, E, marqueur de premier joueur) ; si la ligne n'a pas la capacité d'accueillir toutes ces tuiles, les excédentaires sont ignorées sauf le marqueur de premier joueur qui doit toujours être ajouté, en remplaçant au besoin la dernière tuile,

boolean containsFirstPlayerMarker(int pkFloor)

qui retourne vrai ssi la ligne plancher empaquetée pkFloor contient le marqueur de premier joueur,

int asPkTileSet(int pkFloor)

qui retourne l'ensemble de tuiles empaqueté constitué de toutes les tuiles se trouvant sur la ligne plancher empaquetée pkFloor,

String toString(int pkFloor)

qui retourne la représentation textuelle de la ligne plancher empaquetée pkFloor, décrite ci-après.

La représentation textuelle d'une ligne plancher est constituée des noms des sortes des tuiles qu'elle contient, séparés par des virgules suivies d'espaces, et entourés de crochets. Ainsi, la représentation textuelle de la ligne plancher de la figure 2 est :

[FIRST_PLAYER_MARKER, B, B]

Fréquemment, les méthodes d'un programme exigent que leurs arguments satisfassent certaines conditions. Par exemple, une méthode déterminant la valeur maximale d'un tableau d'entiers exige que ce tableau contienne au moins un élément.

De telles conditions sont souvent appelées préconditions (preconditions) car elles doivent être satisfaites avant l'appel d'une méthode : c'est à l'appelant de s'assurer qu'il n'appelle la méthode qu'avec des arguments valides.

En Java, la convention veut que chaque méthode vérifie, autant que possible, ses préconditions et lève une exception — souvent IllegalArgumentException — si l'une d'entre elles n'est pas satisfaite. Par exemple, une méthode max calculant la valeur maximale d'un tableau d'entiers, et exigeant logiquement que celui-ci contienne au moins un élément, pourrait commencer ainsi :

int max(int[] array) {
  if (! (array.length > 0))
    throw new IllegalArgumentException();
  // … reste du code
}

(Notez au passage que la méthode max ne déclare pas qu'elle lève potentiellement IllegalArgumentException au moyen d'une clause throws, car cette exception est de type unchecked.)

La classe Preconditions a pour but de faciliter l'écriture de telles préconditions. En l'utilisant, la méthode ci-dessus pourrait être simplifiée ainsi :

int max(int[] array) {
  Preconditions.checkArgument(array.length > 0);
  // … reste du code
}

Preconditions appartient au paquetage principal. Elle est publique et finale et n'offre rien d'autre que la méthode publique et statique suivante :

void checkArgument(boolean shouldBeTrue)

qui lève l'exception IllegalArgumentException si son argument est faux, et ne fait rien sinon.

La classe Game du paquetage principal, publique et immuable (donc finale), représente une configuration de partie d'Ajul.

Game possède un enregistrement imbriqué nommé PlayerDescription qui permet de décrire un joueur et qui possède les trois attributs suivants (dans l'ordre) :

PlayerId id

l'identité du joueur,

String name

le nom du joueur,

PlayerKind kind

la sorte du joueur, PlayerKind étant un type énuméré public, imbriqué dans PlayerDescription et contenant uniquement deux valeurs : HUMAN et AI.

En dehors de ces trois attributs, PlayerDescription possède un constructeur compact qui vérifie, au moyen de requireNonNull, qu'aucune des valeurs passées au constructeur ne vaut null.

Game offre un unique constructeur public :

Game(List<PlayerDescription> playerDescriptions)

qui retourne une nouvelle configuration de partie pour les joueurs décrits par playerDescriptions, ou lève une IllegalArgumentException si le nombre de joueurs n'est pas compris entre 2 et 4, ou si la position de l'un d'eux dans la liste ne correspond pas à son identité — en d'autres termes, si le premier joueur de la liste n'a pas l'identité P1, le second P2, etc.

De plus, Game offre les méthodes publiques suivantes :

List<PlayerDescription> playerDescriptions()

qui retourne la liste (immuable) des descriptions des joueurs de la partie, dont le contenu doit être identique à celui de la liste passée au constructeur,

List<PlayerId> playerIds()

qui retourne la liste (immuable) des identités des joueurs de la partie, qui doit être un préfixe de PlayerId.ALL,

int playersCount()

qui retourne le nombre de joueurs dans la partie,

List<TileSource.Factory> factories()

qui retourne la liste (immuable) des identités des fabriques utilisées dans la partie, qui doit être un préfixe de TileSource.Factory.ALL,

int factoriesCount()

qui retourne le nombre de fabriques utilisées dans la partie,

List<TileSource> tileSources()

qui retourne la liste (immuable) des sources de tuiles utilisées dans la partie, qui doit être un préfixe de TileSource.ALL,

int tileSourcesCount()

qui retourne le nombre de sources de tuiles dans la partie,

int centralAreaMaxSize()

qui retourne le nombre maximum de tuiles pouvant se trouver dans la zone centrale durant la partie, marqueur de premier joueur inclus.

Pour écrire ces méthodes, souvenez-vous que le nombre de fabriques dans une partie à n joueurs vaut 2​n + 1. D'autre part, le nombre maximum de tuiles pouvant se trouver dans la zone centrale durant une partie à m fabriques vaut 3​m + 1. En effet, chaque fabrique peut contribuer au maximum 3 tuiles à la zone centrale, et elle peut aussi contenir le marqueur de premier joueur.

Comme pour l'étape précédente, nous ne vous fournissons plus de tests mais un fichier de vérification de signatures à importer dans votre projet.