Guida alle precondizioni di Guava

1. Panoramica

In questo tutorial, mostreremo come utilizzare la classe Preconditions di Google Guava .

La classe Preconditions fornisce un elenco di metodi statici per verificare che un metodo o un costruttore venga richiamato con valori di parametro validi. Se una precondizione non riesce, viene generata un'eccezione personalizzata.

2. Prerequisiti di Google Guava

Ogni metodo statico nella classe Preconditions ha tre varianti:

  • Nessun argomento. Le eccezioni vengono generate senza un messaggio di errore
  • Un argomento Object aggiuntivo che funge da messaggio di errore. Le eccezioni vengono generate con un messaggio di errore
  • Un argomento String aggiuntivo, con un numero arbitrario di argomenti Object aggiuntivi che agiscono come un messaggio di errore con un segnaposto. Si comporta un po 'come printf , ma per la compatibilità e l'efficienza di GWT consente solo gli indicatori % s

Diamo un'occhiata a come utilizzare la classe Preconditions .

2.1. Dipendenza da Maven

Iniziamo aggiungendo la dipendenza della libreria Guava di Google nel pom.xml :

 com.google.guava guava 29.0-jre 

L'ultima versione della dipendenza può essere verificata qui.

3. checkArgument

Il metodo checkArgument della classe Preconditions garantisce la veridicità dei parametri passati al metodo chiamante. Questo metodo accetta una condizione booleana e genera un'eccezione IllegalArgumentException quando la condizione è falsa.

Vediamo come possiamo utilizzare questo metodo con alcuni esempi.

3.1. Senza un messaggio di errore

Possiamo usare checkArgument senza passare alcun parametro aggiuntivo al metodo checkArgument :

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

3.2. Con un messaggio di errore

Possiamo ottenere un messaggio di errore significativo dal metodo checkArgument passando un messaggio di errore:

@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. Con un messaggio di errore del modello

Possiamo ottenere un messaggio di errore significativo insieme ai dati dinamici dal metodo checkArgument passando un messaggio di errore:

@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

Il metodo checkElementIndex controlla che un indice sia un indice valido in un elenco, una stringa o un array di una dimensione specificata. L'indice di un elemento può variare da 0 incluso a dimensione esclusiva. Non si passa direttamente un elenco, una stringa o un array, ma solo la sua dimensione. Questo metodo genera un'eccezione IndexOutOfBoundsException se l'indice non è un indice di elemento valido, altrimenti restituisce un indice che viene passato al metodo.

Vediamo come possiamo utilizzare questo metodo mostrando un messaggio di errore significativo dal metodo checkElementIndex passando un messaggio di errore quando genera un'eccezione:

@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

Il metodo checkNotNull controlla se un valore fornito come parametro è nullo. Restituisce il valore che è stato controllato. Se il valore passato a questo metodo è null, viene generata un'eccezione NullPointerException .

Successivamente, mostreremo come utilizzare questo metodo mostrando come ottenere un messaggio di errore significativo dal metodo checkNotNull passando un messaggio di errore:

@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(); }

Possiamo anche ottenere un messaggio di errore significativo basato su dati dinamici dal metodo checkNotNull passando un parametro al messaggio di errore:

@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

Il metodo checkPositionIndex verifica che un indice passato come argomento a questo metodo sia un indice valido in un elenco, una stringa o un array di una dimensione specificata. Un indice di posizione può variare da 0 incluso a dimensione inclusa. Non si passa direttamente l'elenco, la stringa o l'array, ma solo la sua dimensione.

Questo metodo genera un'eccezione IndexOutOfBoundsException se l'indice passato non è compreso tra 0 e la dimensione data, altrimenti restituisce il valore dell'indice.

Vediamo come possiamo ottenere un messaggio di errore significativo dal metodo 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

Il metodo checkState verifica la validità dello stato di un oggetto e non dipende dagli argomenti del metodo. Ad esempio, un Iterator potrebbe utilizzarlo per verificare che next sia stato chiamato prima di qualsiasi chiamata per la rimozione. Questo metodo genera un'eccezione IllegalStateException se lo stato di un oggetto (valore booleano passato come argomento al metodo) è in uno stato non valido.

Vediamo come possiamo utilizzare questo metodo mostrando un messaggio di errore significativo dal metodo checkState passando un messaggio di errore quando genera un'eccezione:

@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. Conclusione

In questo tutorial, abbiamo illustrato i metodi della classe PreConditions dalla libreria Guava. La classe Preconditions fornisce una raccolta di metodi statici utilizzati per convalidare che un metodo o un costruttore viene richiamato con valori di parametro validi.

Il codice appartenente agli esempi precedenti può essere trovato nel progetto GitHub: questo è un progetto basato su Maven, quindi dovrebbe essere facile da importare ed eseguire così com'è.