Guia das pré-condições da goiaba

1. Visão geral

Neste tutorial, mostraremos como usar a classePreconditions do Google Guava.

A classePreconditions fornece uma lista de métodos estáticos para verificar se um método ou construtor é chamado com valores de parâmetro válidos. Se uma pré-condição falhar, uma exceção personalizada será lançada.

**2. Preconditions do Google Guava**

Cada método estático na classePreconditions tem três variantes:

Sem argumentos. Exceções são lançadas sem uma mensagem de erro
Um argumentoObject extra agindo como uma mensagem de erro. Exceções são lançadas com uma mensagem de erro
Um argumento String extra, com um número arbitrário de argumentosObject adicionais agindo como uma mensagem de erro com um espaço reservado. Este se comporta um pouco comoprintf, mas para compatibilidade e eficiência do GWT permite apenas indicadores de%s

Vamos dar uma olhada em como usar a classePreconditions.

2.1. Dependência do Maven

Vamos começar adicionando a dependência da biblioteca Guava do Google empom.xml:


    com.google.guava
    guava
    21.0

A versão mais recente da dependência pode ser verificadahere.

3. checkArgument

O métodoThecheckArgument doPreconditions class garante a veracidade dos parâmetros passados para o método de chamada. Este método aceita uma condição booleana e lança umIllegalArgumentException quando a condição é falsa.

Vamos ver como podemos usar esse método com alguns exemplos.

3.1. Sem Mensagem de Erro

Podemos usarcheckArgument sem passar nenhum parâmetro extra para o métodocheckArgument:

@Test
public void whenCheckArgumentEvaluatesFalse_throwsException() {
    int age = -18;

    assertThatThrownBy(() -> Preconditions.checkArgument(age > 0))
      .isInstanceOf(IllegalArgumentException.class)
      .hasMessage(null).hasNoCause();
}

3.2. Com uma mensagem de erro

Podemos obter uma mensagem de erro significativa do métodocheckArgument passando uma mensagem de erro:

@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. Com uma mensagem de erro de modelo

Podemos obter uma mensagem de erro significativa junto com os dados dinâmicos do métodocheckArgument passando uma mensagem de erro:

@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

O métodocheckElementIndex verifica se um índice é um índice válido em uma lista, string ou array de um tamanho especificado. Um índice de elemento pode variar de 0 inclusive a tamanho exclusivo. Você não passa uma lista, string ou array diretamente, apenas passa seu tamanho. Este método lança umIndexOutOfBoundsException se o índice não for um índice de elemento válido, caso contrário, ele retorna um índice que está sendo passado para o método.

Vamos ver como podemos usar esse método, mostrando uma mensagem de erro significativa do métodocheckElementIndex, passando uma mensagem de erro quando ele lança uma exceção:

@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

O métodocheckNotNull verifica se um valor fornecido como parâmetro é nulo. Ele retorna o valor que foi verificado. Se o valor que foi passado para este método for nulo, umNullPointerException será lançado.

A seguir, mostraremos como usar esse método, mostrando como obter uma mensagem de erro significativa do métodocheckNotNull passando uma mensagem de erro:

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

Também podemos obter uma mensagem de erro significativa com base em dados dinâmicos do métodocheckNotNull passando um parâmetro para a mensagem de erro:

@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

O métodocheckPositionIndex verifica se um índice passado como argumento para este método é um índice válido em uma lista, string ou array de um tamanho especificado. Um índice de posição pode variar de 0 inclusive a tamanho inclusive. Você não passa a lista, string ou array diretamente, apenas passa seu tamanho.

Este método lança umIndexOutOfBoundsException se o índice passado não estiver entre 0 e o tamanho fornecido, caso contrário, ele retorna o valor do índice.

Vamos ver como podemos obter uma mensagem de erro significativa do métodocheckPositionIndex:

@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

O métodocheckState verifica a validade do estado de um objeto e não depende dos argumentos do método. Por exemplo, umIterator pode usar isso para verificar se next foi chamado antes de qualquer chamada para remover. Este método lança umIllegalStateException se o estado de um objeto (valor booleano passado como um argumento para o método) estiver em um estado inválido.

Vamos ver como podemos usar esse método, mostrando uma mensagem de erro significativa do métodocheckState, passando uma mensagem de erro quando ele lança uma exceção:

@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. Conclusão

Neste tutorial, ilustramos os métodos da classePreConditions da biblioteca Guava. A classePreconditions fornece uma coleção de métodos estáticos que são usados para validar se um método ou construtor é chamado com valores de parâmetro válidos.

O código pertencente aos exemplos acima pode ser encontrado emthe GitHub project - este é um projeto baseado em Maven, portanto, deve ser fácil de importar e executar como está.

TOC

Guia das pré-condições da goiaba