Apache Commons для Java: полное руководство с примерами

Что такое Apache Commons и зачем он нужен?

Apache Commons — это крупнейший проект Apache Software Foundation, представляющий собой набор многократно используемых, проверенных временем Java-компонентов. Это не одна библиотека, а целое семейство библиотек (около 40+ модулей), которые решают типовые задачи, с которыми сталкивается каждый Java-разработчик.

Зачем нужен Apache Commons? Стандартная библиотека Java (JDK) часто предоставляет лишь базовый функционал. Например, для работы со строками, файлами, коллекциями или математическими операциями вам приходится писать много boilerplate-кода. Apache Commons берет на себя эту рутину, предлагая готовые, оптимизированные и хорошо протестированные утилиты. Это позволяет:

• Уменьшить количество кода: Вместо 10 строк вы пишете 1 вызов метода.
• Повысить надежность: Код из Commons используется миллионами проектов и прошел многолетнее тестирование.
• Избежать ошибок: Многие утилиты корректно обрабатывают null-значения, что спасает от NullPointerException.
• Ускорить разработку: Не нужно изобретать велосипед для стандартных задач.

Наиболее популярные модули: Commons Lang (работа со строками, числами), Commons IO (работа с файлами и потоками), Commons Collections (расширенные коллекции) и Commons Math (математические и статистические функции).

Установка Apache Commons

В отличие от Python (где используется pip install), в Java библиотеки подключаются через системы управления зависимостями, такие как Maven или Gradle. Apache Commons не устанавливается одной командой — нужно подключать конкретный модуль.

Установка через Maven (самый популярный способ)

Добавьте зависимость в файл pom.xml. Для примера установим модули Commons Lang3 и Commons IO:

<dependencies>
    <!-- Commons Lang3 (для работы со строками) -->
    <dependency>
        <groupId>org.apache.commons</groupId>
        <artifactId>commons-lang3</artifactId>
        <version>3.14.0</version>
    </dependency>
    
    <!-- Commons IO (для работы с файлами) -->
    <dependency>
        <groupId>commons-io</groupId>
        <artifactId>commons-io</artifactId>
        <version>2.16.1</version>
    </dependency>
</dependencies>

Установка через Gradle

Добавьте строки в файл build.gradle:

dependencies {
    implementation 'org.apache.commons:commons-lang3:3.14.0'
    implementation 'commons-io:commons-io:2.16.1'
}

Установка вручную (без Maven/Gradle)

Скачайте JAR-файлы с официального сайта commons.apache.org и добавьте их в classpath вашего проекта (например, через настройки IDE). Этот способ не рекомендуется для крупных проектов.

Быстрый старт: пример кода

Давайте напишем простую программу, которая использует два модуля: Commons Lang3 для работы со строками и Commons IO для чтения файла.

import org.apache.commons.lang3.StringUtils;
import org.apache.commons.io.FileUtils;
import java.io.File;
import java.io.IOException;

public class QuickStart {
    public static void main(String[] args) {
        // Пример 1: Проверка строки на пустоту
        String text = "   Hello, Apache Commons!   ";
        if (StringUtils.isNotBlank(text)) {
            System.out.println("Строка не пустая и не состоит из пробелов.");
        }

        // Пример 2: Удаление пробелов и перевод в верхний регистр
        String cleaned = StringUtils.trim(text).toUpperCase();
        System.out.println("Очищенная строка: " + cleaned);

        // Пример 3: Чтение файла в строку (создайте файл test.txt рядом)
        try {
            File file = new File("test.txt");
            String content = FileUtils.readFileToString(file, "UTF-8");
            System.out.println("Содержимое файла: " + content);
        } catch (IOException e) {
            System.out.println("Файл не найден. Создайте test.txt.");
        }
    }
}

Этот код демонстрирует, как легко избежать ручных проверок на null и пробелы (метод isNotBlank) и как просто прочитать файл целиком (FileUtils.readFileToString).

Основные методы и функции (минимум 10)

Рассмотрим ключевые методы из самых популярных модулей Apache Commons.

1. StringUtils.isBlank() (Commons Lang3)

Что делает: Проверяет, является ли строка пустой, null или состоящей только из пробелов (whitespace). Это надежнее, чем str == null || str.isEmpty().

Параметры: CharSequence cs — проверяемая строка.

Возвращает: boolean (true, если строка пустая, null или содержит только пробелы).

import org.apache.commons.lang3.StringUtils;

public class ExampleBlank {
    public static void main(String[] args) {
        System.out.println(StringUtils.isBlank(null));    // true
        System.out.println(StringUtils.isBlank(""));      // true
        System.out.println(StringUtils.isBlank("   "));   // true
        System.out.println(StringUtils.isBlank("Hello")); // false
    }
}

2. StringUtils.capitalize() (Commons Lang3)

Что делает: Преобразует первую букву строки в заглавную. Остальные символы остаются без изменений.

Параметры: String str — исходная строка.

Возвращает: String — строку с заглавной первой буквой.

public class ExampleCapitalize {
    public static void main(String[] args) {
        String result = StringUtils.capitalize("hello world");
        System.out.println(result); // "Hello world"
    }
}

3. StringUtils.join() (Commons Lang3)

Что делает: Объединяет элементы массива или коллекции в одну строку с указанным разделителем. Очень удобно для создания CSV или логов.

Параметры: Object[] array (или Iterable), String separator.

Возвращает: String — объединенная строка.

import java.util.Arrays;
import java.util.List;

public class ExampleJoin {
    public static void main(String[] args) {
        List<String> items = Arrays.asList("Java", "Python", "C++");
        String result = StringUtils.join(items, ", ");
        System.out.println(result); // "Java, Python, C++"
    }
}

4. StringUtils.defaultIfEmpty() (Commons Lang3)

Что делает: Возвращает строку, если она не пустая (не null и не ""), иначе возвращает значение по умолчанию. Полезно для избежания NullPointerException.

Параметры: String str, String defaultStr.

Возвращает: String — исходную строку или значение по умолчанию.

public class ExampleDefault {
    public static void main(String[] args) {
        String name = null;
        String safeName = StringUtils.defaultIfEmpty(name, "Гость");
        System.out.println(safeName); // "Гость"
    }
}

5. FileUtils.readFileToString() (Commons IO)

Что делает: Читает содержимое файла целиком в строку. Автоматически закрывает потоки, что предотвращает утечки ресурсов.

Параметры: File file, String encoding (например, "UTF-8").

Возвращает: String — содержимое файла.

import java.io.File;
import java.io.IOException;

public class ExampleReadFile {
    public static void main(String[] args) throws IOException {
        File file = new File("data.txt");
        String content = FileUtils.readFileToString(file, "UTF-8");
        System.out.println(content);
    }
}

6. FileUtils.copyFile() (Commons IO)

Что делает: Копирует файл из одного места в другое. Создает родительские директории, если они не существуют.

Параметры: File srcFile, File destFile.

Возвращает: void.

public class ExampleCopyFile {
    public static void main(String[] args) throws IOException {
        File source = new File("source.txt");
        File dest = new File("backup/source_copy.txt");
        FileUtils.copyFile(source, dest);
        System.out.println("Файл скопирован.");
    }
}

7. FileUtils.deleteDirectory() (Commons IO)

Что делает: Рекурсивно удаляет директорию со всем содержимым. Безопаснее, чем ручное удаление через File.delete().

Параметры: File directory.

Возвращает: void (выбрасывает IOException при ошибке).

public class ExampleDeleteDir {
    public static void main(String[] args) throws IOException {
        File dir = new File("temp_folder");
        if (dir.exists()) {
            FileUtils.deleteDirectory(dir);
            System.out.println("Директория удалена.");
        }
    }
}

8. CollectionUtils.isNotEmpty() (Commons Collections4)

Что делает: Проверяет, что коллекция не является null и содержит хотя бы один элемент. Аналог StringUtils.isNotBlank() для коллекций.

Параметры: Collection<?> coll.

Возвращает: boolean.

import org.apache.commons.collections4.CollectionUtils;
import java.util.ArrayList;
import java.util.List;

public class ExampleCollection {
    public static void main(String[] args) {
        List<String> list = new ArrayList<>();
        System.out.println(CollectionUtils.isNotEmpty(list)); // false
        list.add("item");
        System.out.println(CollectionUtils.isNotEmpty(list)); // true
    }
}

9. NumberUtils.toInt() (Commons Lang3)

Что делает: Безопасно преобразует строку в целое число. Если строка не является числом или равна null, возвращает значение по умолчанию (вместо выброса NumberFormatException).

Параметры: String str, int defaultValue.

Возвращает: int.

public class ExampleToInt {
    public static void main(String[] args) {
        int a = NumberUtils.toInt("123", 0);
        int b = NumberUtils.toInt("abc", -1);
        System.out.println(a); // 123
        System.out.println(b); // -1 (значение по умолчанию)
    }
}

10. ObjectUtils.firstNonNull() (Commons Lang3)

Что делает: Возвращает первый не-null объект из переданных. Позволяет избежать цепочек тернарных операторов.

Параметры: T... values (varargs).

Возвращает: T — первый не-null объект.

public class ExampleFirstNonNull {
    public static void main(String[] args) {
        String result = ObjectUtils.firstNonNull(null, null, "Hello", "World");
        System.out.println(result); // "Hello"
    }
}

Реальный практический пример использования

Представим задачу: нужно обработать лог-файл сервера. Файл может