Vous êtes sur la page 1sur 4

Accueil Cours Exercices Ressources À propos

Cours > Java > Apprendre Java et la Programmation Orientée Objet > Objet

Spécification de l'API Java Monitor Java


w Datadog. See Your
Servers, Clouds Metrics,
On vient tout juste de commencer à manipuler des objets et on peut maintenant se poser plusieurs questions : Apps, and Team. Try Free!
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 Navigation
dans nos programmes. Il est important d'avoir une bonne connaissance de cette librairie standard, afin de ne pas Introduction
toujours réinventer la roue et tout réécrire à partir de rien. Dans un des exemples de la section précédente, on a Introduction aux objets
dû convertir un angle donné en degrés en radians. On aurait pu le faire « manuellement » par la méthode de Créer un objet
Héron par exemple. Mais pourquoi se casser la tête alors qu'il existe une méthode toute faite dans la classe Math Appeler une méthode
? L'API Java
Librairie et package
Dans cette section, on va découvrir la documentation de la librairie standard, communément appelée
Wrapper de types
spécification de l'API Standard Java (Java Standard Application Programmers Interface). On va voir comment
Nombre à précision infinie
utiliser cette documentation pour retrouver rapidement des classes et des informations qui nous permettront de
La classe String
savoir comment créer des objets, appeler des méthodes, etc.
Entrée et sortie standards
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.

Figure 12. Documentation de l'API Standard Java.

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.

Figure 13. La classe Date.

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 :

1 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.

Figure 14. Détail d'un constructeur de la classe Date.

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 :

1 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.

Figure 15. Détail 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.

1 Date first = new Date (2006 - 1900, 0, 4); // Le 4 janvier 2006


2 Date second = new Date (2012 - 1900, 1, 1); // Le 1 février 2012
3
4 System.out.println (first.after (second));
5 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.

Figure 16. Détail de la méthode setMonth de la classe Date.

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.

Figure 17. Détail de la méthode de classe sin de la classe Math.

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 π , elles sont de type double.

Figure 18. Liste des constantes de classe de la classe Math.

Précédent Suivant

Suivez-nous :