UKOnline

Spécification de l'API Java

On vient tout juste de commencer à manipuler des objets et on peut maintenant se poser plusieurs questions : quels sont les objets existants, comment les créer et quels sont les paramètres de création, quelles sont les méthodes qu'on peut appliquer dessus et quels sont les paramètres d'appel, etc.

La librairie standard Java contient une série de classes écrites par d'autres programmeurs et qu'on peut utiliser dans nos programmes. Il est important d'avoir une bonne connaissance de cette librairie standard, afin de ne pas toujours réinventer la roue et tout réécrire à partir de rien. Dans un des exemples de la section précédente, on a dû convertir un angle donné en degrés en radians. On aurait pu le faire « manuellement » par la méthode de Héron par exemple. Mais pourquoi se casser la tête alors qu'il existe une méthode toute faite dans la classe Math ?

Dans cette section, on va découvrir la documentation de la librairie standard, communément appelée spécification de l'API Standard Java (Java Standard Application Programmers Interface). On va voir comment utiliser cette documentation pour retrouver rapidement des classes et des informations qui nous permettront de savoir comment créer des objets, appeler des méthodes, etc.

Vous pouvez télécharger cette documentation depuis le site de Oracle, ou vous pouvez également la consulter en ligne. La documentation de la dernière version du langage Java se trouve à l'URL suivante :

https://docs.oracle.com/javase/8/docs/api/

Cette section se veut plus pratique. Il s'agit plutôt d'un mode d'emploi qui vous permettra d'utiliser efficacement la documentation. Une fois toute la section lue, nous vous conseillons de vous confronter avec la documentation et d'essayer d'y trouver des informations.

Organisation

La figure 12 montre la page d'accueil de la documentation. On peut clairement voir trois parties :

1. La première partie (en haut à gauche) donne la liste des différents packages; on verra de quoi il s'agit à la section suivante. En gros, ce sont des ensembles de classes.
2. La deuxième partie (en bas à gauche) donne la liste des différentes classes faisant partie du package sélectionné dans la première partie.
3. Enfin, la dernière partie (à droite) donne des informations sur la classe sélectionnée dans la seconde partie. On y retrouve entre autre la liste des méthodes qu'on peut appeler, avec la liste des paramètres d'appel.

Retrouver des informations

Pour retrouver des informations sur une classe particulière, il va falloir la retrouver. Supposons que l'on veuille manipuler des dates représentées par un objet de type Date. La première chose à faire, comme on ne sait pas dans quel package elle se trouve, est de cliquer dans la partie package (en haut à gauche) sur All Classes pour voir toutes les classes de la librairie standard.

Une fois cela fait, toutes les classes de la librairie standard sont listées dans la partie classe (en bas à gauche). On y recherche donc la classe Date, mais il y en a deux, laquelle prendre ? Il faut essayer les deux pour trouver celle que l'on cherche. Dans notre cas, c'est la deuxième.

Une fois cliqué sur Date dans la zone en bas à gauche, les informations de la classe s'affichent dans la partie principale à droite. On va maintenant décortiquer toutes les informations présentées. On peut tout d'abord voir en haut de la page les informations principales qui ont été reprises sur la figure 13.

La première information qu'on retrouve est le package dont la classe fait partie. Ici, on voit que la classe Date fait partie du package java.util (1). Comme on le verra dans la section suivante, l'information sur le package est importante en pratique.

Constructeur

Si on continue à descendre dans la page, on tombe sur un tableau nommé Constructor Summary. Ce tableau liste les différents constructeurs, c'est-à-dire les différentes possibilités qui existent pour créer une instance de la classe. On retrouve notamment le constructeur qu'on a utilisé dans les exemples de la section précédente, à savoir :

Date (int year, int month, int date)

Ceci nous indique que pour créer un nouvel objet de type Date, une des possibilités consiste à fournir trois paramètres de création qui sont tous les trois des entiers de type primitif int. Pour savoir ce que représentent ces trois paramètres, il faut accéder à l'information détaillée en cliquant sur le lien. La figure 14 montre les détails de ce constructeur.

Trois parties nous intéressent actuellement. La première (1) reprend le constructeur sélectionné et permet de voir le nombre et le type des paramètres de création. La seconde information (2) est une description en langue naturelle de l'objet qui sera créé par ce constructeur. On apprend ici que l'objet qui sera créé est la date qui représente le jour spécifié par les paramètres year, month et date et que l'heure est fixée à minuit en heure locale. Enfin, la dernière partie (3) donne des précisions sur chaque paramètre de création. Le premier paramètre int year est l'année voulue dont on doit soustraire 1900, le second paramètre int month est le mois donné entre 0 et 11 et enfin le dernier paramètre int date est le jour du mois entre 1 et 31.

Remarquez que cette documentation n'est pas très précise. En effet, en ce qui concerne le mois, la documentation nous apprend qu'il faut le spécifier comme un entier compris entre 0 et 11. Mais on n'a aucune idée de la correspondance. En toute logique, on peut supposer que 0 correspond au mois de janvier, 1 à février... mais rien ne le dit formellement dans le documentation ! On verra au chapitre 7 que la réalisation de la documentation est cruciale, mais que ce n'est pas une tâche facile.

Méthode

Si on revient au tableau des constructeurs et qu'on descend un peu, on tombe sur un autre tableau, celui des méthodes (Method Summary). Ce tableau liste toutes les méthodes qui font partie de la classe. Pour chaque méthode, on peut déjà voir les paramètres d'appel, une courte description de ce que fait la méthode et enfin une indication sur le type de valeur renvoyé.

Dans la classe Date, on voit par exemple l'existence d'une méthode after qui teste si une date est après une autre ou non. La méthode prend un paramètre qui est un objet de type Date. C'est une méthode qui renvoie une valeur de type boolean :

public boolean after(Date when)

Comme pour les constructeurs, on peut avoir plus d'informations en cliquant sur le lien. La figure 15 montre les détails de la méthode after de la classe Date.

Une fois encore, on va se focaliser sur un certain nombre d'informations. On voit directement (1) que la méthode est une méthode qui renvoie un résultat de type primitif booléen (boolean). Celui-ci vaut true si et seulement si la date représentée par l'objet cible se trouve plus tard dans le temps que la date when passée en paramètre à la méthode. On retrouve également les paramètres d'appel (2). On peut voir ici que la méthode after nécessite un paramètre qui doit être un objet de type Date. Enfin, on retrouve une description en langue naturelle de ce que fait la méthode (3).

L'exemple suivant utilise la méthode after de la classe Date.

Date first = new Date (2006 - 1900, 0, 4); // Le 4 janvier 2006 Date second = new Date (2012 - 1900, 1, 1); // Le 1 février 2012 System.out.println (first.after (second)); System.out.println (second.after (first));

L'exécution de ce programme affiche false puis true à l'écran. La méthode after teste si la date représentée par l'objet cible se trouve après, dans le temps, la date représentée par l'objet passé en paramètre. Donc, l'appel first.after (second) teste si first (4 janvier 2006) se trouve après second (1 février 2012). Ce n'est évidemment pas le cas et l'appel de la méthode renvoie donc la valeur false. Par un raisonnement similaire, l'appel second.after (date) renvoie true.

Prenons un autre exemple. Si on revient au tableau qui liste les méthodes de la classe Date, on peut trouver la méthode setMonth dont la documentation détaillée est présentée sur la figure 16.

La méthode setMonth est une méthode void (1), et donc, un appel vers cette méthode ne renverra aucune valeur. De plus, elle prend un paramètre d'appel (2) qui est un entier de type primitif int. Cet entier représente la valeur du mois et doit être comprise entre 0 et 11. Enfin, on retrouve une description en langue naturelle de la méthode (3). On y découvre que la méthode modifie l'objet et change la valeur du mois, c'est donc une méthode mutateur. On apprend également que si la date représente par exemple le 31 octobre et qu'on change le mois en juin, l'objet sera modifié et représentera, non pas le 31 juin, mais le 1 juillet (juin ne comptant que 30 jours). Encore une fois, aucune précision quand à la correspondance entre l'entier et le mois n'est donnée. On doit deviner que 0 correspond à janvier, 1 à février...

Enfin, remarquez qu'il n'y a pas d'information explicite renseignant sur le caractère mutateur ou accesseur des méthodes. On peut retrouver indirectement cette information dans la description en langue naturelle.

Méthode de classe

On a vu à la section précédente qu'il y a des méthodes qu'on doit appeler sans créer d'objets au préalable : les méthodes de classe. On a vu par exemple la méthode sin de la classe Math, qui permet de calculer le sinus d'un angle. Ces méthodes se retrouvent également dans la documentation et on peut les repérer grâce au mot static. La figure 17 montre les détails de la méthode sin.

On voit donc bien qu'il s'agit d'une méthode de classe grâce à la présence de static (1). On peut également voir que l'angle doit être donné en radians (2).

Constante de classe

Enfin, on retrouve également les constantes de classe dans la documentation. Il y a tout d'abord la table Field Summary qui reprend tous les champs de la classe, parmi lesquels les constantes de classe sont identifiées grâce au mot static. En cliquant sur les liens, vous pouvez accéder à une description plus détaillée.

La figure 18 montre les deux constantes de classe de la classe Math. La première représente le nombre d'Euler $e$ et la seconde le nombre $\pi$, elles sont de type double.

• Précédent
• Suivant