Mise en place

Avant de commencer à programmer, il faut vous assurer que la version 21 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 la version Community Edition — et pas la version Ultimate qui apparaît au sommet de la page — depuis le site de JetBrains et installez-la.

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é ReCHor. Lancez IntelliJ, choisissez Open, sélectionnez ce dossier, et finalement cliquez Ok.

Le dossier ReCHor contient les sous-dossiers suivants :

• resources, destiné à contenir les « ressources » utiles au projet, en l'occurrence des icônes représentant les différents moyens de transport,
• 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.

Le dossier resources doit être marqué comme « dossier de ressources » pour qu'il soit correctement géré par IntelliJ. Pour cela, faites un clic droit sur lui puis sélectionnez Mark Directory As puis Resources Root. Vérifiez ensuite que le panneau Project d'IntelliJ ressemble à l'image ci-dessous.

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 première classe à réaliser dans le cadre de ce projet 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
}

Cette classe est nommée Preconditions et appartient au paquetage principal. Elle est publique et finale et n'offre rien d'autre que la méthode checkArgument décrite plus bas. Elle a toutefois la particularité d'avoir un constructeur par défaut privé :

public final class Preconditions {
  private Preconditions() {}
  // … méthode(s)
}

Le but de ce constructeur privé est de rendre impossible la création d'instances de la classe, puisque cela n'a clairement aucun sens — elle ne sert que de conteneur à une méthode statique. Dans la suite du projet, nous définirons plusieurs autres classes du même type, que nous appellerons dès maintenant classes non instanciables.

La méthode publique (et statique) offerte par la classe Preconditions est :

void checkArgument(boolean shouldBeTrue)

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

Le type énuméré Vehicle du sous-paquetage journey — donc du paquetage ch.epfl.rechor.journey — représente les différents types de véhicules de transport public en Suisse. Il comporte les sept valeurs suivantes, qui sont données ici dans l'ordre dans lequel elles doivent apparaître dans le type énuméré :

TRAM

qui représente un tram,

METRO

qui représente un métro,

TRAIN

qui représente un train,

BUS

qui représente un bus ou un car,

FERRY

qui représente un bac ou un autre type de bateau,

AERIAL_LIFT

qui représente une télécabine ou un autre type de transport aérien à câble,

FUNICULAR

qui représente un funiculaire.

En plus de ces valeurs, le type énuméré Vehicle offre l'attribut public, statique et final suivant :

List<Vehicle> ALL

une liste immuable contenant la totalité des valeurs du type énuméré, dans leur ordre de définition (voir les conseils de programmation ci-dessous).

Avant de décrire Stop, 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 Stop du sous-paquetage journey, public, représente un arrêt de transport public. Cet enregistrement est utilisé à la fois pour les gares et pour les voies ou quais. Il possède les attributs suivants :

String name

le nom de l'arrêt, ou le nom de la gare à laquelle appartient l'arrêt s'il représente une voie ou un quai,

String platformName

le nom de la voie ou du quai de l'arrêt, ou null si l'arrêt correspond à une gare,

double longitude

la longitude de la position de l'arrêt, en degrés,

double latitude

la latitude de la position de l'arrêt, en degrés.

Par exemple, l'arrêt correspondant à la gare de Lausanne pourrait être construit ainsi :

Stop l = new Stop("Lausanne", null, 6.62909, 46.51679);

tandis que celui correspondant à la voie 70 de cette même gare pourrait l'être ainsi :

Stop l70 = new Stop("Lausanne", "70", 6.62909, 46.51679);

Stop possède un constructeur compact chargé de valider les arguments et qui :

• lève une NullPointerException si name est null, ou
• lève une IllegalArgumentException si longitude n'est pas compris entre ±180° (inclus) ou si latitude n'est pas compris entre ±90° (inclus).

Stop ne possède aucune autre méthode que celles ajoutées automatiquement aux enregistrements par Java.

L'enregistrement Journey, du sous-paquetage journey, public et immuable, représente un voyage. Il possède un unique attribut :

List<Leg> legs

les étapes du voyage.

Le type Leg est celui d'une interface imbriquée à l'intérieur de l'enregistrement Journey et décrite à la §3.8. Comme expliqué dans cette section et celles qui suivent, trois enregistrements (IntermediateStop, Transport et Foot) sont imbriqués dans Leg. Cela signifie que Journey a la structure suivante :

public record Journey(/* … attributs */) {
  public interface Leg {
    public record IntermediateStop(/* … attributs */) {
      /* … constructeur et/ou méthodes */
    }
    /* … autres enregistrements imbriqués, méthodes */
  }
  /* … constructeur et/ou méthodes */
}

En raison de cette imbrication, la notation pointée doit être utilisée depuis l'extérieur pour accéder à l'interface Leg et aux enregistrements IntermediateStop, Transport et Foot. Par exemple, pour créer une instance de l'enregistrement IntermediateStop, on écrira :

new Journey.Leg.IntermediateStop(/* … arguments */);

Journey possède un constructeur compact qui valide la liste des étapes reçue en vérifiant que :

• elle n'est pas vide,
• les étapes à pied alternent avec celles en transport,
• pour toutes les étapes sauf la première, l'instant de départ ne précède pas celui d'arrivée de la précédente,
• pour toutes les étapes sauf la première, l'arrêt de départ est identique à l'arrêt d'arrivée de la précédente.

Si l'une de ces conditions n'est pas satisfaite, le constructeur compact lève une IllegalArgumentException. Sinon, dans le but de garantir l'immuabilité de la classe, il copie la liste des étapes en utilisant la technique décrite dans les conseils de programmation plus bas.

Journey offre les méthodes publiques suivantes :

Stop depStop()

qui retourne l'arrêt de départ du voyage, c.-à-d. celui de sa première étape,

Stop arrStop()

qui retourne l'arrêt d'arrivée du voyage, c.-à-d. celui de sa dernière étape,

LocalDateTime depTime()

qui retourne la date/heure de début du voyage, c.-à-d. celle de sa première étape,

LocalDateTime arrTime()

qui retourne la date/heure de fin du voyage, c.-à-d. celle de sa dernière étape,

Duration duration()

qui retourne la durée totale du voyage, c.-à-d. celle séparant la date/heure de fin de celle de début.

La classe LocalDateTime, qui représente un couple date/heure sans indication de fuseau horaire, fait partie de la bibliothèque Java. Cette classe jouera un rôle très important dans ce projet, et il est donc conseillé de prendre un moment pour lire sa documentation.

L'interface Leg, publique et imbriquée dans l'enregistrement Journey, représente une étape d'un voyage. Cette interface est implémentée par deux enregistrements, Transport (décrit à la §3.10) et Foot (décrit à la §3.11), qui correspondent aux deux types d'étapes — en transport et à pied.

L'interface Leg offre les méthodes suivantes, toutes abstraites sauf la dernière :

Stop depStop()

qui retourne l'arrêt de départ de l'étape,

LocalDateTime depTime()

qui retourne la date/heure de départ de l'étape,

Stop arrStop()

qui retourne l'arrêt d'arrivée de l'étape,

LocalDateTime arrTime()

qui retourne la date/heure d'arrivée de l'étape,

List<IntermediateStop> intermediateStops()

qui retourne la liste des arrêts intermédiaires de l'étape, le type IntermediateStop étant décrit à la §3.9,

default Duration duration()

qui retourne la durée de l'étape.

La classe Duration, qui représente une durée, est une classe de la bibliothèque Java qui provient du même paquetage que LocalDateTime (java.time). La lecture de sa documentation est aussi fortement recommandée.

L'enregistrement IntermediateStop, public et imbriqué dans l'interface Leg, représente un arrêt intermédiaire d'une étape. Il s'agit d'un arrêt auquel le moyen de transport utilisé s'arrête effectivement, mais qui se trouve entre l'arrêt de départ et l'arrêt d'arrivée de l'étape. Cet enregistrement possède les attributs suivants :

Stop stop

l'arrêt intermédiaire en question,

LocalDateTime arrTime

la date/heure d'arrivée à l'arrêt,

LocalDateTime depTime

la date/heure de départ de l'arrêt.

IntermediateStop possède un constructeur compact qui valide les arguments en vérifiant que :

• stop n'est pas null (avec requireNonNull),
• la date/heure de départ n'est pas antérieure à celle d'arrivée (attention, les deux peuvent être égales !).

Notez que, comme il s'agit d'un arrêt intermédiaire, le véhicule y arrive avant d'en repartir, raison pour laquelle la date/heure d'arrivée doit précéder (ou être identique à) celle de départ.

Comme d'habitude, une NullPointerException est levée si la première vérification échoue, et une IllegalArgumentException si la seconde échoue.

L'enregistrement Transport, public et imbriqué dans l'interface Leg, représente une étape effectuée en transport public. Il implémente donc Leg et possède les attributs suivants :

Stop depStop

l'arrêt de départ de l'étape,

LocalDateTime depTime

la date/heure de départ de l'étape,

Stop arrStop

l'arrêt d'arrivée de l'étape,

LocalDateTime arrTime

la date/heure d'arrivée de l'étape,

List<IntermediateStop> intermediateStops

les éventuels arrêts intermédiaires de l'étape,

Vehicle vehicle

le type de véhicule utilisé pour cette étape,

String route

le nom de la ligne sur laquelle circule le véhicule utilisé pour cette étape,

String destination

le nom de la destination finale du véhicule utilisé pour cette étape.

Le constructeur compact de Transport valide les arguments en vérifiant que :

• aucun d'entre eux n'est null,
• la date/heure d'arrivée n'est pas antérieure à celle de départ.

De plus, il copie la liste des arrêts intermédiaires afin de garantir l'immuabilité de la classe.

Transport ne possède aucune autre méthode que celles ajoutées automatiquement aux enregistrements par Java. Notez que ces méthodes ajoutées par Java sont celles qui implémentent les méthodes abstraites de l'interface Leg. Par exemple, la méthode d'accès pour l'attribut depStop, ajoutée automatiquement, implémente la méthode depStop() de Leg.

L'enregistrement Foot, public et imbriqué dans l'interface Leg, représente une étape effectuée à pied. Il implémente donc Leg et possède les attributs suivants :

Stop depStop

l'arrêt de départ de l'étape,

LocalDateTime depTime

la date/heure de départ de l'étape,

Stop arrStop

l'arrêt d'arrivée de l'étape,

LocalDateTime arrTime

la date/heure d'arrivée de l'étape.

Le constructeur compact de Foot fait les mêmes vérifications que celui de Transport. En plus de ce constructeur compact, Foot possède deux méthodes publiques :

List<IntermediateStop> intermediateStops()

qui implémente la méthode abstraite correspondante de l'interface Leg et retourne une liste vide, car une étape à pied ne comporte jamais d'arrêts intermédiaires,

boolean isTransfer()

qui retourne vrai ssi l'étape est un changement au sein de la même gare, c.-à-d. si le nom (!) de l'arrêt de départ est identique à celui de l'arrêt d'arrivée.

Soyez attentifs au fait qu'une étape à pied entre deux arrêts différents peut être considérée comme un changement si ces arrêts ont le même nom. Par exemple, une étape entre la voie 70 et la voie 1 de la gare de Lausanne est un changement, même si les arrêts sont différents. Seul le fait que le nom de (la gare de) ces deux arrêts soit identique compte.

En Java, une interface peut normalement être implémentée par n'importe quelle classe. Par exemple, l'interface Leg déclarée ci-dessus pourrait très bien être implémentée par d'autres classes que celles déclarées à l'intérieur de Leg (Transport et Foot).

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

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

public sealed interface Leg { … }

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 », c.-à-d. le même fichier Java.

La classe FormatterFr du paquetage principal, publique, finale et non instanciable, contient des méthodes statiques permettant d'obtenir la représentation textuelle de différents types de données, au format décrit à la §2.4. Il s'agit de :

String formatDuration(Duration duration)

qui retourne la représentation textuelle, décrite à la §2.4.1, de la durée donnée,

String formatTime(LocalDateTime dateTime)

qui retourne la représentation textuelle, décrite à la §2.4.2, de l'heure de la date/heure donnée,

String formatPlatformName(Stop stop)

qui retourne la représentation textuelle, décrite à la §2.4.3, de la voie ou quai de l'arrêt donné — ou une chaîne vide si l'arrêt en question est une gare, ou si son nom de voie/quai est vide,

String formatLeg(Journey.Leg.Foot footLeg)

qui retourne la représentation textuelle, décrite à la §2.4.4, de l'étape à pied donnée,

String formatLeg(Journey.Leg.Transport leg)

qui retourne la représentation textuelle, décrite à la §2.4.5, de l'étape en transport donnée,

String formatRouteDestination(Journey.Leg.Transport transportLeg)

qui retourne la représentation textuelle, décrite à la §2.4.6, de la ligne et du sens de parcours du véhicule emprunté pour effectuer l'étape donnée.

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.