Guide des conditions préalables à la goyave

1. Vue d'ensemble

Dans ce didacticiel, nous montrerons comment utiliser la classe Preconditions de Google Guava .

La classe Preconditions fournit une liste de méthodes statiques pour vérifier qu'une méthode ou un constructeur est appelé avec des valeurs de paramètre valides. Si une condition préalable échoue, une exception personnalisée est levée.

2. Conditions préalables de Google Guava

Chaque méthode statique de la classe Preconditions a trois variantes:

  • Aucun argument. Les exceptions sont levées sans message d'erreur
  • Un argument Object supplémentaire agissant comme un message d'erreur. Les exceptions sont lancées avec un message d'erreur
  • Un argument String supplémentaire, avec un nombre arbitraire d' arguments Object supplémentaires agissant comme un message d'erreur avec un espace réservé. Cela se comporte un peu comme printf , mais pour la compatibilité et l'efficacité GWT, il n'autorise que les indicateurs % s

Voyons comment utiliser la classe Preconditions .

2.1. Dépendance de Maven

Commençons par ajouter la dépendance de la bibliothèque Guava de Google dans le pom.xml :

 com.google.guava guava 29.0-jre 

La dernière version de la dépendance peut être vérifiée ici.

3. checkArgument

La méthode checkArgument de la classe Preconditions garantit la véracité des paramètres passés à la méthode appelante. Cette méthode accepte une condition booléenne et lève une IllegalArgumentException lorsque la condition est fausse.

Voyons comment nous pouvons utiliser cette méthode avec quelques exemples.

3.1. Sans message d'erreur

Nous pouvons utiliser checkArgument sans passer de paramètre supplémentaire à la méthode checkArgument :

@Test public void whenCheckArgumentEvaluatesFalse_throwsException() { int age = -18; assertThatThrownBy(() -> Preconditions.checkArgument(age > 0)) .isInstanceOf(IllegalArgumentException.class) .hasMessage(null).hasNoCause(); }

3.2. Avec un message d'erreur

Nous pouvons obtenir un message d'erreur significatif de la méthode checkArgument en passant un message d'erreur:

@Test public void givenErrorMsg_whenCheckArgEvalsFalse_throwsException() { int age = -18; String message = "Age can't be zero or less than zero."; assertThatThrownBy(() -> Preconditions.checkArgument(age > 0, message)) .isInstanceOf(IllegalArgumentException.class) .hasMessage(message).hasNoCause(); }

3.3. Avec un message d'erreur de modèle

Nous pouvons obtenir un message d'erreur significatif avec des données dynamiques de la méthode checkArgument en passant un message d'erreur:

@Test public void givenTemplateMsg_whenCheckArgEvalsFalse_throwsException() { int age = -18; String message = "Age should be positive number, you supplied %s."; assertThatThrownBy( () -> Preconditions.checkArgument(age > 0, message, age)) .isInstanceOf(IllegalArgumentException.class) .hasMessage(message, age).hasNoCause(); } 

4. checkElementIndex

La méthode checkElementIndex vérifie qu'un index est un index valide dans une liste, une chaîne ou un tableau d'une taille spécifiée. Un indice d'élément peut aller de 0 inclus à taille exclusive. Vous ne passez pas directement une liste, une chaîne ou un tableau, vous passez simplement sa taille. Cette méthode lève une IndexOutOfBoundsException si l'index n'est pas un index d'élément valide, sinon elle renvoie un index qui est passé à la méthode.

Voyons comment nous pouvons utiliser cette méthode en affichant un message d'erreur significatif de la méthode checkElementIndex en passant un message d'erreur lorsqu'il lève une exception:

@Test public void givenArrayAndMsg_whenCheckElementEvalsFalse_throwsException() { int[] numbers = { 1, 2, 3, 4, 5 }; String message = "Please check the bound of an array and retry"; assertThatThrownBy(() -> Preconditions.checkElementIndex(6, numbers.length - 1, message)) .isInstanceOf(IndexOutOfBoundsException.class) .hasMessageStartingWith(message).hasNoCause(); }

5. checkNotNull

La méthode checkNotNull vérifie si une valeur fournie en tant que paramètre est nulle. Il renvoie la valeur qui a été vérifiée. Si la valeur qui a été transmise à cette méthode est null, une NullPointerException est levée.

Ensuite, nous allons montrer comment utiliser cette méthode en montrant comment obtenir un message d'erreur significatif de la méthode checkNotNull en passant un message d'erreur:

@Test public void givenNullString_whenCheckNotNullWithMessage_throwsException () { String nullObject = null; String message = "Please check the Object supplied, its null!"; assertThatThrownBy(() -> Preconditions.checkNotNull(nullObject, message)) .isInstanceOf(NullPointerException.class) .hasMessage(message).hasNoCause(); }

Nous pouvons également obtenir un message d'erreur significatif basé sur des données dynamiques de la méthode checkNotNull en passant un paramètre au message d'erreur:

@Test public void whenCheckNotNullWithTemplateMessage_throwsException() { String nullObject = null; String message = "Please check the Object supplied, its %s!"; assertThatThrownBy( () -> Preconditions.checkNotNull(nullObject, message, new Object[] { null })) .isInstanceOf(NullPointerException.class) .hasMessage(message, nullObject).hasNoCause(); }

6. checkPositionIndex

La méthode checkPositionIndex vérifie qu'un index passé en argument à cette méthode est un index valide dans une liste, une chaîne ou un tableau d'une taille spécifiée. Un indice de position peut aller de 0 inclus à taille incluse. Vous ne passez pas directement la liste, la chaîne ou le tableau, vous passez simplement sa taille.

Cette méthode lève une IndexOutOfBoundsException si l'index passé n'est pas compris entre 0 et la taille donnée, sinon elle renvoie la valeur d'index.

Voyons comment nous pouvons obtenir un message d'erreur significatif de la méthode checkPositionIndex :

@Test public void givenArrayAndMsg_whenCheckPositionEvalsFalse_throwsException() { int[] numbers = { 1, 2, 3, 4, 5 }; String message = "Please check the bound of an array and retry"; assertThatThrownBy( () -> Preconditions.checkPositionIndex(6, numbers.length - 1, message)) .isInstanceOf(IndexOutOfBoundsException.class) .hasMessageStartingWith(message).hasNoCause(); }

7. checkState

La méthode checkState vérifie la validité de l'état d'un objet et ne dépend pas des arguments de la méthode. Par exemple, un itérateur peut utiliser ceci pour vérifier que next a été appelé avant tout appel à supprimer. Cette méthode lève une IllegalStateException si l'état d'un objet (valeur booléenne transmise comme argument à la méthode) est dans un état non valide.

Voyons comment nous pouvons utiliser cette méthode en affichant un message d'erreur significatif de la méthode checkState en passant un message d'erreur lorsqu'il lève une exception:

@Test public void givenStatesAndMsg_whenCheckStateEvalsFalse_throwsException() { int[] validStates = { -1, 0, 1 }; int givenState = 10; String message = "You have entered an invalid state"; assertThatThrownBy( () -> Preconditions.checkState( Arrays.binarySearch(validStates, givenState) > 0, message)) .isInstanceOf(IllegalStateException.class) .hasMessageStartingWith(message).hasNoCause(); }

8. Conclusion

Dans ce tutoriel, nous avons illustré les méthodes de la classe PreConditions de la bibliothèque Guava. La classe Preconditions fournit une collection de méthodes statiques utilisées pour valider qu'une méthode ou un constructeur est appelé avec des valeurs de paramètre valides.

Le code appartenant aux exemples ci-dessus se trouve dans le projet GitHub - il s'agit d'un projet basé sur Maven, il devrait donc être facile à importer et à exécuter tel quel.