Mise en place

Avant de commencer à programmer, il faut vous assurer que la version 25 de Java est bien installée sur votre ordinateur, car c'est celle qui sera utilisée pour ce projet.

Si vous ne l'avez pas encore installée, rendez-vous sur le site Web du projet Adoptium, téléchargez le programme d'installation correspondant à votre système d'exploitation (macOS, Linux ou Windows), et exécutez-le.

Cela fait, si vous n'avez pas encore installé IntelliJ, téléchargez-le depuis le site de JetBrains et installez-le.

Une fois Java et IntelliJ installés, vous pouvez télécharger le squelette de projet que nous mettons à votre disposition. Il s'agit d'une archive Zip dont vous devrez tout d'abord extraire le contenu à un emplacement de votre choix sur votre ordinateur. (Notez que certains navigateurs comme Safari extraient automatiquement le contenu de telles archives.)

Une fois le contenu de l'archive extrait, vous constaterez qu'il se trouve en totalité dans un dossier nommé Ajul. Lancez IntelliJ, choisissez Open, sélectionnez ce dossier, et finalement cliquez Ok.

Le dossier Ajul contient les sous-dossiers suivants :

• src, destiné à contenir le code source de votre projet, ainsi que divers fichiers que nous mettrons à votre disposition, et qui contient pour l'instant :
  • SignatureChecks_1.java, un fichier de vérification de signatures pour l'étape 1, qui ne devrait plus contenir d'erreur lorsque vous aurez terminé la rédaction de cette étape,
  • Submit.java, un programme qui vous permettra de rendre votre projet à la fin de chaque semaine,
• test, destiné à contenir le code des tests unitaires de votre projet que nous vous fournirons ou que vous écrirez vous-même, et qui contient pour l'instant les tests de l'étape 1 — fournis exceptionnellement pour faciliter votre démarrage.

Pour vous assurer d'avoir bien importé le projet, vérifiez que le contenu du panneau Project d'IntelliJ ressemble à l'image ci-dessous.

L'interface TileKind du paquetage principal (ch.epfl.ajul), publique, représente les six sortes de tuiles qui existent dans le jeu, à savoir les cinq sortes de tuiles colorées et le marqueur de premier joueur.

TileKind est implémentée par les types énumérés Colored, décrit à la §3.4 plus bas, et FirstPlayerMarker, décrit à la §3.5. Il est donc fortement conseillé de lire également ces deux sections avant de commencer la rédaction de TileKind. Ces deux types énumérés sont imbriqués à l'intérieur de l'interface TileKind, qui a donc la structure suivante :

public interface TileKind {
  // … attributs et méthodes abstraites

  enum Colored implements TileKind {
    // … valeurs du type énuméré, attributs, méthodes concrètes
  }
  enum FirstPlayerMarker implements TileKind {
    // … valeurs du type énuméré, attributs, méthodes concrètes
  }
}

En raison de cette organisation, trois types Java différents existent pour représenter une sorte de tuile Ajul, à savoir :

TileKind

qui représente n'importe laquelle des six sortes de tuiles existantes dans le jeu — les cinq sortes de tuiles colorées et le marqueur de premier joueur,

TileKind.Colored

qui représente l'une des cinq sortes de tuiles colorées (A, B, C, D ou E),

TileKind.FirstPlayerMarker

qui représente le marqueur de premier joueur.

Comme vous le verrez ultérieurement, avoir ces trois types à disposition nous permet de mieux exprimer, au moyen de types Java, les valeurs valides dans une situation donnée. Par exemple, lorsqu'un joueur joue un coup, il choisit toutes les tuiles d'une même couleur d'une source donnée. Lorsque nous représenterons un coup, nous utiliserons donc le type TileKind.Colored plutôt que TileKind pour décrire la couleur choisie, garantissant ainsi que seules les tuiles colorées peuvent être jouées, et pas le marqueur de premier joueur.

L'interface TileKind offre les attributs publics, statiques et finaux suivants :

TileKind A

qui représente les tuiles colorées de couleur A,

TileKind B

qui représente les tuiles colorées de couleur B,

TileKind C

qui représente les tuiles colorées de couleur C,

TileKind D

qui représente les tuiles colorées de couleur D,

TileKind E

qui représente les tuiles colorées de couleur E,

TileKind FIRST_PLAYER_MARKER

qui représente le marqueur de premier joueur.

Ces attributs sont simplement définis comme étant égaux aux valeurs correspondantes des types énumérés décrits aux §3.4 et §3.5. Ainsi, TileKind.A référence exactement le même objet que TileKind.Colored.A mais avec un type différent ! En effet, TileKind.A a le type TileKind tandis que TileKind.Colored.A a le type TileKind.Colored. En fonction des besoins, nous utiliserons l'un ou l'autre de ces attributs.

En plus des attributs ci-dessus représentant les différentes sortes de tuiles, TileKind offre les deux attributs suivants :

List<TileKind> ALL

une liste immuable qui contient les six attributs définis plus haut (A, B, C, D, E et FIRST_PLAYER_MARKER), dans le même ordre,

int COUNT

qui contient le nombre de sortes de tuiles qui existent (6).

Les conseils de programmation ci-dessous vous donneront les indications nécessaires à la définition de ces deux attributs.

Finalement, TileKind offre deux méthodes publiques et abstraites, qui sont :

int index()

qui retourne l'index de la sorte de tuile à laquelle on l'applique, à savoir 0 pour A, 1 pour B, …, 4 pour E et 5 pour FIRST_PLAYER_MARKER,

int tilesCount()

qui retourne le nombre de tuiles de la sorte à laquelle on l'applique qui existent dans le jeu, à savoir 20 pour les tuiles colorées et 1 pour le marqueur de premier joueur.

Le type énuméré Colored, imbriqué dans l'interface TileKind, représente les différentes sortes de tuiles colorées qui existent dans le jeu. Il possède donc cinq valeurs, nommées A, B, C, D et E, qui représentent les cinq couleurs de tuiles. Notez que ces valeurs doivent impérativement être définies dans cet ordre.

Colored implémente l'interface TileKind et possède donc des définitions concrètes des méthodes index et tilesCount. De plus, Colored offre des attributs similaires à ceux offerts par TileKind, à savoir :

List<Colored> ALL

une liste immuable qui contient la totalité des valeurs du type énuméré, dans leur ordre de définition (voir les conseils de programmation plus bas),

int COUNT

qui contient le nombre de valeurs du type énuméré, à savoir 5.

Finalement, Colored offre une méthode publique et statique permettant de mélanger les éléments d'un tableau de valeurs de type Colored au moyen de l'algorithme décrit à la §2.4 :

void shuffle(Colored[] tiles, RandomGenerator randomGenerator)

qui mélange les éléments du tableau tiles en utilisant le générateur aléatoire randomGenerator pour obtenir des nombres aléatoires (voir les conseils de programmation ci-dessous).

Le type énuméré FirstPlayerMarker est similaire à Colored mais ne possède qu'une seule valeur, nommée FIRST_PLAYER_MARKER, qui représente le marqueur de premier joueur.

Les seules méthodes offertes par FirstPlayerMarker sont des définitions concrètes des méthodes de TileKind (index et tilesCount).

En Java, une interface peut normalement être implémentée par n'importe quelle classe. Par exemple, l'interface TileKind pourrait très bien être implémentée par d'autres classes que Colored et FirstPlayerMarker.

Dans ce cas particulier, cela n'est toutefois pas souhaitable, car nous savons que les seules sortes de tuiles qui existent dans le projet sont celles-là. Il serait donc bien de pouvoir communiquer cela à Java, afin d'interdire la définition d'autres classes implémentant l'interface TileKind.

Cela peut se faire en scellant (seal) l'interface TileKind, simplement en ajoutant le mot-clef sealed à l'interface, ainsi :

public sealed interface TileKind { … }

Lorsqu'une interface est ainsi scellée, les seules classes qui ont le droit de l'implémenter sont celles se trouvant dans la même unité de compilation (compilation unit), c.-à-d. le même fichier Java.

L'interface TileSource du paquetage principal, publique et scellée, identifie une source de tuiles, c.-à-d. l'une des fabriques ou la zone centrale.

Pour la même raison qu'il est utile d'avoir trois types représentant les sortes de tuiles, il est utile d'avoir trois types identifiant les sources de tuiles, qui sont :

• TileSource, une interface identifiant une source de tuiles quelconque (fabrique ou zone centrale),
• TileSource.CenterArea, un type énuméré ne possédant qu'une seule valeur, qui identifie la zone centrale,
• TileSource.Factory, un type énuméré possédant neuf valeurs, qui identifient chacune l'une des fabriques.

L'organisation de l'interface TileSource est donc très similaire à celle de TileKind et n'est donc décrite que très rapidement ci-après.

TileSource possède dix attributs publics, statiques et finaux qui correspondent aux dix sources de tuiles existant. Tous ces attributs ont le type TileSource et celui correspondant à la zone centrale se nomme CENTER_AREA tandis que ceux correspondant aux fabriques se nomment FACTORY_1 à FACTORY_9.

TileSource offre une unique méthode abstraite et publique :

int index()

qui retourne l'index de la source, à savoir 0 pour la zone centrale, et 1 à 9 pour les fabriques 1 à 9.

Finalement, TileSource offre deux attributs similaires à ceux qui existent dans TileKind :

List<TileSource> ALL

une liste immuable qui contient toutes les sources, chacune d'entre elles étant à l'index retourné par la méthode index — 0 pour la zone centrale, 1 pour la fabrique 1, etc.

int COUNT

qui contient le nombre total de sources de tuiles, à savoir 10.

Le type énuméré CenterArea, imbriqué dans l'interface TileSource qu'il implémente, identifie la zone centrale. Il ne contient donc qu'une seule valeur, nommée CENTER_AREA, qui représente cette zone.

CenterArea n'offre rien d'autre qu'une mise en œuvre concrète de la méthode index de TileSource, qui retourne 0.

Le type énuméré Factory, imbriqué dans l'interface TileSource qu'il implémente, identifie les fabriques. Il contient donc neuf valeurs, nommées FACTORY_1 à FACTORY_9, définies dans cet ordre.

Factory offre un attribut public, statique et final de type int, nommé TILES_PER_FACTORY et contenant le nombre de tuiles que contient une fabrique, à savoir 4. De plus, elle offre les attributs ALL et COUNT déjà décrits plus haut pour d'autres types, ainsi qu'une mise en œuvre concrète de la méthode index de TileSource, qui retourne 1 pour la fabrique 1, 2 pour la fabrique 2, etc.

L'interface TileDestination du paquetage principal, publique et scellée, identifie une destination de tuile, c.-à-d. l'une des 5 lignes de motif ou la ligne plancher.

TileDestination est très similaire à TileSource et est également implémentée par deux types énumérés représentant chacun un type de destination. Il s'agit de :

• Pattern (§3.11), qui identifie les lignes de motif,
• Floor (§3.12), qui identifie la ligne plancher.

TileDestination possède six attributs publics, statiques et finaux qui correspondent aux six destinations de tuiles existant. Ils ont le type TileDestination et ceux correspondant aux lignes de motif se nomment PATTERN_1 à PATTERN_5 tandis que celui correspondant à la ligne plancher se nomme FLOOR.

TileDestination offre deux méthodes abstraite et publiques :

int index()

qui retourne l'index de la destination, à savoir 0 pour la ligne de motif 1, 1 pour la ligne de motif 2, …, 4 pour la ligne de motif 5, et 5 pour la ligne plancher,

int capacity()

qui retourne la capacité de la destination, c.-à-d. le nombre de tuiles qu'elle peut contenir, à savoir 1 pour la première ligne, 2 pour la seconde, etc. et 7 pour la ligne plancher.

Finalement, TileDestination offre des attributs ALL et COUNT définis de manière similaire à ceux des classes ci-dessus.

Le type énuméré Pattern, imbriqué dans l'interface TileDestination qu'il implémente, identifie les lignes de motif. Il contient donc cinq valeurs, nommées PATTERN_1 à PATTERN_5, définies dans cet ordre.

Pattern offre les attributs ALL et COUNT déjà décrits plus haut pour d'autres types, ainsi qu'une mise en œuvre concrète des méthodes index et capacity de TileDestination.

Le type énuméré Floor, imbriqué dans l'interface TileDestination qu'il implémente, représente la ligne plancher. Il ne contient donc qu'une seule valeur, nommée FLOOR, qui représente cette ligne.

En plus de cette valeur, Floor offre bien entendu une mise en œuvre concrète des méthodes index et capacity de TileDestination.

L'interface ReadOnlyIntArray du sous-paquetage intarray (donc du paquetage ch.epfl.ajul.intarray), publique, représente un tableau d'entier en lecture seule. C'est-à-dire que les éléments d'un tableau de ce type peuvent être lus, mais pas modifiés.

ReadOnlyIntArray offre les méthodes publiques et abstraites suivantes :

int size()

qui retourne la taille du tableau,

int get(int i)

qui retourne l'élément d'index i du tableau, ou lève une exception de type IndexOutOfBoundsException si cet index est invalide,

ImmutableIntArray immutable()

qui retourne un tableau d'entier immuable (voir §3.15) ayant les mêmes éléments et la même taille que le tableau auquel on applique la méthode,

int[] toArray()

qui retourne un nouveau tableau Java primitif ayant les mêmes éléments et la même taille que le tableau auquel on applique la méthode.

La classe AbstractIntArray du sous-paquetage intarray, publique et abstraite, sert de classe-mère aux différentes classes mettant en œuvre les tableaux d'entiers. Elle implémente donc l'interface ReadOnlyIntArray.

AbstractIntArray possède un attribut privé de type int[] qui est le tableau primitif contenant les éléments du tableau d'entier, ainsi qu'un constructeur protégé (protected) prenant en argument ce tableau et le stockant dans l'attribut. Ce constructeur est bien entendu destiné à être utilisé par les deux sous-classes de AbstractIntArray, à savoir ImmutableIntArray (§3.15) et MutableIntArray (§3.16).

En plus de cet attribut privé et du constructeur protégé, AbstractIntArray offre des mises en œuvre concrètes de toutes les méthodes de l'interface ReadOnlyIntArray, à savoir :

• size et get, qui sont triviales à écrire car elles correspondent respectivement à l'attribut length et l'opération d'indexation ([]) du tableau primitif stocké en attribut,
• immutable, qui est aussi triviale à écrire mais seulement une fois que la méthode copyOf de ImmutableIntArray a été écrite (voir §3.15),
• toArray, qui est aussi triviale à écrire car elle doit simplement retourner une copie du tableau primitif stocké en attribut, qu'elle peut obtenir p. ex. au moyen de la méthode clone.

En plus de ces mises en œuvre concrètes des méthodes de ReadOnlyIntArray, AbstractIntArray contient également une redéfinition de la méthode toString de Object. Cette redéfinition de toString doit retourner la même chaîne que celle obtenue en appliquant la méthode toString de Arrays au tableau primitif stocké en attribut.

La classe ImmutableIntArray du sous-paquetage intarray, publique et finale, représente un tableau d'entier immuable, c.-à-d. dont le contenu ne peut pas changer après sa création. Elle hérite de AbstractIntArray et implémente donc, indirectement, l'interface ReadOnlyIntArray.

Le constructeur de ImmutableIntArray est privé et ne fait rien d'autre qu'appeler celui de sa super-classe en lui passant en argument le tableau reçu. Comme ce constructeur est privé, il n'est pas possible de l'utiliser depuis l'extérieur de la classe pour créer des instances de ImmutableIntArray. Pour cette raison, ImmutableIntArray offre ce que l'on nomme une méthode fabrique (factory method), publique et statique, qui permet de créer des instances de la classe :

ImmutableIntArray copyOf(int[] array)

qui retourne un nouveau tableau d'entiers immuable dont la taille et les éléments sont les mêmes que ceux du tableau primitif array.

La raison pour laquelle nous avons choisi de rendre le constructeur privé et d'offrir à la place la méthode fabrique copyOf est que le nom de cette méthode rappelle à ses utilisateurs que le tableau passé en argument est copié. Notez que cette technique consistant à offrir des méthodes fabriques plutôt que des constructeurs est fréquemment utilisée en Java, et il est donc bon de la connaître.

En plus de la méthode fabrique copyOf, ImmutableIntArray redéfinit la méthode immutable de ReadOnlyIntArray pour qu'elle retourne simplement le récepteur (this). En effet, lorsque cette méthode est appliquée à un tableau qui est déjà immuable, il n'est pas nécessaire de copier ce dernier.

La classe MutableIntArray du sous-paquetage intarray, publique et finale, représente un tableau d'entier non immuable. Elle hérite de AbstractIntArray et implémente donc, indirectement, l'interface ReadOnlyIntArray.

Une instance de MutableIntArray est très similaires à un tableau d'entiers primitifs de type int[], si ce n'est qu'elle a un type différent. En particulier, son type est un sous-type de ReadOnlyIntArray. Cela nous permet d'utiliser une instance de MutableIntArray dans les situations dans lesquelles une valeur de type ReadOnlyIntArray est attendue, ce qui ne serait pas possible avec un tableau d'entiers primitif de type int[].

Tout comme ImmutableIntArray, MutableIntArray « cache » son constructeur en le rendant privé, et offre à la place la méthode fabrique suivante, publique et statique :

MutableIntArray wrapping(int[] array)

qui retourne un nouveau tableau d'entiers non immuable qui « emballe » simplement le tableau array donné, sans le copier (!).

Là aussi, le nom de la méthode fabrique a pour but de rappeler à ses utilisateurs que la méthode se contente « d'emballer » le tableau primitif qu'on lui passe en argument, en le stockant dans un de ses attributs, mais sans le copier. En conséquence, si le contenu de ce tableau primitif change par la suite, le tableau MutableIntArray changera également.

Comme MutableIntArray représente un tableau d'entiers non immuable, il serait logique de lui ajouter au moins une méthode permettant de modifier un élément (nommée p. ex. set). Mais comme cette modification peut également se faire en modifiant directement le tableau passé à la méthode wrapping, et que c'est ce que nous ferons dans ce projet, nous avons renoncé à ajouter une telle méthode.

Pour vous aider à démarrer ce projet, des tests unitaires JUnit vous sont exceptionnellement fournis pour cette étape, et se trouvent dans le dossier test du squelette. Une fois que vous aurez terminé la rédaction des classes de cette étape, vous pourrez les exécuter en :

• ajoutant JUnit à votre projet, comme expliqué dans notre guide à ce sujet,
• effectuant un clic droit sur le dossier test du projet et sélectionnant Run 'All Tests'.

Une fois les tests exécutés avec succès, il vous reste à documenter la totalité des entités publiques (classes, attributs et méthodes) définies dans cette étape, au moyen de commentaires Javadoc, comme décrit dans le guide consacré à ce sujet. Vous pouvez écrire ces commentaires en français ou en anglais, en fonction de votre préférence, mais vous ne devez utiliser qu'une seule langue pour tout le projet.