Руководство по предварительным условиям гуавы

1. Обзор

В этом руководстве мы покажем, как использовать класс предварительных условий Google Guava .

Класс Preconditions предоставляет список статических методов для проверки того, вызывается ли метод или конструктор с допустимыми значениями параметров. Если предварительное условие не выполняется, генерируется адаптированное исключение.

2. Предварительные условия Google Guava ``

Каждый статический метод в классе Preconditions имеет три варианта:

• Никаких аргументов. Исключения выбрасываются без сообщения об ошибке
• Дополнительный аргумент объекта , действующий как сообщение об ошибке. Исключения выдаются с сообщением об ошибке
• Дополнительный аргумент String с произвольным количеством дополнительных аргументов Object , действующих как сообщение об ошибке с заполнителем. Это немного похоже на printf , но для совместимости и эффективности GWT позволяет использовать только индикаторы %s

Давайте посмотрим, как использовать класс Preconditions .

2.1. Зависимость от Maven

Начнем с добавления зависимости библиотеки Google Guava в pom.xml :

<dependency>
    <groupId>com.google.guava</groupId>
    <artifactId>guava</artifactId>
    <version>31.0.1-jre</version>
</dependency>

Последнюю версию зависимости можно проверить здесь .

3. проверитьаргумент

Метод checkArgument класса Preconditions обеспечивает достоверность параметров , передаваемых вызывающему методу. Этот метод принимает логическое условие и создает исключение IllegalArgumentException , если условие ложно.

Давайте посмотрим, как мы можем использовать этот метод на нескольких примерах.

3.1. Без сообщения об ошибке

Мы можем использовать checkArgument без передачи какого-либо дополнительного параметра методу checkArgument :

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

3.2. С сообщением об ошибке

Мы можем получить осмысленное сообщение об ошибке из метода checkArgument , передав сообщение об ошибке:

@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. С сообщением об ошибке шаблона

Мы можем получить осмысленное сообщение об ошибке вместе с динамическими данными из метода checkArgument , передав сообщение об ошибке:

@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 проверяет, что индекс является допустимым индексом в списке, строке или массиве указанного размера. Индекс элемента может варьироваться от 0 включительно до размера без учета размера. Вы не передаете список, строку или массив напрямую, вы просто передаете их размер. Этот метод создает исключение IndexOutOfBoundsException , если индекс не является допустимым индексом элемента, в противном случае он возвращает индекс, который передается методу.

Давайте посмотрим, как мы можем использовать этот метод, показав значимое сообщение об ошибке из метода checkElementIndex , передав сообщение об ошибке, когда он выдает исключение:

@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 проверяет, является ли значение, указанное в качестве параметра, нулевым. Он возвращает проверенное значение. Если значение, переданное этому методу, равно null, создается исключение NullPointerException .

Далее мы собираемся показать, как использовать этот метод, показав, как получить значимое сообщение об ошибке из метода checkNotNull , передав сообщение об ошибке:

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

Мы также можем получить осмысленное сообщение об ошибке на основе динамических данных из метода checkNotNull , передав в сообщение об ошибке параметр:

@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 проверяет, что индекс, переданный в качестве аргумента этому методу, является допустимым индексом в списке, строке или массиве указанного размера. Индекс положения может варьироваться от 0 включительно до размера включительно. Вы не передаете список, строку или массив напрямую, вы просто передаете их размер.

Этот метод генерирует исключение IndexOutOfBoundsException , если переданный индекс не находится между 0 и заданным размером, в противном случае он возвращает значение индекса.

Давайте посмотрим, как мы можем получить осмысленное сообщение об ошибке из метода 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 проверяет правильность состояния объекта и не зависит от аргументов метода. Например, итератор может использовать это, чтобы проверить, был ли вызван next перед любым вызовом для удаления. Этот метод создает исключение IllegalStateException , если состояние объекта (логическое значение, переданное в качестве аргумента метода) находится в недопустимом состоянии.

Давайте посмотрим, как мы можем использовать этот метод, показав значимое сообщение об ошибке из метода checkState , передав сообщение об ошибке, когда он выдает исключение:

@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. Заключение

В этом руководстве мы проиллюстрировали методы класса PreConditions из библиотеки Guava. Класс Preconditions предоставляет набор статических методов, которые используются для проверки того, что метод или конструктор вызывается с допустимыми значениями параметров.

Код, относящийся к приведенным выше примерам, можно найти в проекте GitHub — это проект на основе Maven, поэтому его легко импортировать и запускать как есть.