Horaire aplati

La classe Structure du sous-paquetage timetable.mapped a pour but de faciliter la description de la structure des données aplaties. Ainsi, une fois terminée, cette classe permet d'écrire le code suivant pour décrire les noms alternatifs des gares :

int ALIAS_ID = 0;
int STATION_NAME_ID = 1;

Structure STRUCTURE = new Structure(
    field(ALIAS_ID, U16),
    field(STATION_NAME_ID, U16));

qui est très proche de la table donnée à la §2.4, les constantes ALIAS_ID et STATION_NAME_ID contenant les index (colonne I) des différents champs.

Une fois cette définition écrite, il est par exemple possible de calculer l'index, dans le tableau d'octets contenant les données aplaties, du premier octet de l'index de chaîne du nom de gare du second nom alternatif d'une table (celui d'index 1), ainsi :

int offset = STRUCTURE.offset(STATION_NAME_ID, 1);

qui vaut 6.

Structure possède un type énuméré imbriqué public nommé FieldType représentant les trois types de champs possibles, à savoir U8, U16 et S32.

De plus, elle possède un enregistrement imbriqué public nommé Field, qui représente un champ et possède les deux attributs suivants, dans l'ordre :

int index

l'index du champ dans la structure (colonne I dans les tables plus haut),

FieldType type

le type du champ.

Field possède un constructeur compact qui lève une NullPointerException ssi type est null.

Structure possède de plus une méthode publique et statique dont le but est d'alléger un peu la création d'instances de Field, en omettant le new, comme dans l'exemple plus haut :

Field field(int index, FieldType type)

qui retourne une instance de Field avec les attributs donnés.

Structure possède un unique constructeur, qui prend en arguments la description des différents champs de la structure :

Structure(Field... fields)

qui retourne une structure dont les champs sont ceux donnés, ou lève une IllegalArgumentException si ces champs ne sont pas donnés dans l'ordre — c.-à-d. si le premier d'entre eux n'est pas celui d'index 0, le second celui d'index 1, etc.

int totalSize()

qui retourne la taille totale, en octets, de la structure — p. ex. 10 pour celle correspondant aux gares,

int offset(int fieldIndex, int elementIndex)

qui retourne l'index, dans le tableau d'octets contenant les données aplaties, du premier octet du champ d'index fieldIndex de l'élément d'index elementIndex ; lève IndexOutOfBoundsException si l'index du champ est invalide.

La classe StructuredBuffer du sous-paquetage timetable.mapped, représente un « tableau d'octets structuré ». Son but est d'offrir un accès agréable à des données aplaties stockées dans un tableau d'octets, et dont la structure est décrite par une instance de Structure.

Une fois cette classe terminée, il sera possible de l'utiliser par exemple ainsi pour obtenir l'index de chaîne du nom alternatif d'index 1 :

StructuredBuffer buffer = …;
int stationNameStringIndex = buffer.getU16(STATION_NAME_ID, 1);

Dans l'exemple de la §2.6, stationNameStringIndex vaudrait 3, car c'est l'index de chaîne Ins.

StructuredBuffer possède un unique constructeur public :

StructuredBuffer(Structure structure, ByteBuffer buffer)

qui construit un tableau structuré dont les éléments ont la structure donnée, et dont les octets sont stockés dans le « tableau » buffer, ou lève une IllegalArgumentException si le nombre d'octets de ce tableau n'est pas un multiple de la taille totale de la structure.

La classe ByteBuffer, qui appartient à la bibliothèque Java, est décrite dans les conseils de programmation ci-dessous.

En plus de son constructeur, StructuredBuffer offre les méthodes publiques suivantes :

int size()

qui retourne le nombre d'éléments que contient le tableau, p. ex. 3 pour les voies/quais de la §2.6,

int getU8(int fieldIndex, int elementIndex)

qui retourne l'entier U8 correspondant au champ d'index fieldIndex de l'élément d'index elementIndex du tableau, ou lève IndexOutOfBoundsException si l'un des deux index est invalide,

int getU16(int fieldIndex, int elementIndex)

qui fait la même chose que getU8 mais pour un champ de type U16,

int getS32(int fieldIndex, int elementIndex)

qui fait la même chose que getU8 mais pour un champ de type S32.

N'oubliez pas que les valeurs retournées par getU8 et getU16 doivent être positives, car les champs de ces deux types sont interprétés de manière non signée. C'est la raison pour laquelle ces méthodes retournent une valeur de type int et pas byte ou short.

La classe BufferedStations du sous-paquetage timetable.mapped, publique et finale, implémente l'interface Stations et permet d'accéder à une table de gares représentée de manière aplatie comme décrit à la §2.3. Elle possède un unique constructeur public :

BufferedStations(List<String> stringTable, ByteBuffer buffer)

qui construit une instance donnant accès aux données aplaties disponibles dans le tableau buffer, en utilisant la table de chaînes stringTable pour déterminer la valeur des chaînes référencées par ces données.

Les seules méthodes publiques offertes par cette classe sont les versions concrètes des méthodes abstraites de Stations.

La classe BufferedStationAliasess du sous-paquetage timetable.mapped, publique et finale, implémente l'interface StationAliases et permet d'accéder à une table de noms alternatifs de gares représentée de manière aplatie comme décrit à la §2.4. Elle possède un unique constructeur public :

BufferedStationAliases(List<String> stringTable, ByteBuffer buffer)

qui construit une instance donnant accès aux données aplaties disponibles dans le tableau buffer, en utilisant la table de chaînes stringTable pour déterminer la valeur des chaînes référencées par ces données.

Les seules méthodes publiques offertes par cette classe sont les versions concrètes des méthodes abstraites de StationAliases.

La classe BufferedPlatforms du sous-paquetage timetable.mapped, publique et finale, implémente l'interface Platforms et permet d'accéder à une table de voies ou quais représentée de manière aplatie comme décrit à la §2.5. Elle possède un unique constructeur public :

BufferedPlatforms(List<String> stringTable, ByteBuffer buffer)

qui construit une instance donnant accès aux données aplaties disponibles dans le tableau buffer, en utilisant la table de chaînes stringTable pour déterminer la valeur des chaînes référencées par ces données.

Les seules méthodes publiques offertes par cette classe sont les versions concrètes des méthodes abstraites de Platforms.

Comme d'habitude, nous ne vous fournissons plus de tests mais un fichier de vérification de signatures à importer dans votre projet.

Pour écrire vos tests, vous pouvez entre autres vous aider des valeurs d'exemple données à la §2.6. Grâce à la classe HexFormat de la bibliothèque Java, il est très simple d'obtenir le tableau d'octets correspondant à une chaîne ayant le même format que celui de cette section. Par exemple, pour obtenir le tableau d'octets des noms alternatifs, on peut procéder ainsi :

HexFormat hexFormat = HexFormat.ofDelimiter(" ");
byte[] bytes = hexFormat.parseHex("00 05 00 04 00 02 00 03");

Une fois ce tableau obtenu, la méthode wrap de ByteBuffer permet d'obtenir une valeur de type ByteBuffer qui peut directement être passée au constructeur de BufferedStationAliases.